@viji-dev/core 0.6.2 → 0.7.4

package/dist/artist-global.d.ts

@@ -1,9 +1,9 @@
-// Viji Artist API - Global Type Definitions
-// All types are placed inside declare global {} because this file uses export {}
-// for top-level await support, which makes it a module (where top-level declarations
-// would otherwise be module-scoped, not global).
-
-declare global {
+// Viji Artist API - Global Type Definitions
+// All types are placed inside declare global {} because this file uses export {}
+// for top-level await support, which makes it a module (where top-level declarations
+// would otherwise be module-scoped, not global).
+
+declare global {
   /**
    * Real-time audio analysis for the main audio stream (`viji.audio`).
    * Provides volume, frequency bands, beat detection (with triggers, events, BPM),
@@ -118,7 +118,7 @@ declare global {
        */
       getWaveform: () => Float32Array;
   }
-
+
   /**
    * Lightweight audio analysis for additional or device audio streams. A strict
    * subset of `AudioAPI` that exposes volume, frequency bands, spectral features,
@@ -178,7 +178,7 @@ declare global {
        */
       getWaveform: () => Float32Array;
   }
-
+
   /**
    * Configuration object passed to `viji.button()`. The host renders a clickable
    * momentary button. The resulting `value` is `true` for one frame after press,
@@ -194,7 +194,7 @@ declare global {
       /** Visibility category. The control hides when its capability is unavailable. Default: `'general'`. */
       category?: ParameterCategory;
   }
-
+
   /**
    * Reactive object returned by `viji.button()`. `value` is a momentary flag:
    * `true` for exactly one frame after the user clicks, then auto-resets to
@@ -212,7 +212,7 @@ declare global {
       /** Visibility category that controls when the parameter is shown. */
       category: ParameterCategory;
   }
-
+
   /**
    * Options accepted by `VijiCore.captureFrame()` for snapshotting the current
    * scene. Controls output format, encoding, and target resolution / aspect.
@@ -230,7 +230,7 @@ declare global {
        */
       resolution?: number | Resolution;
   }
-
+
   /**
    * Configuration object passed to `viji.color()`. Defines the color picker's
    * label and UI grouping/visibility.
@@ -245,7 +245,7 @@ declare global {
       /** Visibility category. The control hides when its capability is unavailable. Default: `'general'`. */
       category?: ParameterCategory;
   }
-
+
   /**
    * Accepted input forms for color parameters. Internally normalized to canonical
    * lowercase 6-digit hex `#rrggbb`. See `viji.color()` for full documentation.
@@ -270,7 +270,7 @@ declare global {
       /** Brightness in 0..100. */
       b: number;
   };
-
+
   /**
    * Reactive object returned by `viji.color()`. `value` is always a canonical
    * lowercase 6-digit hex string; `rgb` and `hsb` are derived accessors that are
@@ -306,7 +306,7 @@ declare global {
       /** Visibility category that controls when the parameter is shown. */
       category: ParameterCategory;
   }
-
+
   /**
    * Configuration object passed to `viji.coordinate()`. The host renders a 2D
    * draggable pad; both `x` and `y` are clamped to `-1..1`.
@@ -323,7 +323,7 @@ declare global {
       /** Visibility category. The control hides when its capability is unavailable. Default: `'general'`. */
       category?: ParameterCategory;
   }
-
+
   /**
    * Reactive object returned by `viji.coordinate()`. `value.x` and `value.y` are
    * always in `-1..1`; the host UI renders a draggable 2D pad.
@@ -342,7 +342,7 @@ declare global {
       /** Visibility category that controls when the parameter is shown. */
       category: ParameterCategory;
   }
-
+
   /**
    * Two-component coordinate, both axes in `-1..1` (centered on the canvas).
    * Returned and consumed by `viji.coordinate()`.
@@ -353,20 +353,20 @@ declare global {
       /** Vertical axis in `-1..1` (bottom to top, `0` = canvas center). */
       y: number;
   };
-
+
   /**
    * Identifier for an individual computer-vision feature pipeline. Returned by
    * `VideoAPI.cv.getActiveFeatures()` and used internally to track state.
    */
   type CVFeature = 'faceDetection' | 'faceMesh' | 'handTracking' | 'poseDetection' | 'bodySegmentation' | 'emotionDetection';
-
+
   /**
    * Computer-vision processing rate relative to the scene's render rate.
    * `'full'` runs CV every frame, `'half'` every other frame, `'quarter'` every
    * fourth, `'eighth'` every eighth. Lower rates reduce CPU/GPU cost.
    */
   type CVFrameRateMode = 'full' | 'half' | 'quarter' | 'eighth';
-
+
   /**
    * Device motion data sourced from the platform's `DeviceMotionEvent`. All
    * accelerations are in metres per second squared (m/s²); rotation rates are
@@ -405,7 +405,7 @@ declare global {
       /** Interval between sensor updates in milliseconds. */
       interval: number;
   }
-
+
   /**
    * DeviceOrientationEvent data
    * Matches native DeviceOrientationEvent structure
@@ -420,7 +420,7 @@ declare global {
       /** True if using magnetometer (compass) for absolute orientation */
       absolute: boolean;
   }
-
+
   /**
    * Sensor snapshot for the device running the scene. Both fields read `null`
    * when the corresponding sensor is unavailable or has not delivered a sample yet.
@@ -431,7 +431,7 @@ declare global {
       /** Orientation data (alpha/beta/gamma in degrees). `null` if no orientation sensor is available. */
       orientation: DeviceOrientationData | null;
   }
-
+
   /**
    * External device state (includes id and name)
    */
@@ -445,7 +445,7 @@ declare global {
       /** Device audio stream (null if not available) */
       audio: AudioStreamAPI | null;
   }
-
+
   /**
    * 52 ARKit-compatible face blendshape coefficients (each in 0..1) derived from
    * MediaPipe FaceLandmarker. All fields are `0` unless emotion detection is
@@ -557,17 +557,27 @@ declare global {
       /** Coefficient (0..1) for the tongue protruding. */
       tongueOut: number;
   }
-
+
   /**
-   * One detected face produced by the video CV pipeline. Always carries `id`,
-   * `bounds`, `center`, and `confidence`; the rest is populated only when the
-   * matching CV feature is enabled (face mesh for `landmarks` and `headPose`,
-   * emotion detection for `expressions` and `blendshapes`).
+   * One detected face produced by the video CV pipeline. Each field is
+   * populated only by its source model; fields whose source model is not
+   * enabled read as `null` so the absence is loud rather than silent. Enable
+   * the relevant `enable*` verb on `viji.video.cv` to populate each group:
+   *
+   * - `bounds`, `center`, `confidence`: populated by `enableFaceDetection(true)`.
+   * - `landmarks`: populated by `enableFaceMesh(true)` (empty array otherwise).
+   * - `headPose`: populated by `enableFaceMesh(true)`.
+   * - `blendshapes`, `expressions`: populated by `enableEmotionDetection(true)`.
+   *
+   * If a field is `null`, call the corresponding `enable*` verb on
+   * `viji.video.cv` to populate it. Each active CV feature consumes its own
+   * WebGL context for MediaPipe; enabling many at once on lower-end hardware
+   * can hit context limits.
    */
   interface FaceData {
       /** Index-based face identifier (`0`, `1`, …). Stable within a single frame, may change between frames. */
       id: number;
-      /** Bounding box, all components normalized to 0..1 of the source frame. */
+      /** Bounding box, all components normalized to 0..1 of the source frame. `null` unless face detection is enabled. */
       bounds: {
           /** Left edge of the face bounding box, normalized 0..1. */
           x: number;
@@ -577,16 +587,16 @@ declare global {
           width: number;
           /** Height of the face bounding box, normalized 0..1. */
           height: number;
-      };
-      /** Center of the bounding box, normalized 0..1. */
+      } | null;
+      /** Center of the bounding box, normalized 0..1. `null` unless face detection is enabled. */
       center: {
           /** Horizontal center of the face, normalized 0..1. */
           x: number;
           /** Vertical center of the face, normalized 0..1. */
           y: number;
-      };
-      /** Detection confidence in 0..1. */
-      confidence: number;
+      } | null;
+      /** Detection confidence in 0..1. `null` unless face detection is enabled. */
+      confidence: number | null;
       /** 468 normalized face mesh landmarks when face mesh is enabled; empty array otherwise. */
       landmarks: {
           /** Horizontal landmark coordinate, normalized 0..1. */
@@ -596,7 +606,16 @@ declare global {
           /** Optional depth (relative). */
           z?: number;
       }[];
-      /** Seven expression confidence scores in 0..1. All zero unless emotion detection is enabled. */
+      /** Estimated head rotation in degrees. `null` unless face mesh is enabled. */
+      headPose: {
+          /** Up/down rotation in degrees (-90..90). Positive = head looking up, negative = looking down. */
+          pitch: number;
+          /** Left/right rotation in degrees (-90..90). Positive = head turned to the subject's right, negative = to the left. */
+          yaw: number;
+          /** Tilt rotation in degrees (-180..180). Positive = head tilted to the subject's right (right ear toward right shoulder). */
+          roll: number;
+      } | null;
+      /** Seven expression confidence scores in 0..1. `null` unless emotion detection is enabled. */
       expressions: {
           /** Confidence (0..1) of a neutral expression. */
           neutral: number;
@@ -612,27 +631,18 @@ declare global {
           disgusted: number;
           /** Confidence (0..1) of a fearful expression. */
           fearful: number;
-      };
-      /** Estimated head rotation. All zero unless face mesh is enabled. */
-      headPose: {
-          /** Up/down rotation in degrees (-90..90). Positive = head looking up, negative = looking down. */
-          pitch: number;
-          /** Left/right rotation in degrees (-90..90). Positive = head turned to the subject's right, negative = to the left. */
-          yaw: number;
-          /** Tilt rotation in degrees (-180..180). Positive = head tilted to the subject's right (right ear toward right shoulder). */
-          roll: number;
-      };
-      /** 52 ARKit-compatible facial muscle coefficients. All zero unless emotion detection is enabled. */
-      blendshapes: FaceBlendshapes;
+      } | null;
+      /** 52 ARKit-compatible facial muscle coefficients. `null` unless emotion detection is enabled. */
+      blendshapes: FaceBlendshapes | null;
   }
-
+
   /**
    * Render-loop pacing mode. `'full'` runs `render()` on every animation frame
    * (~60 FPS). `'half'` runs every second frame (~30 FPS), saving CPU/GPU on
    * lower-cost scenes.
    */
   type FrameRateMode = 'full' | 'half';
-
+
   /**
    * One named frequency band reported by the audio analyzer
    * (e.g., `{ name: 'low', min: 20, max: 120 }`). Frequencies are in Hertz.
@@ -645,7 +655,7 @@ declare global {
       /** Upper edge of the band in Hertz (exclusive). */
       max: number;
   }
-
+
   /**
    * One detected hand produced by the video CV pipeline. Carries 21 landmarks,
    * a palm shortcut, and ML-classified gesture confidence scores. Up to two
@@ -708,7 +718,7 @@ declare global {
           iLoveYou: number;
       };
   }
-
+
   /**
    * Configuration object passed to `viji.image()`. The host renders an upload
    * field; the user-supplied image becomes available as an `ImageBitmap` (Native)
@@ -724,7 +734,7 @@ declare global {
       /** Visibility category. The control hides when its capability is unavailable. Default: `'general'`. */
       category?: ParameterCategory;
   }
-
+
   /**
    * Reactive object returned by `viji.image()`. `value` is `null` until the user
    * uploads an image; in P5 scenes a `.p5` accessor is also added at runtime so
@@ -744,7 +754,7 @@ declare global {
       /** Visibility category that controls when the parameter is shown. */
       category: ParameterCategory;
   }
-
+
   /**
    * Keyboard input state for the current frame: per-key press / hold / release
    * queries (case-insensitive), the live set of held keys, modifier flags, and
@@ -785,7 +795,7 @@ declare global {
        */
       textureData: Uint8Array;
   }
-
+
   /**
    * Mouse input state for the current frame: position, individual button states,
    * per-frame movement, scroll wheel, and frame-based press / release events.
@@ -825,7 +835,7 @@ declare global {
       /** `true` if the mouse moved this frame (any non-zero `deltaX` / `deltaY`). Resets each frame. */
       wasMoved: boolean;
   }
-
+
   /**
    * Configuration object passed to `viji.number()`. Defines the bounds, step,
    * label, and UI grouping/visibility for a precise numeric input.
@@ -846,7 +856,7 @@ declare global {
       /** Visibility category. The control hides when its capability is unavailable. Default: `'general'`. */
       category?: ParameterCategory;
   }
-
+
   /**
    * Reactive object returned by `viji.number()`. Like `SliderParameter` but the
    * host UI renders a precise numeric input rather than a draggable slider.
@@ -869,14 +879,14 @@ declare global {
       /** Visibility category that controls when the parameter is shown. */
       category: ParameterCategory;
   }
-
+
   /**
    * Visibility category for a parameter. The host hides parameters whose category
    * is not currently available (e.g., `'audio'` controls hide when no audio
    * source is connected). `'general'` parameters are always visible.
    */
   type ParameterCategory = 'audio' | 'video' | 'interaction' | 'general';
-
+
   /**
    * Unified pointer that abstracts mouse and primary touch into a single input
    * stream. Recommended for click / drag / position-tracking interactions that
@@ -905,7 +915,7 @@ declare global {
       /** Currently active input source: `'touch'` when at least one touch is active, otherwise `'mouse'` (or `'none'` when the cursor is off-canvas). */
       type: 'mouse' | 'touch' | 'none';
   }
-
+
   /**
    * Detected body pose from MediaPipe BlazePose. `landmarks` contains 33 points;
    * the `face` / `torso` / `leftArm` / `rightArm` / `leftLeg` / `rightLeg` arrays
@@ -968,7 +978,7 @@ declare global {
           y: number;
       }[];
   }
-
+
   /**
    * Discrete pixel dimensions for a canvas, frame capture, or render target.
    */
@@ -978,7 +988,7 @@ declare global {
       /** Height in pixels (positive integer). */
       height: number;
   };
-
+
   /**
    * Per-pixel person/background segmentation mask. Mask dimensions reflect the
    * ML model's output and may differ from the source video frame.
@@ -991,7 +1001,7 @@ declare global {
       /** Mask height in pixels. */
       height: number;
   }
-
+
   /**
    * Configuration object passed to `viji.select()`. The host renders the choices
    * as a dropdown or segmented control.
@@ -1008,7 +1018,7 @@ declare global {
       /** Visibility category. The control hides when its capability is unavailable. Default: `'general'`. */
       category?: ParameterCategory;
   }
-
+
   /**
    * Reactive object returned by `viji.select()`. `value` matches the element type
    * of the configured `options` array (`string` or `number`).
@@ -1027,7 +1037,7 @@ declare global {
       /** Visibility category that controls when the parameter is shown. */
       category: ParameterCategory;
   }
-
+
   /**
    * Configuration object passed to `viji.slider()`. Defines the slider's bounds,
    * increment, label, and UI grouping/visibility.
@@ -1048,7 +1058,7 @@ declare global {
       /** Visibility category. The control hides when its capability is unavailable. Default: `'general'`. */
       category?: ParameterCategory;
   }
-
+
   /**
    * Reactive object returned by `viji.slider()`. `value` updates in real-time as
    * the user drags the control; the remaining fields mirror the configuration.
@@ -1071,7 +1081,7 @@ declare global {
       /** Visibility category that controls when the parameter is shown. */
       category: ParameterCategory;
   }
-
+
   /**
    * Configuration object passed to `viji.text()`. The host renders a single-line
    * text input field.
@@ -1088,7 +1098,7 @@ declare global {
       /** Maximum character count enforced by the host UI. Default: `1000`. */
       maxLength?: number;
   }
-
+
   /**
    * Reactive object returned by `viji.text()`. `value` updates as the user types
    * and is enforced to be no longer than `maxLength` by the host UI.
@@ -1107,7 +1117,7 @@ declare global {
       /** Visibility category that controls when the parameter is shown. */
       category: ParameterCategory;
   }
-
+
   /**
    * Configuration object passed to `viji.toggle()`. Defines the on/off switch's
    * label and UI grouping/visibility.
@@ -1122,7 +1132,7 @@ declare global {
       /** Visibility category. The control hides when its capability is unavailable. Default: `'general'`. */
       category?: ParameterCategory;
   }
-
+
   /**
    * Reactive object returned by `viji.toggle()`. `value` flips between `true`
    * and `false` as the user interacts with the switch.
@@ -1139,7 +1149,7 @@ declare global {
       /** Visibility category that controls when the parameter is shown. */
       category: ParameterCategory;
   }
-
+
   /**
    * Multi-touch input state. Lists all active touches, plus per-frame
    * `started` / `moved` / `ended` arrays for frame-based gesture handling.
@@ -1161,7 +1171,7 @@ declare global {
       /** Convenience shortcut to `points[0]`, or `null` when no touches are active. */
       primary: TouchPoint | null;
   }
-
+
   /**
    * One active touch contact reported by `TouchAPI`. Position, pressure, radius,
    * rotation, per-frame movement, velocity, and lifecycle flags. Coordinates are
@@ -1210,9 +1220,9 @@ declare global {
       /** `true` for exactly one frame when this touch ends, then auto-resets. */
       isEnding: boolean;
   }
-
-  const VERSION = "0.6.0";
-
+
+  const VERSION = "0.7.4";
+
   /**
    * Real-time video API: drawable frame, dimensions, and the source-side
    * properties of the connected stream. All computer-vision data and controls
@@ -1254,7 +1264,7 @@ declare global {
        */
       cv: VideoCVAPI;
   }
-
+
   /**
    * Computer-vision surface attached to a `VideoAPI`. Combines paired CV data
    * outputs (the analysed frame and its detection / segmentation results) with
@@ -1320,35 +1330,73 @@ declare global {
       /** Body segmentation mask, or `null` when segmentation is off. */
       segmentation: SegmentationData | null;
       /**
-       * Toggle face detection (bounding box, center, confidence, id).
+       * Toggle face detection. Populates `face.bounds`, `face.center`,
+       * `face.confidence` on each detected face. Independent of face mesh and
+       * emotion detection.
+       *
+       * Safe to call from module scope as well as from inside `render()`. The
+       * verb is idempotent and reference-counted; per-frame calls inside
+       * `render()` (the canonical toggle-gated pattern) are cheap.
+       *
        * @returns Resolves once the underlying pipeline has finished switching.
        */
       enableFaceDetection(enabled: boolean): Promise<void>;
       /**
-       * Toggle 468-point face mesh + head pose (`pitch`, `yaw`, `roll`). Implies
-       * face detection.
+       * Toggle 468-point face mesh and computed head pose (`pitch`, `yaw`,
+       * `roll`). Populates `face.landmarks` and `face.headPose` on the face
+       * entry. Does NOT populate `face.bounds` / `face.center` / `face.confidence`
+       * — those are produced only by face detection. Enable both if you need
+       * both, or compute bounds from `face.landmarks` min/max yourself.
+       *
+       * Safe to call from module scope as well as from inside `render()`. The
+       * verb is idempotent and reference-counted.
+       *
        * @returns Resolves once the pipeline has finished switching.
        */
       enableFaceMesh(enabled: boolean): Promise<void>;
       /**
        * Toggle 7 expressions + 52 ARKit blendshape coefficients on each face.
-       * Implies face mesh.
+       * Populates `face.blendshapes` and `face.expressions`. Internally requires
+       * the face landmarker model (loads it alongside `enableFaceMesh` if both
+       * are enabled; loads it on its own otherwise so `face.landmarks` and
+       * `face.headPose` are also populated). Does NOT populate
+       * `face.bounds` / `face.center` / `face.confidence` — enable face
+       * detection for those.
+       *
+       * Safe to call from module scope as well as from inside `render()`. The
+       * verb is idempotent and reference-counted.
+       *
        * @returns Resolves once the pipeline has finished switching.
        */
       enableEmotionDetection(enabled: boolean): Promise<void>;
       /**
-       * Toggle 21-point hand landmarks + ML-classified gesture confidences for up
-       * to two hands.
+       * Toggle 21-point hand landmarks and ML-classified gesture confidences
+       * for up to two hands. Populates `viji.video.cv.hands[]` with `landmarks`,
+       * `palm`, `bounds` (computed from landmarks), and `gestures`.
+       *
+       * Safe to call from module scope as well as from inside `render()`. The
+       * verb is idempotent and reference-counted.
+       *
        * @returns Resolves once the pipeline has finished switching.
        */
       enableHandTracking(enabled: boolean): Promise<void>;
       /**
        * Toggle 33-point BlazePose body landmarks (face / torso / arms / legs).
+       * Populates `viji.video.cv.pose`.
+       *
+       * Safe to call from module scope as well as from inside `render()`. The
+       * verb is idempotent and reference-counted.
+       *
        * @returns Resolves once the pipeline has finished switching.
        */
       enablePoseDetection(enabled: boolean): Promise<void>;
       /**
-       * Toggle per-pixel person/background segmentation mask.
+       * Toggle per-pixel person/background segmentation mask. Populates
+       * `viji.video.cv.segmentation`.
+       *
+       * Safe to call from module scope as well as from inside `render()`. The
+       * verb is idempotent and reference-counted.
+       *
        * @returns Resolves once the pipeline has finished switching.
        */
       enableBodySegmentation(enabled: boolean): Promise<void>;
@@ -1357,7 +1405,7 @@ declare global {
       /** Returns `true` if the CV worker is actively processing frames. */
       isProcessing(): boolean;
   }
-
+
   /**
    * The Viji API surface available to artist code as the global `viji` object.
    * Groups canvas access, timing, connected media APIs, user interaction, device
@@ -1511,14 +1559,14 @@ declare global {
        */
       useContext(type: 'webgl2'): WebGL2RenderingContext;
   }
-
-  // Runtime global - the main viji object
-  const viji: VijiAPI;
-  
-  // Function type aliases (artists define their own render/setup functions)
-  type Render = (viji: VijiAPI) => void;
-  type Setup = (viji: VijiAPI) => void;
-}
-
-// Module marker (enables top-level await in artist code)
-export {};
+
+  // Runtime global - the main viji object
+  const viji: VijiAPI;
+  
+  // Function type aliases (artists define their own render/setup functions)
+  type Render = (viji: VijiAPI) => void;
+  type Setup = (viji: VijiAPI) => void;
+}
+
+// Module marker (enables top-level await in artist code)
+export {};

package/dist/artist-jsdoc.d.ts

@@ -362,23 +362,27 @@
  */
 
 /**
- * One detected face produced by the video CV pipeline. Always carries `id`, `bounds`, `center`, and `confidence`; the rest is populated only when the matching CV feature is enabled (face mesh for `landmarks` and `headPose`, emotion detection for `expressions` and `blendshapes`).
+ * One detected face produced by the video CV pipeline. Each field is populated only by its source model; fields whose source model is not enabled read as `null` so the absence is loud rather than silent. Enable the relevant `enable*` verb on `viji.video.cv` to populate each group: - `bounds`, `center`, `confidence`: populated by `enableFaceDetection(true)`. - `landmarks`: populated by `enableFaceMesh(true)` (empty array otherwise). - `headPose`: populated by `enableFaceMesh(true)`. - `blendshapes`, `expressions`: populated by `enableEmotionDetection(true)`. If a field is `null`, call the corresponding `enable*` verb on `viji.video.cv` to populate it. Each active CV feature consumes its own WebGL context for MediaPipe; enabling many at once on lower-end hardware can hit context limits.
  * @typedef {Object} FaceData
  * @property {number} id - Index-based face identifier (`0`, `1`, …). Stable within a single frame, may change between frames.
- * @property {Object} bounds - Bounding box, all components normalized to 0..1 of the source frame.
+ * @property {Object} bounds - Bounding box, all components normalized to 0..1 of the source frame. `null` unless face detection is enabled.
  * @property {number} bounds.x - Left edge of the face bounding box, normalized 0..1.
  * @property {number} bounds.y - Top edge of the face bounding box, normalized 0..1.
  * @property {number} bounds.width - Width of the face bounding box, normalized 0..1.
  * @property {number} bounds.height - Height of the face bounding box, normalized 0..1.
- * @property {Object} center - Center of the bounding box, normalized 0..1.
+ * @property {Object} center - Center of the bounding box, normalized 0..1. `null` unless face detection is enabled.
  * @property {number} center.x - Horizontal center of the face, normalized 0..1.
  * @property {number} center.y - Vertical center of the face, normalized 0..1.
- * @property {number} confidence - Detection confidence in 0..1.
+ * @property {number |null} confidence - Detection confidence in 0..1. `null` unless face detection is enabled.
  * @property {Object} landmarks - 468 normalized face mesh landmarks when face mesh is enabled; empty array otherwise.
  * @property {number} landmarks.x - Horizontal landmark coordinate, normalized 0..1.
  * @property {number} landmarks.y - Vertical landmark coordinate, normalized 0..1.
  * @property {number} landmarks.z - Optional depth (relative).
- * @property {Object} expressions - Seven expression confidence scores in 0..1. All zero unless emotion detection is enabled.
+ * @property {Object} headPose - Estimated head rotation in degrees. `null` unless face mesh is enabled.
+ * @property {number} headPose.pitch - Up/down rotation in degrees (-90..90). Positive = head looking up, negative = looking down.
+ * @property {number} headPose.yaw - Left/right rotation in degrees (-90..90). Positive = head turned to the subject's right, negative = to the left.
+ * @property {number} headPose.roll - Tilt rotation in degrees (-180..180). Positive = head tilted to the subject's right (right ear toward right shoulder).
+ * @property {Object} expressions - Seven expression confidence scores in 0..1. `null` unless emotion detection is enabled.
  * @property {number} expressions.neutral - Confidence (0..1) of a neutral expression.
  * @property {number} expressions.happy - Confidence (0..1) of a happy / smiling expression.
  * @property {number} expressions.sad - Confidence (0..1) of a sad expression.
@@ -386,11 +390,7 @@
  * @property {number} expressions.surprised - Confidence (0..1) of a surprised expression.
  * @property {number} expressions.disgusted - Confidence (0..1) of a disgusted expression.
  * @property {number} expressions.fearful - Confidence (0..1) of a fearful expression.
- * @property {Object} headPose - Estimated head rotation. All zero unless face mesh is enabled.
- * @property {number} headPose.pitch - Up/down rotation in degrees (-90..90). Positive = head looking up, negative = looking down.
- * @property {number} headPose.yaw - Left/right rotation in degrees (-90..90). Positive = head turned to the subject's right, negative = to the left.
- * @property {number} headPose.roll - Tilt rotation in degrees (-180..180). Positive = head tilted to the subject's right (right ear toward right shoulder).
- * @property {FaceBlendshapes} blendshapes - 52 ARKit-compatible facial muscle coefficients. All zero unless emotion detection is enabled.
+ * @property {FaceBlendshapes |null} blendshapes - 52 ARKit-compatible facial muscle coefficients. `null` unless emotion detection is enabled.
  */
 
 /**