.. This file is generated by docs/scripts/generate_javascript_api_rst.mjs.
   Edit javascript/index.d.ts comments and rerun the generator instead.

JavaScript (Beta)
=================

The JavaScript API is provided through the ``@eyeware/beam-eye-tracker`` ES module package in the SDK archive's ``javascript`` folder. It exposes the beta Beam Eye Tracker JavaScript API through a WebAssembly runtime and can be used from browsers, Electron renderer processes, Electron main processes, and Node.js.

Functions
---------

loadBeamEyeTrackerModule
~~~~~~~~~~~~~~~~~~~~~~~~

Loads and initializes the underlying WebAssembly module.

.. code-block:: typescript

   export declare function loadBeamEyeTrackerModule(): Promise<unknown>;

createSession
~~~~~~~~~~~~~

Creates a Beam Eye Tracker JavaScript API instance.

* ``friendlyName``: Name shown to the user by the Beam Eye Tracker application.
* ``viewportGeometry``: Optional viewport rectangle used for viewport gaze mapping.

.. code-block:: typescript

   export declare function createSession(
     friendlyName: string,
     viewportGeometry?: ViewportGeometry,
   ): Promise<BeamEyeTrackerSession>;

Classes
-------

BeamEyeTrackerSession
~~~~~~~~~~~~~~~~~~~~~

JavaScript API object for communicating with the Beam Eye Tracker
application.

Methods
^^^^^^^

Creates an API instance from an already-loaded WebAssembly module.

.. code-block:: typescript

   constructor(module: unknown, friendlyName: string, viewportGeometry?: ViewportGeometry)

Releases native and JavaScript resources owned by this API instance.

.. code-block:: typescript

   destroy(): void

Returns the current tracking-data reception status.

.. code-block:: typescript

   getTrackingDataReceptionStatus(): TrackingDataReceptionStatus

Returns a human-readable name for a tracking-data reception status.

.. code-block:: typescript

   getTrackingDataReceptionStatusName(status?: TrackingDataReceptionStatus): string

Requests Beam Eye Tracker to launch and start tracking.

.. code-block:: typescript

   attemptStartingTheBeamEyeTracker(): void

Starts recentering the smoothed sim game camera.

.. code-block:: typescript

   startRecenterSimGameCamera(): boolean

Stops recentering the smoothed sim game camera.

.. code-block:: typescript

   stopRecenterSimGameCamera(): void

Waits asynchronously for a new tracking-state set.

Pass 0 to poll and return immediately. Pass a positive timeout to wait up
to that number of milliseconds.

This method does not block the JavaScript event loop. It polls internally
until new tracking data is available or the timeout expires.

.. code-block:: typescript

   waitForNewTrackingStateSet(timeoutMs?: number, pollIntervalMs?: number): Promise<boolean>

Returns the most recent tracking-state set.

.. code-block:: typescript

   getLastTrackingStateSet(): TrackingStateSet

Samples the smoothed sim game camera state from the caller's loop.

.. code-block:: typescript

   sampleSmoothSimGameCameraState(): SimGameCameraState

Computes the final sim game camera transform from eye/head tracking
components and caller-provided weights. Preferred for Beam Eye Tracker 2.6
and above when paired with sampleSmoothSimGameCameraState().

.. code-block:: typescript

   computeSmoothSimGameCameraTransformParameters(
       cameraState: SimGameCameraState,
       eyeTrackingWeight?: number,
       headTrackingWeight?: number,
     ): SimCameraTransform3D

Starts asynchronous tracking-data reception callbacks.

.. code-block:: typescript

   startReceivingTrackingData(callbacks: TrackingCallbacks): void

Stops asynchronous tracking-data reception callbacks.

.. code-block:: typescript

   stopReceivingTrackingData(): void

Constants
---------

Status
~~~~~~

Numeric tracking-data reception states reported by the Beam Eye Tracker
JavaScript client.

.. code-block:: typescript

   export declare const Status: Readonly<{
     NOT_RECEIVING_TRACKING_DATA: 0;
     RECEIVING_TRACKING_DATA: 1;
     ATTEMPTING_TRACKING_AUTO_START: 2;
   }>;

Types and Interfaces
--------------------

TrackingDataReceptionStatus
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Indicates whether the client is currently receiving frame-by-frame tracking
data, or whether it is attempting to launch/start Beam Eye Tracker.

.. code-block:: typescript

   export type TrackingDataReceptionStatus = 0 | 1 | 2;

Point
~~~~~

Integer 2D point in screen coordinates.

.. code-block:: typescript

   export interface Point {
     x: number;
     y: number;
   }

Vector3D
~~~~~~~~

3D vector or point.

.. code-block:: typescript

   export interface Vector3D {
     x: number;
     y: number;
     z: number;
   }

ViewportGeometry
~~~~~~~~~~~~~~~~

Viewport rectangle used to map unified screen gaze into normalized viewport
coordinates.

.. code-block:: typescript

   export interface ViewportGeometry {
     point00?: Point;
     point11?: Point;
   }

SimCameraTransform3D
~~~~~~~~~~~~~~~~~~~~

Six degree-of-freedom sim camera transform. Rotations are in radians and
translations are in meters.

.. code-block:: typescript

   export interface SimCameraTransform3D {
     yaw_in_radians: number;
     pitch_in_radians: number;
     roll_in_radians: number;
     x_in_meters: number;
     y_in_meters: number;
     z_in_meters: number;
   }

SimGameCameraState
~~~~~~~~~~~~~~~~~~

Smoothed sim game camera state sampled from the Beam SDK.

.. code-block:: typescript

   export interface SimGameCameraState {
     valid: boolean;
     timestamp_in_seconds?: number;
     eye_tracking_pose_component?: SimCameraTransform3D;
     head_tracking_pose_component?: SimCameraTransform3D;
   }

UserState
~~~~~~~~~

Raw and processed tracking data for the current user.

.. code-block:: typescript

   export interface UserState {
     valid: boolean;
     timestamp_in_seconds?: number;
     head_pose?: {
       confidence: number;
       translation_from_hcs_to_wcs: Vector3D;
       track_session_uid: string;
     };
     unified_screen_gaze?: {
       confidence: number;
       point_of_regard: Point;
       unbounded_point_of_regard: Point;
     };
     viewport_gaze?: {
       confidence: number;
       normalized_point_of_regard: Point;
     };
   }

TrackingStateSet
~~~~~~~~~~~~~~~~

Container for the latest tracking data produced by the Beam Eye Tracker
application.

.. code-block:: typescript

   export interface TrackingStateSet {
     valid: boolean;
     timestamp_in_seconds?: number;
     user_state?: UserState;
     sim_game_camera_state?: SimGameCameraState;
   }

TrackingCallbacks
~~~~~~~~~~~~~~~~~

Callbacks used for asynchronous tracking-data reception in JavaScript.

.. code-block:: typescript

   export interface TrackingCallbacks {
     onStatusChanged?: (status: TrackingDataReceptionStatus) => void;
     onTrackingStateSetUpdate?: (trackingStateSet: TrackingStateSet, timestamp: number) => void;
   }

Browser Runtime Requirements
----------------------------

The current JavaScript package is a beta WebAssembly package. Browser hosts must serve the application and SDK files with cross-origin isolation headers because the runtime uses Emscripten pthreads and ``SharedArrayBuffer``:

* ``Cross-Origin-Opener-Policy: same-origin``
* ``Cross-Origin-Embedder-Policy: require-corp``

For latency-critical desktop integrations, prefer the native C, C++, C#, or Python SDK clients for the target platform.

Keep the package's ``lib`` directory next to ``index.js`` when copying or publishing the package. The generated WebAssembly runtime loads the wasm module from that relative layout.

