@jspsych/extension-tobii 0.1.1

package/src/validation.ts

@@ -0,0 +1,60 @@
+/**
+ * Data validation utilities
+ */
+
+import type { GazeData, CalibrationPoint, CalibrationResult, ValidationResult } from './types';
+
+/**
+ * Validate gaze data point
+ */
+export function validateGazeData(data: unknown): data is GazeData {
+  if (typeof data !== 'object' || data === null) return false;
+  const d = data as Record<string, unknown>;
+  return (
+    typeof d.x === 'number' &&
+    typeof d.y === 'number' &&
+    typeof d.timestamp === 'number' &&
+    !isNaN(d.x) &&
+    !isNaN(d.y) &&
+    !isNaN(d.timestamp)
+  );
+}
+
+/**
+ * Validate calibration point
+ */
+export function validateCalibrationPoint(point: unknown): point is CalibrationPoint {
+  if (typeof point !== 'object' || point === null) return false;
+  const p = point as Record<string, unknown>;
+  return (
+    typeof p.x === 'number' &&
+    typeof p.y === 'number' &&
+    p.x >= 0 &&
+    p.x <= 1 &&
+    p.y >= 0 &&
+    p.y <= 1
+  );
+}
+
+/**
+ * Filter invalid gaze data
+ */
+export function filterValidGaze(data: GazeData[]): GazeData[] {
+  return data.filter(validateGazeData);
+}
+
+/**
+ * Validate that a server response conforms to CalibrationResult
+ */
+export function validateCalibrationResult(data: unknown): data is CalibrationResult {
+  if (typeof data !== 'object' || data === null) return false;
+  return typeof (data as Record<string, unknown>).success === 'boolean';
+}
+
+/**
+ * Validate that a server response conforms to ValidationResult
+ */
+export function validateValidationResult(data: unknown): data is ValidationResult {
+  if (typeof data !== 'object' || data === null) return false;
+  return typeof (data as Record<string, unknown>).success === 'boolean';
+}

package/src/websocket-client.d.ts

@@ -0,0 +1,55 @@
+/**
+ * WebSocket client for Tobii server communication
+ */
+import type { ConnectionConfig, WebSocketMessage, ConnectionStatus } from './types';
+export declare class WebSocketClient {
+    private ws;
+    private config;
+    private status;
+    private messageHandlers;
+    private reconnectTimeout;
+    private currentReconnectAttempt;
+    private nextRequestId;
+    constructor(config?: ConnectionConfig);
+    /**
+     * Connect to WebSocket server
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from WebSocket server
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Check if connected
+     */
+    isConnected(): boolean;
+    /**
+     * Get connection status
+     */
+    getStatus(): ConnectionStatus;
+    /**
+     * Send message to server
+     */
+    send(message: WebSocketMessage): Promise<void>;
+    /**
+     * Send message and wait for response
+     */
+    sendAndWait(message: WebSocketMessage, timeout?: number): Promise<Record<string, unknown>>;
+    /**
+     * Register message handler
+     */
+    on(messageType: string, handler: (data: Record<string, unknown>) => void): void;
+    /**
+     * Unregister message handler
+     */
+    off(messageType: string): void;
+    /**
+     * Handle incoming message
+     */
+    private handleMessage;
+    /**
+     * Handle disconnection and attempt reconnect
+     */
+    private handleDisconnect;
+}
+//# sourceMappingURL=websocket-client.d.ts.map

package/src/websocket-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket-client.d.ts","sourceRoot":"","sources":["websocket-client.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAEpF,qBAAa,eAAe;IAC1B,OAAO,CAAC,EAAE,CAA0B;IACpC,OAAO,CAAC,MAAM,CAA6B;IAC3C,OAAO,CAAC,MAAM,CAAmB;IACjC,OAAO,CAAC,eAAe,CAAuD;IAC9E,OAAO,CAAC,gBAAgB,CAAuB;IAC/C,OAAO,CAAC,uBAAuB,CAAa;IAC5C,OAAO,CAAC,aAAa,CAAa;gBAEtB,MAAM,GAAE,gBAAqB;IAgBzC;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IA4C9B;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAejC;;OAEG;IACH,WAAW,IAAI,OAAO;IAItB;;OAEG;IACH,SAAS,IAAI,gBAAgB;IAI7B;;OAEG;IACG,IAAI,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAQpD;;OAEG;IACG,WAAW,CACf,OAAO,EAAE,gBAAgB,EACzB,OAAO,GAAE,MAAa,GACrB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IA2BnC;;OAEG;IACH,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,GAAG,IAAI;IAS/E;;OAEG;IACH,GAAG,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAI9B;;OAEG;IACH,OAAO,CAAC,aAAa;IAuBrB;;OAEG;IACH,OAAO,CAAC,gBAAgB;CAwBzB"}

package/src/websocket-client.js

@@ -0,0 +1,189 @@
+/**
+ * WebSocket client for Tobii server communication
+ */
+export class WebSocketClient {
+    constructor(config = {}) {
+        this.ws = null;
+        this.reconnectTimeout = null;
+        this.currentReconnectAttempt = 0;
+        this.nextRequestId = 0;
+        this.config = {
+            url: config.url || 'ws://localhost:8080',
+            autoConnect: config.autoConnect ?? true,
+            reconnectAttempts: config.reconnectAttempts ?? 5,
+            reconnectDelay: config.reconnectDelay ?? 1000,
+        };
+        this.status = {
+            connected: false,
+            tracking: false,
+        };
+        this.messageHandlers = new Map();
+    }
+    /**
+     * Connect to WebSocket server
+     */
+    async connect() {
+        if (this.ws?.readyState === WebSocket.OPEN) {
+            return;
+        }
+        return new Promise((resolve, reject) => {
+            try {
+                this.ws = new WebSocket(this.config.url);
+                // Timeout for connection — cleared on success
+                const timeoutId = setTimeout(() => {
+                    if (this.ws?.readyState !== WebSocket.OPEN) {
+                        reject(new Error(`Connection timeout (${this.config.url})`));
+                    }
+                }, 5000);
+                this.ws.onopen = () => {
+                    clearTimeout(timeoutId);
+                    this.status.connected = true;
+                    this.status.connectedAt = Date.now();
+                    this.currentReconnectAttempt = 0;
+                    resolve();
+                };
+                this.ws.onmessage = (event) => {
+                    this.handleMessage(event);
+                };
+                this.ws.onerror = (error) => {
+                    this.status.lastError = 'WebSocket error';
+                    console.error('WebSocket error:', error);
+                };
+                this.ws.onclose = () => {
+                    this.status.connected = false;
+                    this.status.tracking = false;
+                    this.handleDisconnect();
+                };
+            }
+            catch (error) {
+                reject(error);
+            }
+        });
+    }
+    /**
+     * Disconnect from WebSocket server
+     */
+    async disconnect() {
+        if (this.reconnectTimeout !== null) {
+            clearTimeout(this.reconnectTimeout);
+            this.reconnectTimeout = null;
+        }
+        if (this.ws) {
+            this.ws.close();
+            this.ws = null;
+        }
+        this.status.connected = false;
+        this.status.tracking = false;
+    }
+    /**
+     * Check if connected
+     */
+    isConnected() {
+        return this.ws?.readyState === WebSocket.OPEN;
+    }
+    /**
+     * Get connection status
+     */
+    getStatus() {
+        return { ...this.status };
+    }
+    /**
+     * Send message to server
+     */
+    async send(message) {
+        if (!this.isConnected()) {
+            throw new Error('Not connected to server');
+        }
+        this.ws.send(JSON.stringify(message));
+    }
+    /**
+     * Send message and wait for response
+     */
+    async sendAndWait(message, timeout = 5000) {
+        if (!this.isConnected()) {
+            throw new Error('Not connected to server');
+        }
+        return new Promise((resolve, reject) => {
+            // Generate unique ID for this request
+            const requestId = `req_${this.nextRequestId++}`;
+            const messageWithId = { ...message, requestId };
+            // Set up response handler
+            const timeoutId = setTimeout(() => {
+                this.messageHandlers.delete(requestId);
+                reject(new Error('Request timeout'));
+            }, timeout);
+            this.messageHandlers.set(requestId, (data) => {
+                clearTimeout(timeoutId);
+                this.messageHandlers.delete(requestId);
+                resolve(data);
+            });
+            // Send message
+            this.ws.send(JSON.stringify(messageWithId));
+        });
+    }
+    /**
+     * Register message handler
+     */
+    on(messageType, handler) {
+        if (this.messageHandlers.has(messageType)) {
+            console.warn(`Tobii WebSocket: Overwriting existing handler for message type "${messageType}"`);
+        }
+        this.messageHandlers.set(messageType, handler);
+    }
+    /**
+     * Unregister message handler
+     */
+    off(messageType) {
+        this.messageHandlers.delete(messageType);
+    }
+    /**
+     * Handle incoming message
+     */
+    handleMessage(event) {
+        try {
+            const receiveTime = performance.now();
+            const data = JSON.parse(event.data);
+            data._clientReceiveTime = receiveTime;
+            // Check for request ID (response to sendAndWait)
+            if (data.requestId && this.messageHandlers.has(data.requestId)) {
+                const handler = this.messageHandlers.get(data.requestId);
+                handler(data);
+                return;
+            }
+            // Handle by message type
+            if (data.type && this.messageHandlers.has(data.type)) {
+                const handler = this.messageHandlers.get(data.type);
+                handler(data);
+            }
+        }
+        catch (error) {
+            console.error('Error handling message:', error);
+        }
+    }
+    /**
+     * Handle disconnection and attempt reconnect
+     */
+    handleDisconnect() {
+        if (this.currentReconnectAttempt < this.config.reconnectAttempts) {
+            this.currentReconnectAttempt++;
+            const delay = this.config.reconnectDelay * this.currentReconnectAttempt;
+            this.reconnectTimeout = window.setTimeout(async () => {
+                try {
+                    await this.connect();
+                    // Emit reconnected event so listeners can re-sync time
+                    const reconnectedHandler = this.messageHandlers.get('reconnected');
+                    if (reconnectedHandler) {
+                        reconnectedHandler({ type: 'reconnected' });
+                    }
+                }
+                catch (error) {
+                    console.warn(`Tobii: Reconnection attempt ${this.currentReconnectAttempt}/${this.config.reconnectAttempts} failed:`, error);
+                }
+            }, delay);
+        }
+        else {
+            this.status.lastError = 'Max reconnection attempts reached';
+        }
+    }
+}
+//# sourceMappingURL=websocket-client.js.map

package/src/websocket-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket-client.js","sourceRoot":"","sources":["websocket-client.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,MAAM,OAAO,eAAe;IAS1B,YAAY,SAA2B,EAAE;QARjC,OAAE,GAAqB,IAAI,CAAC;QAI5B,qBAAgB,GAAkB,IAAI,CAAC;QACvC,4BAAuB,GAAW,CAAC,CAAC;QACpC,kBAAa,GAAW,CAAC,CAAC;QAGhC,IAAI,CAAC,MAAM,GAAG;YACZ,GAAG,EAAE,MAAM,CAAC,GAAG,IAAI,qBAAqB;YACxC,WAAW,EAAE,MAAM,CAAC,WAAW,IAAI,IAAI;YACvC,iBAAiB,EAAE,MAAM,CAAC,iBAAiB,IAAI,CAAC;YAChD,cAAc,EAAE,MAAM,CAAC,cAAc,IAAI,IAAI;SAC9C,CAAC;QAEF,IAAI,CAAC,MAAM,GAAG;YACZ,SAAS,EAAE,KAAK;YAChB,QAAQ,EAAE,KAAK;SAChB,CAAC;QAEF,IAAI,CAAC,eAAe,GAAG,IAAI,GAAG,EAAE,CAAC;IACnC,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,OAAO;QACX,IAAI,IAAI,CAAC,EAAE,EAAE,UAAU,KAAK,SAAS,CAAC,IAAI,EAAE,CAAC;YAC3C,OAAO;QACT,CAAC;QAED,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACrC,IAAI,CAAC;gBACH,IAAI,CAAC,EAAE,GAAG,IAAI,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBAEzC,8CAA8C;gBAC9C,MAAM,SAAS,GAAG,UAAU,CAAC,GAAG,EAAE;oBAChC,IAAI,IAAI,CAAC,EAAE,EAAE,UAAU,KAAK,SAAS,CAAC,IAAI,EAAE,CAAC;wBAC3C,MAAM,CAAC,IAAI,KAAK,CAAC,uBAAuB,IAAI,CAAC,MAAM,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;oBAC/D,CAAC;gBACH,CAAC,EAAE,IAAI,CAAC,CAAC;gBAET,IAAI,CAAC,EAAE,CAAC,MAAM,GAAG,GAAG,EAAE;oBACpB,YAAY,CAAC,SAAS,CAAC,CAAC;oBACxB,IAAI,CAAC,MAAM,CAAC,SAAS,GAAG,IAAI,CAAC;oBAC7B,IAAI,CAAC,MAAM,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;oBACrC,IAAI,CAAC,uBAAuB,GAAG,CAAC,CAAC;oBACjC,OAAO,EAAE,CAAC;gBACZ,CAAC,CAAC;gBAEF,IAAI,CAAC,EAAE,CAAC,SAAS,GAAG,CAAC,KAAK,EAAE,EAAE;oBAC5B,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;gBAC5B,CAAC,CAAC;gBAEF,IAAI,CAAC,EAAE,CAAC,OAAO,GAAG,CAAC,KAAK,EAAE,EAAE;oBAC1B,IAAI,CAAC,MAAM,CAAC,SAAS,GAAG,iBAAiB,CAAC;oBAC1C,OAAO,CAAC,KAAK,CAAC,kBAAkB,EAAE,KAAK,CAAC,CAAC;gBAC3C,CAAC,CAAC;gBAEF,IAAI,CAAC,EAAE,CAAC,OAAO,GAAG,GAAG,EAAE;oBACrB,IAAI,CAAC,MAAM,CAAC,SAAS,GAAG,KAAK,CAAC;oBAC9B,IAAI,CAAC,MAAM,CAAC,QAAQ,GAAG,KAAK,CAAC;oBAC7B,IAAI,CAAC,gBAAgB,EAAE,CAAC;gBAC1B,CAAC,CAAC;YACJ,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,CAAC,KAAK,CAAC,CAAC;YAChB,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,UAAU;QACd,IAAI,IAAI,CAAC,gBAAgB,KAAK,IAAI,EAAE,CAAC;YACnC,YAAY,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;YACpC,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC;QAC/B,CAAC;QAED,IAAI,IAAI,CAAC,EAAE,EAAE,CAAC;YACZ,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC;YAChB,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC;QACjB,CAAC;QAED,IAAI,CAAC,MAAM,CAAC,SAAS,GAAG,KAAK,CAAC;QAC9B,IAAI,CAAC,MAAM,CAAC,QAAQ,GAAG,KAAK,CAAC;IAC/B,CAAC;IAED;;OAEG;IACH,WAAW;QACT,OAAO,IAAI,CAAC,EAAE,EAAE,UAAU,KAAK,SAAS,CAAC,IAAI,CAAC;IAChD,CAAC;IAED;;OAEG;IACH,SAAS;QACP,OAAO,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;IAC5B,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,IAAI,CAAC,OAAyB;QAClC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;QAC7C,CAAC;QAED,IAAI,CAAC,EAAG,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC;IACzC,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,WAAW,CACf,OAAyB,EACzB,UAAkB,IAAI;QAEtB,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;QAC7C,CAAC;QAED,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACrC,sCAAsC;YACtC,MAAM,SAAS,GAAG,OAAO,IAAI,CAAC,aAAa,EAAE,EAAE,CAAC;YAChD,MAAM,aAAa,GAAG,EAAE,GAAG,OAAO,EAAE,SAAS,EAAE,CAAC;YAEhD,0BAA0B;YAC1B,MAAM,SAAS,GAAG,UAAU,CAAC,GAAG,EAAE;gBAChC,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;gBACvC,MAAM,CAAC,IAAI,KAAK,CAAC,iBAAiB,CAAC,CAAC,CAAC;YACvC,CAAC,EAAE,OAAO,CAAC,CAAC;YAEZ,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,EAAE;gBAC3C,YAAY,CAAC,SAAS,CAAC,CAAC;gBACxB,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;gBACvC,OAAO,CAAC,IAAI,CAAC,CAAC;YAChB,CAAC,CAAC,CAAC;YAEH,eAAe;YACf,IAAI,CAAC,EAAG,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC;QAC/C,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,EAAE,CAAC,WAAmB,EAAE,OAAgD;QACtE,IAAI,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,CAAC;YAC1C,OAAO,CAAC,IAAI,CACV,mEAAmE,WAAW,GAAG,CAClF,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;IACjD,CAAC;IAED;;OAEG;IACH,GAAG,CAAC,WAAmB;QACrB,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;IAC3C,CAAC;IAED;;OAEG;IACK,aAAa,CAAC,KAAmB;QACvC,IAAI,CAAC;YACH,MAAM,WAAW,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;YACtC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YACpC,IAAI,CAAC,kBAAkB,GAAG,WAAW,CAAC;YAEtC,iDAAiD;YACjD,IAAI,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;gBAC/D,MAAM,OAAO,GAAG,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;gBACzD,OAAQ,CAAC,IAAI,CAAC,CAAC;gBACf,OAAO;YACT,CAAC;YAED,yBAAyB;YACzB,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;gBACrD,MAAM,OAAO,GAAG,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBACpD,OAAQ,CAAC,IAAI,CAAC,CAAC;YACjB,CAAC;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,KAAK,CAAC,yBAAyB,EAAE,KAAK,CAAC,CAAC;QAClD,CAAC;IACH,CAAC;IAED;;OAEG;IACK,gBAAgB;QACtB,IAAI,IAAI,CAAC,uBAAuB,GAAG,IAAI,CAAC,MAAM,CAAC,iBAAiB,EAAE,CAAC;YACjE,IAAI,CAAC,uBAAuB,EAAE,CAAC;YAC/B,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,cAAc,GAAG,IAAI,CAAC,uBAAuB,CAAC;YAExE,IAAI,CAAC,gBAAgB,GAAG,MAAM,CAAC,UAAU,CAAC,KAAK,IAAI,EAAE;gBACnD,IAAI,CAAC;oBACH,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;oBACrB,uDAAuD;oBACvD,MAAM,kBAAkB,GAAG,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;oBACnE,IAAI,kBAAkB,EAAE,CAAC;wBACvB,kBAAkB,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC,CAAC;oBAC9C,CAAC;gBACH,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,OAAO,CAAC,IAAI,CACV,+BAA+B,IAAI,CAAC,uBAAuB,IAAI,IAAI,CAAC,MAAM,CAAC,iBAAiB,UAAU,EACtG,KAAK,CACN,CAAC;gBACJ,CAAC;YACH,CAAC,EAAE,KAAK,CAAC,CAAC;QACZ,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,MAAM,CAAC,SAAS,GAAG,mCAAmC,CAAC;QAC9D,CAAC;IACH,CAAC;CACF"}

package/src/websocket-client.ts

@@ -0,0 +1,227 @@
+/**
+ * WebSocket client for Tobii server communication
+ */
+
+import type { ConnectionConfig, WebSocketMessage, ConnectionStatus } from './types';
+
+export class WebSocketClient {
+  private ws: WebSocket | null = null;
+  private config: Required<ConnectionConfig>;
+  private status: ConnectionStatus;
+  private messageHandlers: Map<string, (data: Record<string, unknown>) => void>;
+  private reconnectTimeout: number | null = null;
+  private currentReconnectAttempt: number = 0;
+  private nextRequestId: number = 0;
+
+  constructor(config: ConnectionConfig = {}) {
+    this.config = {
+      url: config.url || 'ws://localhost:8080',
+      autoConnect: config.autoConnect ?? true,
+      reconnectAttempts: config.reconnectAttempts ?? 5,
+      reconnectDelay: config.reconnectDelay ?? 1000,
+    };
+
+    this.status = {
+      connected: false,
+      tracking: false,
+    };
+
+    this.messageHandlers = new Map();
+  }
+
+  /**
+   * Connect to WebSocket server
+   */
+  async connect(): Promise<void> {
+    if (this.ws?.readyState === WebSocket.OPEN) {
+      return;
+    }
+
+    return new Promise((resolve, reject) => {
+      try {
+        this.ws = new WebSocket(this.config.url);
+
+        // Timeout for connection — cleared on success
+        const timeoutId = setTimeout(() => {
+          if (this.ws?.readyState !== WebSocket.OPEN) {
+            reject(new Error(`Connection timeout (${this.config.url})`));
+          }
+        }, 5000);
+
+        this.ws.onopen = () => {
+          clearTimeout(timeoutId);
+          this.status.connected = true;
+          this.status.connectedAt = Date.now();
+          this.currentReconnectAttempt = 0;
+          resolve();
+        };
+
+        this.ws.onmessage = (event) => {
+          this.handleMessage(event);
+        };
+
+        this.ws.onerror = (error) => {
+          this.status.lastError = 'WebSocket error';
+          console.error('WebSocket error:', error);
+        };
+
+        this.ws.onclose = () => {
+          this.status.connected = false;
+          this.status.tracking = false;
+          this.handleDisconnect();
+        };
+      } catch (error) {
+        reject(error);
+      }
+    });
+  }
+
+  /**
+   * Disconnect from WebSocket server
+   */
+  async disconnect(): Promise<void> {
+    if (this.reconnectTimeout !== null) {
+      clearTimeout(this.reconnectTimeout);
+      this.reconnectTimeout = null;
+    }
+
+    if (this.ws) {
+      this.ws.close();
+      this.ws = null;
+    }
+
+    this.status.connected = false;
+    this.status.tracking = false;
+  }
+
+  /**
+   * Check if connected
+   */
+  isConnected(): boolean {
+    return this.ws?.readyState === WebSocket.OPEN;
+  }
+
+  /**
+   * Get connection status
+   */
+  getStatus(): ConnectionStatus {
+    return { ...this.status };
+  }
+
+  /**
+   * Send message to server
+   */
+  async send(message: WebSocketMessage): Promise<void> {
+    if (!this.isConnected()) {
+      throw new Error('Not connected to server');
+    }
+
+    this.ws!.send(JSON.stringify(message));
+  }
+
+  /**
+   * Send message and wait for response
+   */
+  async sendAndWait(
+    message: WebSocketMessage,
+    timeout: number = 5000
+  ): Promise<Record<string, unknown>> {
+    if (!this.isConnected()) {
+      throw new Error('Not connected to server');
+    }
+
+    return new Promise((resolve, reject) => {
+      // Generate unique ID for this request
+      const requestId = `req_${this.nextRequestId++}`;
+      const messageWithId = { ...message, requestId };
+
+      // Set up response handler
+      const timeoutId = setTimeout(() => {
+        this.messageHandlers.delete(requestId);
+        reject(new Error('Request timeout'));
+      }, timeout);
+
+      this.messageHandlers.set(requestId, (data) => {
+        clearTimeout(timeoutId);
+        this.messageHandlers.delete(requestId);
+        resolve(data);
+      });
+
+      // Send message
+      this.ws!.send(JSON.stringify(messageWithId));
+    });
+  }
+
+  /**
+   * Register message handler
+   */
+  on(messageType: string, handler: (data: Record<string, unknown>) => void): void {
+    if (this.messageHandlers.has(messageType)) {
+      console.warn(
+        `Tobii WebSocket: Overwriting existing handler for message type "${messageType}"`
+      );
+    }
+    this.messageHandlers.set(messageType, handler);
+  }
+
+  /**
+   * Unregister message handler
+   */
+  off(messageType: string): void {
+    this.messageHandlers.delete(messageType);
+  }
+
+  /**
+   * Handle incoming message
+   */
+  private handleMessage(event: MessageEvent): void {
+    try {
+      const receiveTime = performance.now();
+      const data = JSON.parse(event.data);
+      data._clientReceiveTime = receiveTime;
+
+      // Check for request ID (response to sendAndWait)
+      if (data.requestId && this.messageHandlers.has(data.requestId)) {
+        const handler = this.messageHandlers.get(data.requestId);
+        handler!(data);
+        return;
+      }
+
+      // Handle by message type
+      if (data.type && this.messageHandlers.has(data.type)) {
+        const handler = this.messageHandlers.get(data.type);
+        handler!(data);
+      }
+    } catch (error) {
+      console.error('Error handling message:', error);
+    }
+  }
+
+  /**
+   * Handle disconnection and attempt reconnect
+   */
+  private handleDisconnect(): void {
+    if (this.currentReconnectAttempt < this.config.reconnectAttempts) {
+      this.currentReconnectAttempt++;
+      const delay = this.config.reconnectDelay * this.currentReconnectAttempt;
+
+      this.reconnectTimeout = window.setTimeout(async () => {
+        try {
+          await this.connect();
+          // Emit reconnected event so listeners can re-sync time
+          const reconnectedHandler = this.messageHandlers.get('reconnected');
+          if (reconnectedHandler) {
+            reconnectedHandler({ type: 'reconnected' });
+          }
+        } catch (error) {
+          console.warn(
+            `Tobii: Reconnection attempt ${this.currentReconnectAttempt}/${this.config.reconnectAttempts} failed:`,
+            error
+          );
+        }
+      }, delay);
+    } else {
+      this.status.lastError = 'Max reconnection attempts reached';
+    }
+  }
+}