@viji-dev/core 0.4.0 → 0.4.1

package/dist/index.d.ts

@@ -11,81 +11,178 @@ declare interface AudioAnalysisState {
     };
 }
 
+/**
+ * Real-time audio analysis for the main audio stream (`viji.audio`).
+ * Provides volume, frequency bands, beat detection (with triggers, events, BPM),
+ * spectral features, and access to raw FFT / waveform data.
+ *
+ * All numeric outputs are zeroed when `isConnected` is `false`.
+ */
 export declare interface AudioAPI {
+    /** `true` when an audio source is connected; otherwise all numeric fields read as `0` and helper methods return empty data. */
     isConnected: boolean;
+    /** Overall loudness across the stream. */
     volume: {
+        /** Instantaneous RMS volume in 0..1. */
         current: number;
+        /** Instantaneous peak amplitude in 0..1. */
         peak: number;
+        /** Volume with a 200ms decay envelope; rises fast, falls smoothly. Use for flicker-free animations. */
         smoothed: number;
     };
+    /** Energy in five fixed frequency bands, plus a smoothed companion (~150ms decay) for each. All in 0..1. */
     bands: {
+        /** Instant low-band energy (20–120 Hz, bass/kick range). 0..1. */
         low: number;
+        /** Instant low-mid energy (120–400 Hz). 0..1. */
         lowMid: number;
+        /** Instant mid energy (400–1600 Hz, vocals/instruments). 0..1. */
         mid: number;
+        /** Instant high-mid energy (1600–6000 Hz, cymbals/hi-hats). 0..1. */
         highMid: number;
+        /** Instant high-band energy (6000–16000 Hz, air/brilliance). 0..1. */
         high: number;
+        /** Smoothed `low` (~150ms decay). 0..1. */
         lowSmoothed: number;
+        /** Smoothed `lowMid` (~150ms decay). 0..1. */
         lowMidSmoothed: number;
+        /** Smoothed `mid` (~150ms decay). 0..1. */
         midSmoothed: number;
+        /** Smoothed `highMid` (~150ms decay). 0..1. */
         highMidSmoothed: number;
+        /** Smoothed `high` (~150ms decay). 0..1. */
         highSmoothed: number;
     };
+    /** Beat detection: fast/smoothed energy curves, single-frame boolean triggers, raw event list, and BPM tracking. */
     beat: {
+        /** Kick energy curve in 0..1 with a 300ms decay. Peaks on each detected kick. */
         kick: number;
+        /** Snare energy curve in 0..1 with a 300ms decay. */
         snare: number;
+        /** Hi-hat energy curve in 0..1 with a 300ms decay. */
         hat: number;
+        /** Energy curve for any beat type in 0..1 with a 300ms decay. */
         any: number;
+        /** Smoothed `kick` curve in 0..1 with a 500ms decay. Use for ambient pulses. */
         kickSmoothed: number;
+        /** Smoothed `snare` curve in 0..1 with a 500ms decay. */
         snareSmoothed: number;
+        /** Smoothed `hat` curve in 0..1 with a 500ms decay. */
         hatSmoothed: number;
+        /** Smoothed `any` curve in 0..1 with a 500ms decay. */
         anySmoothed: number;
+        /** Single-frame boolean triggers OR-accumulated between frames, so no detected beat is lost. */
         triggers: {
+            /** `true` for one frame when any beat is detected. */
             any: boolean;
+            /** `true` for one frame when a kick is detected. */
             kick: boolean;
+            /** `true` for one frame when a snare is detected. */
             snare: boolean;
+            /** `true` for one frame when a hi-hat is detected. */
             hat: boolean;
         };
+        /** All beats detected since the last render frame (zero or more). Cleared each frame. */
         events: Array<{
+            /** Which drum was detected. */
             type: 'kick' | 'snare' | 'hat';
+            /** Timestamp of the detection in milliseconds. */
             time: number;
+            /** Strength of the beat in 0..1. */
             strength: number;
         }>;
+        /** Currently detected tempo in beats per minute. Defaults to `120` when no audio. */
         bpm: number;
+        /** Confidence of the BPM tracker in 0..1. */
         confidence: number;
+        /** `true` when the BPM tracker has a stable lock on the current tempo. */
         isLocked: boolean;
     };
+    /** High-level spectral features derived from the FFT. */
     spectral: {
+        /** Normalized spectral centroid in 0..1 — higher values mean brighter, more treble-heavy sound. */
         brightness: number;
+        /** Normalized spectral flatness in 0..1 — higher values mean noisier (white-noise-like) sound; lower values mean tonal. */
         flatness: number;
     };
+    /**
+     * Returns the raw FFT magnitude spectrum as a `Uint8Array` (1024 bins, each 0..255).
+     * Bin `i` covers frequency `i × (sampleRate / fftSize)`. The returned array is a
+     * snapshot from the latest analysis tick — repeated calls in the same frame return the same data.
+     *
+     * @example
+     * const fft = viji.audio.getFrequencyData();
+     * for (let i = 0; i < fft.length; i++) drawBar(i, fft[i] / 255);
+     */
     getFrequencyData: () => Uint8Array;
+    /**
+     * Returns the raw time-domain waveform as a `Float32Array` (2048 PCM samples in -1..1).
+     * The returned array is a snapshot — repeated calls in the same frame return the same data.
+     *
+     * @example
+     * const wave = viji.audio.getWaveform();
+     * for (let i = 0; i < wave.length; i++) drawSample(i, wave[i]);
+     */
     getWaveform: () => Float32Array;
 }
 
+/**
+ * Lightweight audio analysis for additional or device audio streams. A strict
+ * subset of `AudioAPI` — exposes volume, frequency bands, spectral features,
+ * and raw FFT/waveform access, but **no beat detection** (no `beat`, no BPM,
+ * no triggers, no events).
+ */
 declare interface AudioStreamAPI {
+    /** `true` when this audio stream is connected; otherwise all numeric fields read as `0`. */
     isConnected: boolean;
+    /** Overall loudness across the stream. */
     volume: {
+        /** Instantaneous RMS volume in 0..1. */
         current: number;
+        /** Instantaneous peak amplitude in 0..1. */
         peak: number;
+        /** Volume with a 200ms decay envelope. */
         smoothed: number;
     };
+    /** Energy in five fixed frequency bands, plus a smoothed companion (~150ms decay) for each. All in 0..1. */
     bands: {
+        /** Instant low-band energy (20–120 Hz). 0..1. */
         low: number;
+        /** Instant low-mid energy (120–400 Hz). 0..1. */
         lowMid: number;
+        /** Instant mid energy (400–1600 Hz). 0..1. */
         mid: number;
+        /** Instant high-mid energy (1600–6000 Hz). 0..1. */
         highMid: number;
+        /** Instant high-band energy (6000–16000 Hz). 0..1. */
         high: number;
+        /** Smoothed `low` (~150ms decay). 0..1. */
         lowSmoothed: number;
+        /** Smoothed `lowMid` (~150ms decay). 0..1. */
         lowMidSmoothed: number;
+        /** Smoothed `mid` (~150ms decay). 0..1. */
         midSmoothed: number;
+        /** Smoothed `highMid` (~150ms decay). 0..1. */
         highMidSmoothed: number;
+        /** Smoothed `high` (~150ms decay). 0..1. */
         highSmoothed: number;
     };
+    /** High-level spectral features derived from the FFT. */
     spectral: {
+        /** Normalized spectral centroid in 0..1. */
         brightness: number;
+        /** Normalized spectral flatness in 0..1. */
         flatness: number;
     };
+    /**
+     * Returns the raw FFT magnitude spectrum for this stream as a `Uint8Array`
+     * (1024 bins, each 0..255). Snapshot semantics — see `AudioAPI.getFrequencyData`.
+     */
     getFrequencyData: () => Uint8Array;
+    /**
+     * Returns the raw time-domain waveform for this stream as a `Float32Array`
+     * (2048 samples, each -1..1). Snapshot semantics — see `AudioAPI.getWaveform`.
+     */
     getWaveform: () => Float32Array;
 }
 
@@ -576,72 +673,178 @@ declare interface BeatEvent {
     bands?: string[];
 }
 
+/**
+ * Configuration object passed to `viji.button()`. The host renders a clickable
+ * momentary button — the resulting `value` is `true` for one frame after press,
+ * then auto-resets to `false`.
+ */
 declare interface ButtonConfig {
+    /** Display name shown on the button in the parameter UI. Required. */
     label: string;
+    /** Optional tooltip / help text shown next to the control. */
     description?: string;
+    /** Group name for organizing related parameters under a shared heading. Default: `'general'`. */
     group?: string;
+    /** 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
+ * `false`. Use it to trigger discrete events from `render()`.
+ */
 declare interface ButtonParameter {
+    /** `true` for the single frame after the user clicks the button, `false` otherwise. */
     value: boolean;
+    /** Display name shown on the button in the parameter UI. */
     label: string;
+    /** Tooltip / help text for the control (empty string when not configured). */
     description?: string;
+    /** Group name under which the control appears in the UI. */
     group: string;
+    /** Visibility category — 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.
+ */
 export declare interface CaptureFrameOptions {
-    /** Output format: 'blob' for encoded image, 'bitmap' for GPU-friendly ImageBitmap */
+    /** Output format: `'blob'` for an encoded image, `'bitmap'` for a GPU-friendly `ImageBitmap`. Default: `'blob'`. */
     format?: 'blob' | 'bitmap';
-    /** MIME type for blob output (ignored for bitmap), e.g., 'image/png', 'image/jpeg', 'image/webp' */
+    /** MIME type for `'blob'` output (ignored for `'bitmap'`). Examples: `'image/png'`, `'image/jpeg'`, `'image/webp'`. */
     type?: string;
     /**
      * Target resolution.
-     * - number: scale factor relative to current canvas size (e.g., 0.5 = 50%)
-     * - { width, height }: exact output size; if aspect ratio differs from canvas,
-     *   the source is center-cropped to match the target aspect ratio before scaling
+     * - `number`: scale factor relative to the current canvas size (e.g., `0.5` = 50%).
+     * - `Resolution`: exact output size. If the aspect ratio differs from the
+     *   canvas, the source is center-cropped before scaling.
      */
-    resolution?: number | {
-        width: number;
-        height: number;
-    };
+    resolution?: number | Resolution;
 }
 
+/**
+ * Configuration object passed to `viji.color()`. Defines the color picker's
+ * label and UI grouping/visibility.
+ */
 declare interface ColorConfig {
+    /** Display name shown next to the color swatch in the parameter UI. Required. */
     label: string;
+    /** Optional tooltip / help text shown next to the control. */
     description?: string;
+    /** Group name for organizing related parameters under a shared heading. Default: `'general'`. */
     group?: string;
+    /** 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.
+ *
+ * - `string`: hex (`#rrggbb`, `#rgb`), CSS `rgb(r, g, b)`, CSS `hsl(h, s%, l%)`,
+ *   GLSL-style `vec3(r, g, b)` (0..1), or P5-style `hsb(h, s, b)` (0..360 / 0..100 / 0..100)
+ * - `{ r, g, b }`: RGB object with components in 0..255
+ * - `{ h, s, b }`: HSB object with `h` in 0..360, `s` and `b` in 0..100
+ */
+declare type ColorInput = string | {
+    /** Red component in 0..255. */
+    r: number;
+    /** Green component in 0..255. */
+    g: number;
+    /** Blue component in 0..255. */
+    b: number;
+} | {
+    /** Hue in 0..360. */
+    h: number;
+    /** Saturation in 0..100. */
+    s: number;
+    /** 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
+ * recomputed (and frozen) every time the user changes the color.
+ */
 declare interface ColorParameter {
+    /** Canonical hex color string `#rrggbb` (lowercase). Updates in real-time. */
     value: string;
+    /** RGB components as integers in 0..255 (frozen, recomputed when value changes). */
+    rgb: {
+        /** Red component, integer in 0..255. */
+        r: number;
+        /** Green component, integer in 0..255. */
+        g: number;
+        /** Blue component, integer in 0..255. */
+        b: number;
+    };
+    /** HSB components: `h` in 0..360, `s` and `b` in 0..100 (frozen, recomputed when value changes). */
+    hsb: {
+        /** Hue in 0..360. */
+        h: number;
+        /** Saturation in 0..100. */
+        s: number;
+        /** Brightness in 0..100. */
+        b: number;
+    };
+    /** Display name shown next to the swatch in the parameter UI. */
     label: string;
+    /** Tooltip / help text for the control (empty string when not configured). */
     description?: string;
+    /** Group name under which the control appears in the UI. */
     group: string;
+    /** Visibility category — 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`.
+ */
 declare interface CoordinateConfig {
+    /** Snap increment for both `x` and `y` components. Default: `0.01`. */
     step?: number;
+    /** Display name shown next to the pad in the parameter UI. Required. */
     label: string;
+    /** Optional tooltip / help text shown next to the control. */
     description?: string;
+    /** Group name for organizing related parameters under a shared heading. Default: `'general'`. */
     group?: string;
+    /** 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.
+ */
 declare interface CoordinateParameter {
+    /** Current `{ x, y }` position. Both components are in `-1..1`. Updates in real-time. */
     value: CoordinateValue;
+    /** Snap increment for both `x` and `y` components. */
     step: number;
+    /** Display name shown next to the pad in the parameter UI. */
     label: string;
+    /** Tooltip / help text for the control (empty string when not configured). */
     description?: string;
+    /** Group name under which the control appears in the UI. */
     group: string;
+    /** Visibility category — 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()`.
+ */
 declare type CoordinateValue = {
+    /** Horizontal axis in `-1..1` (left to right, `0` = canvas center). */
     x: number;
+    /** Vertical axis in `-1..1` (bottom to top, `0` = canvas center). */
     y: number;
 };
 
@@ -656,34 +859,55 @@ declare interface CoreCapabilities {
     hasGeneral: boolean;
 }
 
+/**
+ * Identifier for an individual computer-vision feature pipeline. Returned by
+ * `VideoAPI.cv.getActiveFeatures()` and used internally to track state.
+ */
 declare 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.
+ */
 declare type CVFrameRateMode = 'full' | 'half' | 'quarter' | 'eighth';
 
 /**
- * DeviceMotionEvent acceleration data
- * Matches native DeviceMotionEvent.acceleration structure
+ * Device motion data sourced from the platform's `DeviceMotionEvent`. All
+ * accelerations are in metres per second squared (m/s²); rotation rates are
+ * in degrees per second. Inner objects may be `null` when the underlying
+ * sensor is unavailable, and individual axes may be `null` on platforms that
+ * report only some components.
  */
 declare interface DeviceMotionData {
-    /** Acceleration without gravity (m/s²) */
+    /** Acceleration without gravity (m/s²). `null` when no accelerometer is available. */
     acceleration: {
+        /** Acceleration along the device's X axis in m/s². `null` if unsupported. */
         x: number | null;
+        /** Acceleration along the device's Y axis in m/s². `null` if unsupported. */
         y: number | null;
+        /** Acceleration along the device's Z axis in m/s². `null` if unsupported. */
         z: number | null;
     } | null;
-    /** Acceleration including gravity (m/s²) */
+    /** Acceleration including gravity (m/s²). `null` when no accelerometer is available. */
     accelerationIncludingGravity: {
+        /** Acceleration including gravity along the device's X axis in m/s². `null` if unsupported. */
         x: number | null;
+        /** Acceleration including gravity along the device's Y axis in m/s². `null` if unsupported. */
         y: number | null;
+        /** Acceleration including gravity along the device's Z axis in m/s². `null` if unsupported. */
         z: number | null;
     } | null;
-    /** Rotation rate (degrees/second) */
+    /** Angular rotation rate (degrees per second). `null` when no gyroscope is available. */
     rotationRate: {
+        /** Rotation rate around the device's Z axis in deg/s. `null` if unsupported. */
         alpha: number | null;
+        /** Rotation rate around the device's X axis in deg/s. `null` if unsupported. */
         beta: number | null;
+        /** Rotation rate around the device's Y axis in deg/s. `null` if unsupported. */
         gamma: number | null;
     } | null;
-    /** Interval between updates (milliseconds) */
+    /** Interval between sensor updates in milliseconds. */
     interval: number;
 }
 
@@ -703,10 +927,13 @@ declare interface DeviceOrientationData {
 }
 
 /**
- * Complete device sensor state (internal device - no id/name)
+ * 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.
  */
 declare interface DeviceSensorState {
+    /** Motion data (acceleration, rotation rate, sampling interval). `null` if no motion sensor is available. */
     motion: DeviceMotionData | null;
+    /** Orientation data (alpha/beta/gamma in degrees). `null` if no orientation sensor is available. */
     orientation: DeviceOrientationData | null;
 }
 
@@ -724,93 +951,183 @@ declare interface DeviceState extends DeviceSensorState {
     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
+ * enabled. Available on each `FaceData.blendshapes`.
+ */
 declare interface FaceBlendshapes {
+    /** Coefficient (0..1) for the inner brow of the left eye pulling down. */
     browDownLeft: number;
+    /** Coefficient (0..1) for the inner brow of the right eye pulling down. */
     browDownRight: number;
+    /** Coefficient (0..1) for both inner brows pulling up. */
     browInnerUp: number;
+    /** Coefficient (0..1) for the outer left brow pulling up. */
     browOuterUpLeft: number;
+    /** Coefficient (0..1) for the outer right brow pulling up. */
     browOuterUpRight: number;
+    /** Coefficient (0..1) for puffed cheeks. */
     cheekPuff: number;
+    /** Coefficient (0..1) for the left cheek squinting. */
     cheekSquintLeft: number;
+    /** Coefficient (0..1) for the right cheek squinting. */
     cheekSquintRight: number;
+    /** Coefficient (0..1) for the left eyelid closing. */
     eyeBlinkLeft: number;
+    /** Coefficient (0..1) for the right eyelid closing. */
     eyeBlinkRight: number;
+    /** Coefficient (0..1) for the left eye looking down. */
     eyeLookDownLeft: number;
+    /** Coefficient (0..1) for the right eye looking down. */
     eyeLookDownRight: number;
+    /** Coefficient (0..1) for the left eye looking inward (toward the nose). */
     eyeLookInLeft: number;
+    /** Coefficient (0..1) for the right eye looking inward. */
     eyeLookInRight: number;
+    /** Coefficient (0..1) for the left eye looking outward (away from the nose). */
     eyeLookOutLeft: number;
+    /** Coefficient (0..1) for the right eye looking outward. */
     eyeLookOutRight: number;
+    /** Coefficient (0..1) for the left eye looking up. */
     eyeLookUpLeft: number;
+    /** Coefficient (0..1) for the right eye looking up. */
     eyeLookUpRight: number;
+    /** Coefficient (0..1) for the left eye squinting. */
     eyeSquintLeft: number;
+    /** Coefficient (0..1) for the right eye squinting. */
     eyeSquintRight: number;
+    /** Coefficient (0..1) for the left eye opening wide. */
     eyeWideLeft: number;
+    /** Coefficient (0..1) for the right eye opening wide. */
     eyeWideRight: number;
+    /** Coefficient (0..1) for the jaw moving forward. */
     jawForward: number;
+    /** Coefficient (0..1) for the jaw moving left. */
     jawLeft: number;
+    /** Coefficient (0..1) for the jaw opening (mouth open). */
     jawOpen: number;
+    /** Coefficient (0..1) for the jaw moving right. */
     jawRight: number;
+    /** Coefficient (0..1) for the mouth closing tightly. */
     mouthClose: number;
+    /** Coefficient (0..1) for a dimple appearing on the left side. */
     mouthDimpleLeft: number;
+    /** Coefficient (0..1) for a dimple appearing on the right side. */
     mouthDimpleRight: number;
+    /** Coefficient (0..1) for the left mouth corner pulling down (frown). */
     mouthFrownLeft: number;
+    /** Coefficient (0..1) for the right mouth corner pulling down (frown). */
     mouthFrownRight: number;
+    /** Coefficient (0..1) for funneling the lips outward. */
     mouthFunnel: number;
+    /** Coefficient (0..1) for the mouth shifting left. */
     mouthLeft: number;
+    /** Coefficient (0..1) for the lower lip on the left pulling down. */
     mouthLowerDownLeft: number;
+    /** Coefficient (0..1) for the lower lip on the right pulling down. */
     mouthLowerDownRight: number;
+    /** Coefficient (0..1) for the left lip pressing inward. */
     mouthPressLeft: number;
+    /** Coefficient (0..1) for the right lip pressing inward. */
     mouthPressRight: number;
+    /** Coefficient (0..1) for puckered lips. */
     mouthPucker: number;
+    /** Coefficient (0..1) for the mouth shifting right. */
     mouthRight: number;
+    /** Coefficient (0..1) for the lower lip rolling inward. */
     mouthRollLower: number;
+    /** Coefficient (0..1) for the upper lip rolling inward. */
     mouthRollUpper: number;
+    /** Coefficient (0..1) for the lower lip shrugging. */
     mouthShrugLower: number;
+    /** Coefficient (0..1) for the upper lip shrugging. */
     mouthShrugUpper: number;
+    /** Coefficient (0..1) for the left mouth corner pulling up (smile). */
     mouthSmileLeft: number;
+    /** Coefficient (0..1) for the right mouth corner pulling up (smile). */
     mouthSmileRight: number;
+    /** Coefficient (0..1) for the left mouth corner stretching outward. */
     mouthStretchLeft: number;
+    /** Coefficient (0..1) for the right mouth corner stretching outward. */
     mouthStretchRight: number;
+    /** Coefficient (0..1) for the upper lip on the left raising. */
     mouthUpperUpLeft: number;
+    /** Coefficient (0..1) for the upper lip on the right raising. */
     mouthUpperUpRight: number;
+    /** Coefficient (0..1) for the left side of the nose sneering. */
     noseSneerLeft: number;
+    /** Coefficient (0..1) for the right side of the nose sneering. */
     noseSneerRight: number;
+    /** 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`).
+ */
 export declare 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. */
     bounds: {
+        /** Left edge of the face bounding box, normalized 0..1. */
         x: number;
+        /** Top edge of the face bounding box, normalized 0..1. */
         y: number;
+        /** Width of the face bounding box, normalized 0..1. */
         width: number;
+        /** Height of the face bounding box, normalized 0..1. */
         height: number;
     };
+    /** Center of the bounding box, normalized 0..1. */
     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;
+    /** 468 normalized face mesh landmarks when face mesh is enabled; empty array otherwise. */
     landmarks: {
+        /** Horizontal landmark coordinate, normalized 0..1. */
         x: number;
+        /** Vertical landmark coordinate, normalized 0..1. */
         y: number;
+        /** Optional depth (relative). */
         z?: number;
     }[];
+    /** Seven expression confidence scores in 0..1. All zero unless emotion detection is enabled. */
     expressions: {
+        /** Confidence (0..1) of a neutral expression. */
         neutral: number;
+        /** Confidence (0..1) of a happy / smiling expression. */
         happy: number;
+        /** Confidence (0..1) of a sad expression. */
         sad: number;
+        /** Confidence (0..1) of an angry expression. */
         angry: number;
+        /** Confidence (0..1) of a surprised expression. */
         surprised: number;
+        /** Confidence (0..1) of a disgusted expression. */
         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). */
         pitch: number;
+        /** Left/right rotation in degrees (-90..90). */
         yaw: number;
+        /** Tilt rotation in degrees (-180..180). */
         roll: number;
     };
+    /** 52 ARKit-compatible facial muscle coefficients. All zero unless emotion detection is enabled. */
     blendshapes: FaceBlendshapes;
 }
 
@@ -820,77 +1137,165 @@ declare interface FrameRateInfo {
     effectiveRefreshRate: number;
 }
 
+/**
+ * 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.
+ */
 declare 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.
+ */
 export declare interface FrequencyBand {
+    /** Human-readable band name (e.g., `'low'`, `'mid'`, `'high'`). */
     name: string;
+    /** Lower edge of the band in Hertz (inclusive). */
     min: number;
+    /** 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
+ * hands appear in `VideoAPI.hands` simultaneously.
+ */
 export declare interface HandData {
+    /** Index-based hand identifier (`0` or `1`). */
     id: number;
+    /** Which hand. Always lowercase. */
     handedness: 'left' | 'right';
+    /** Detection confidence in 0..1. */
     confidence: number;
+    /** Bounding box, all components normalized to 0..1 of the source frame. */
     bounds: {
+        /** Left edge of the hand bounding box, normalized 0..1. */
         x: number;
+        /** Top edge of the hand bounding box, normalized 0..1. */
         y: number;
+        /** Width of the hand bounding box, normalized 0..1. */
         width: number;
+        /** Height of the hand bounding box, normalized 0..1. */
         height: number;
     };
+    /** 21 MediaPipe hand landmarks, normalized 0..1. */
     landmarks: {
+        /** Horizontal landmark coordinate, normalized 0..1. */
         x: number;
+        /** Vertical landmark coordinate, normalized 0..1. */
         y: number;
+        /** Depth (relative). */
         z: number;
     }[];
+    /** Palm center — equivalent to `landmarks[9]` (middle-finger MCP). */
     palm: {
+        /** Palm horizontal coordinate, normalized 0..1. */
         x: number;
+        /** Palm vertical coordinate, normalized 0..1. */
         y: number;
+        /** Palm depth (relative). */
         z: number;
     };
+    /**
+     * ML-classified gesture confidences from MediaPipe GestureRecognizer.
+     * Each value is in 0..1; multiple gestures can fire simultaneously.
+     */
     gestures: {
+        /** Confidence (0..1) of a closed-fist gesture. */
         fist: number;
+        /** Confidence (0..1) of an open-palm gesture. */
         openPalm: number;
+        /** Confidence (0..1) of a peace / victory sign. */
         peace: number;
+        /** Confidence (0..1) of a thumbs-up gesture. */
         thumbsUp: number;
+        /** Confidence (0..1) of a thumbs-down gesture. */
         thumbsDown: number;
+        /** Confidence (0..1) of a pointing-up gesture. */
         pointing: number;
+        /** Confidence (0..1) of the ASL "I love you" sign. */
         iLoveYou: number;
     };
 }
 
+/**
+ * Configuration object passed to `viji.image()`. The host renders an upload
+ * field; the user-supplied image becomes available as an `ImageBitmap` (Native)
+ * or a P5 image wrapper (P5 renderer).
+ */
 declare interface ImageConfig {
+    /** Display name shown next to the upload field in the parameter UI. Required. */
     label: string;
+    /** Optional tooltip / help text shown next to the control. */
     description?: string;
+    /** Group name for organizing related parameters under a shared heading. Default: `'general'`. */
     group?: string;
+    /** 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
+ * the image works directly with `image()`, `texture()`, etc.
+ */
 declare interface ImageParameter {
+    /** Uploaded image as an `ImageBitmap`, or `null` until the user provides one. */
     value: ImageBitmap | null;
     /** P5-compatible image wrapper. Only available in the P5 renderer — added at runtime by the P5 adapter. */
     readonly p5?: any;
+    /** Display name shown next to the upload field in the parameter UI. */
     label: string;
+    /** Tooltip / help text for the control (empty string when not configured). */
     description?: string;
+    /** Group name under which the control appears in the UI. */
     group: string;
+    /** Visibility category — controls when the parameter is shown. */
     category: ParameterCategory;
 }
 
 declare type InstrumentType = 'kick' | 'snare' | 'hat';
 
+/**
+ * Keyboard input state for the current frame: per-key press / hold / release
+ * queries (case-insensitive), the live set of held keys, modifier flags, and
+ * a Shadertoy-compatible texture buffer for shader-side keyboard reads.
+ *
+ * Key names follow the browser's `event.key` standard
+ * (`'a'`, `'arrowup'`, `' '` for Space, `'enter'`, `'escape'`, etc.).
+ */
 export declare interface KeyboardAPI {
+    /** Returns `true` while the named key is held. Case-insensitive. */
     isPressed(key: string): boolean;
+    /** Returns `true` for exactly one frame on the rising edge of the named key (no key-repeat). Case-insensitive. */
     wasPressed(key: string): boolean;
+    /** Returns `true` for exactly one frame on the falling edge of the named key. Case-insensitive. */
     wasReleased(key: string): boolean;
+    /** Set of all currently held keys, lowercased. Persists across frames. */
     activeKeys: Set<string>;
+    /** Set of keys whose key-down fired this frame, lowercased. Cleared each frame. */
     pressedThisFrame: Set<string>;
+    /** Set of keys whose key-up fired this frame, lowercased. Cleared each frame. */
     releasedThisFrame: Set<string>;
+    /** Most recently pressed key in its original case (e.g., `'A'` when Shift is held). */
     lastKeyPressed: string;
+    /** Most recently released key in its original case. */
     lastKeyReleased: string;
+    /** `true` while the Shift key is held. */
     shift: boolean;
+    /** `true` while the Ctrl key is held. */
     ctrl: boolean;
+    /** `true` while the Alt (or Option) key is held. */
     alt: boolean;
+    /** `true` while the Meta (Windows / Cmd) key is held. */
     meta: boolean;
+    /**
+     * Shadertoy-compatible 256×3 keyboard texture (256 keycodes × 3 rows).
+     * Row 0: held state (1 / 0). Row 1: pressed-this-frame (1 / 0). Row 2: per-key toggle.
+     * Bound to a uniform sampler in shader scenes; rarely needed in JS.
+     */
     textureData: Uint8Array;
 }
 
@@ -904,21 +1309,43 @@ export declare interface KeyboardEventData {
     metaKey: boolean;
 }
 
+/**
+ * Mouse input state for the current frame: position, individual button states,
+ * per-frame movement, scroll wheel, and frame-based press / release events.
+ * Coordinates are in canvas-space pixels with `(0, 0)` at the top-left corner.
+ *
+ * For interactions that should also work on touch devices, prefer `viji.pointer`.
+ */
 export declare interface MouseAPI {
+    /** Canvas-space X position in pixels. */
     x: number;
+    /** Canvas-space Y position in pixels. */
     y: number;
+    /** `true` when the cursor is currently over the canvas. */
     isInCanvas: boolean;
+    /** `true` if any mouse button is currently held. */
     isPressed: boolean;
+    /** `true` while the left mouse button is held. */
     leftButton: boolean;
+    /** `true` while the right mouse button is held. The browser context menu is suppressed on the canvas. */
     rightButton: boolean;
+    /** `true` while the middle (wheel) mouse button is held. */
     middleButton: boolean;
+    /** Horizontal movement this frame in pixels. Resets to `0` each frame. */
     deltaX: number;
+    /** Vertical movement this frame in pixels. Resets to `0` each frame. */
     deltaY: number;
+    /** Vertical scroll accumulated this frame (alias of `wheelY`). Resets to `0` each frame. */
     wheelDelta: number;
+    /** Horizontal scroll accumulated this frame (e.g., trackpad gestures, tilt-wheel mice). Resets to `0` each frame. */
     wheelX: number;
+    /** Vertical scroll accumulated this frame. Resets to `0` each frame. */
     wheelY: number;
+    /** `true` for exactly one frame when any button is first pressed, then auto-resets. */
     wasPressed: boolean;
+    /** `true` for exactly one frame when any button is released, then auto-resets. */
     wasReleased: boolean;
+    /** `true` if the mouse moved this frame (any non-zero `deltaX` / `deltaY`). Resets each frame. */
     wasMoved: boolean;
 }
 
@@ -933,24 +1360,47 @@ export declare interface MouseEventData {
     isInCanvas?: boolean;
 }
 
+/**
+ * Configuration object passed to `viji.number()`. Defines the bounds, step,
+ * label, and UI grouping/visibility for a precise numeric input.
+ */
 declare interface NumberConfig {
+    /** Inclusive minimum value. Default: `0`. */
     min?: number;
+    /** Inclusive maximum value. Default: `100`. */
     max?: number;
+    /** Increment between values. Default: `1`. */
     step?: number;
+    /** Display name shown next to the input in the parameter UI. Required. */
     label: string;
+    /** Optional tooltip / help text shown next to the control. */
     description?: string;
+    /** Group name for organizing related parameters under a shared heading. Default: `'general'`. */
     group?: string;
+    /** 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.
+ */
 declare interface NumberParameter {
+    /** Current numeric value in the configured `min..max` range. Updates in real-time. */
     value: number;
+    /** Inclusive minimum value. */
     min: number;
+    /** Inclusive maximum value. */
     max: number;
+    /** Increment between values. */
     step: number;
+    /** Display name shown next to the input in the parameter UI. */
     label: string;
+    /** Tooltip / help text for the control (empty string when not configured). */
     description?: string;
+    /** Group name under which the control appears in the UI. */
     group: string;
+    /** Visibility category — controls when the parameter is shown. */
     category: ParameterCategory;
 }
 
@@ -963,6 +1413,11 @@ export declare interface ParameterAPI {
     [key: string]: any;
 }
 
+/**
+ * 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.
+ */
 declare type ParameterCategory = 'audio' | 'video' | 'interaction' | 'general';
 
 export declare interface ParameterConfig {
@@ -1052,141 +1507,290 @@ declare interface PLLState {
     driftRate: number;
 }
 
+/**
+ * Unified pointer that abstracts mouse and primary touch into a single input
+ * stream. Recommended for click / drag / position-tracking interactions that
+ * should work identically on desktop and mobile.
+ *
+ * Use `viji.mouse` for mouse-specific features (right click, middle click,
+ * scroll wheel); use `viji.touches` for multi-touch, pressure, or radius.
+ */
 declare interface PointerAPI {
+    /** Canvas-space X position in pixels. */
     x: number;
+    /** Canvas-space Y position in pixels. */
     y: number;
+    /** Horizontal movement since the last frame in pixels. */
     deltaX: number;
+    /** Vertical movement since the last frame in pixels. */
     deltaY: number;
+    /** `true` while the pointer is "down" — left mouse button held, or a touch active. */
     isDown: boolean;
+    /** `true` for exactly one frame when the pointer becomes down, then auto-resets. */
     wasPressed: boolean;
+    /** `true` for exactly one frame when the pointer is released, then auto-resets. */
     wasReleased: boolean;
+    /** `true` while the pointer is within the canvas bounds. */
     isInCanvas: boolean;
+    /** 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
+ * are pre-grouped slices for convenience.
+ */
 declare interface PoseData {
+    /** Average landmark visibility in 0..1. */
     confidence: number;
+    /** 33 BlazePose landmarks, normalized 0..1. Each carries a per-point `visibility` score. */
     landmarks: {
+        /** Horizontal landmark coordinate, normalized 0..1. */
         x: number;
+        /** Vertical landmark coordinate, normalized 0..1. */
         y: number;
+        /** Depth (relative). */
         z: number;
+        /** Visibility / confidence of this individual landmark in 0..1. */
         visibility: number;
     }[];
+    /** Face landmarks (BlazePose indices 0..10). Coordinates normalized 0..1. */
     face: {
+        /** Horizontal landmark coordinate, normalized 0..1. */
         x: number;
+        /** Vertical landmark coordinate, normalized 0..1. */
         y: number;
     }[];
+    /** Torso landmarks (BlazePose indices 11, 12, 23, 24). Coordinates normalized 0..1. */
     torso: {
+        /** Horizontal landmark coordinate, normalized 0..1. */
         x: number;
+        /** Vertical landmark coordinate, normalized 0..1. */
         y: number;
     }[];
+    /** Left-arm landmarks (BlazePose indices 11, 13, 15). Coordinates normalized 0..1. */
     leftArm: {
+        /** Horizontal landmark coordinate, normalized 0..1. */
         x: number;
+        /** Vertical landmark coordinate, normalized 0..1. */
         y: number;
     }[];
+    /** Right-arm landmarks (BlazePose indices 12, 14, 16). Coordinates normalized 0..1. */
     rightArm: {
+        /** Horizontal landmark coordinate, normalized 0..1. */
         x: number;
+        /** Vertical landmark coordinate, normalized 0..1. */
         y: number;
     }[];
+    /** Left-leg landmarks (BlazePose indices 23, 25, 27, 29, 31). Coordinates normalized 0..1. */
     leftLeg: {
+        /** Horizontal landmark coordinate, normalized 0..1. */
         x: number;
+        /** Vertical landmark coordinate, normalized 0..1. */
         y: number;
     }[];
+    /** Right-leg landmarks (BlazePose indices 24, 26, 28, 30, 32). Coordinates normalized 0..1. */
     rightLeg: {
+        /** Horizontal landmark coordinate, normalized 0..1. */
         x: number;
+        /** Vertical landmark coordinate, normalized 0..1. */
         y: number;
     }[];
 }
 
 declare type RendererType = 'native' | 'p5' | 'shader';
 
+/**
+ * Discrete pixel dimensions for a canvas, frame capture, or render target.
+ */
 export declare type Resolution = {
+    /** Width in pixels (positive integer). */
     width: number;
+    /** 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.
+ */
 declare interface SegmentationData {
+    /** Flat per-pixel mask: each byte is `0` (background) or `1` (person). Length = `width * height`. */
     mask: Uint8Array;
+    /** Mask width in pixels. */
     width: number;
+    /** Mask height in pixels. */
     height: number;
 }
 
+/**
+ * Configuration object passed to `viji.select()`. The host renders the choices
+ * as a dropdown or segmented control.
+ */
 declare interface SelectConfig {
+    /** Available choices. The element type (`string` or `number`) becomes the parameter's value type. Required. */
     options: string[] | number[];
+    /** Display name shown next to the dropdown in the parameter UI. Required. */
     label: string;
+    /** Optional tooltip / help text shown next to the control. */
     description?: string;
+    /** Group name for organizing related parameters under a shared heading. Default: `'general'`. */
     group?: string;
+    /** 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`).
+ */
 declare interface SelectParameter {
+    /** Currently selected option. Updates in real-time when the user changes the selection. */
     value: string | number;
+    /** The full list of choices originally configured. */
     options: string[] | number[];
+    /** Display name shown next to the dropdown in the parameter UI. */
     label: string;
+    /** Tooltip / help text for the control (empty string when not configured). */
     description?: string;
+    /** Group name under which the control appears in the UI. */
     group: string;
+    /** Visibility category — 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.
+ */
 declare interface SliderConfig {
+    /** Inclusive minimum value of the slider. Default: `0`. */
     min?: number;
+    /** Inclusive maximum value of the slider. Default: `100`. */
     max?: number;
+    /** Increment between values. Default: `1`. */
     step?: number;
+    /** Display name shown next to the control in the parameter UI. Required. */
     label: string;
+    /** Optional tooltip / help text shown next to the control. */
     description?: string;
+    /** Group name for organizing related parameters under a shared heading. Default: `'general'`. */
     group?: string;
+    /** 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.
+ */
 declare interface SliderParameter {
+    /** Current slider value in the configured `min..max` range. Updates in real-time. */
     value: number;
+    /** Inclusive minimum value of the slider. */
     min: number;
+    /** Inclusive maximum value of the slider. */
     max: number;
+    /** Increment between values. */
     step: number;
+    /** Display name shown next to the control in the parameter UI. */
     label: string;
+    /** Tooltip / help text for the control (empty string when not configured). */
     description?: string;
+    /** Group name under which the control appears in the UI. */
     group: string;
+    /** Visibility category — controls when the parameter is shown. */
     category: ParameterCategory;
 }
 
+/**
+ * Configuration object passed to `viji.text()`. The host renders a single-line
+ * text input field.
+ */
 declare interface TextConfig {
+    /** Display name shown next to the text field in the parameter UI. Required. */
     label: string;
+    /** Optional tooltip / help text shown next to the control. */
     description?: string;
+    /** Group name for organizing related parameters under a shared heading. Default: `'general'`. */
     group?: string;
+    /** Visibility category — the control hides when its capability is unavailable. Default: `'general'`. */
     category?: ParameterCategory;
+    /** 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.
+ */
 declare interface TextParameter {
+    /** Current text content. Updates in real-time as the user types. */
     value: string;
+    /** Maximum character count enforced by the host UI. */
     maxLength?: number;
+    /** Display name shown next to the input in the parameter UI. */
     label: string;
+    /** Tooltip / help text for the control (empty string when not configured). */
     description?: string;
+    /** Group name under which the control appears in the UI. */
     group: string;
+    /** Visibility category — 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.
+ */
 declare interface ToggleConfig {
+    /** Display name shown next to the switch in the parameter UI. Required. */
     label: string;
+    /** Optional tooltip / help text shown next to the control. */
     description?: string;
+    /** Group name for organizing related parameters under a shared heading. Default: `'general'`. */
     group?: string;
+    /** 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.
+ */
 declare interface ToggleParameter {
+    /** Current state of the switch. Updates in real-time when the user toggles it. */
     value: boolean;
+    /** Display name shown next to the switch in the parameter UI. */
     label: string;
+    /** Tooltip / help text for the control (empty string when not configured). */
     description?: string;
+    /** Group name under which the control appears in the UI. */
     group: string;
+    /** Visibility category — 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.
+ *
+ * For single-point interactions that should also work with a mouse, prefer
+ * `viji.pointer` — it switches automatically between mouse and primary touch.
+ */
 export declare interface TouchAPI {
+    /** All currently active touch points. Order is stable but not ordered by id. */
     points: TouchPoint[];
+    /** Number of currently active touches (equivalent to `points.length`). */
     count: number;
+    /** Touches that started this frame (also visible in `points`). Cleared each frame. */
     started: TouchPoint[];
+    /** Touches that moved this frame. Cleared each frame. */
     moved: TouchPoint[];
+    /** Touches that ended this frame. Each entry has `isEnding === true`. Cleared each frame. */
     ended: TouchPoint[];
+    /** Convenience shortcut to `points[0]`, or `null` when no touches are active. */
     primary: TouchPoint | null;
 }
 
@@ -1204,25 +1808,52 @@ export declare interface TouchEventData {
     }>;
 }
 
+/**
+ * One active touch contact reported by `TouchAPI`. Position, pressure, radius,
+ * rotation, per-frame movement, velocity, and lifecycle flags. Coordinates are
+ * in canvas-space pixels.
+ *
+ * Some fields (notably `pressure` / `force`, `radiusX` / `radiusY`,
+ * `rotationAngle`) are passed through from the device — values vary by
+ * platform; many devices report `0` when unsupported.
+ */
 declare interface TouchPoint {
+    /** Stable touch identifier across frames for the duration of this contact. */
     id: number;
+    /** Canvas-space X position in pixels. */
     x: number;
+    /** Canvas-space Y position in pixels. */
     y: number;
+    /** Touch pressure in 0..1 (device-dependent; often `0` on devices without force support). */
     pressure: number;
+    /** Contact radius — `Math.max(radiusX, radiusY)` in pixels. */
     radius: number;
+    /** Horizontal contact radius in pixels (raw device value). */
     radiusX: number;
+    /** Vertical contact radius in pixels (raw device value). */
     radiusY: number;
+    /** Contact area rotation in radians (raw device value). */
     rotationAngle: number;
+    /** Touch force in 0..1 — alias of `pressure`. */
     force: number;
+    /** `true` while the touch position is within the canvas bounds. */
     isInCanvas: boolean;
+    /** Horizontal movement since the last frame in pixels. */
     deltaX: number;
+    /** Vertical movement since the last frame in pixels. */
     deltaY: number;
+    /** Movement velocity in pixels per second, computed by Viji. */
     velocity: {
+        /** Horizontal velocity component in pixels per second. */
         x: number;
+        /** Vertical velocity component in pixels per second. */
         y: number;
     };
+    /** `true` for exactly one frame when this touch starts, then auto-resets. */
     isNew: boolean;
+    /** `true` while the touch is ongoing. */
     isActive: boolean;
+    /** `true` for exactly one frame when this touch ends, then auto-resets. */
     isEnding: boolean;
 }
 
@@ -1234,25 +1865,81 @@ declare type TrackingState = 'TRACKING' | 'LOCKED' | 'BREAKDOWN' | 'LOST';
 
 export declare const VERSION = "0.3.29";
 
+/**
+ * Real-time video API: drawable frame, dimensions, and computer-vision results
+ * (faces, hands, pose, segmentation). Activate individual CV features through `cv.*`.
+ *
+ * When `isConnected` is `false`, `currentFrame` is `null`, all dimensions are `0`,
+ * and CV result fields hold their empty defaults.
+ */
 export declare interface VideoAPI {
+    /** `true` when a video stream is connected. When `false`, all other fields hold their default empty values. */
     isConnected: boolean;
+    /** Latest video frame, drawable directly with `ctx.drawImage()`. `null` when disconnected. */
     currentFrame: OffscreenCanvas | ImageBitmap | null;
+    /** Source video frame width in pixels. `0` when disconnected. */
     frameWidth: number;
+    /** Source video frame height in pixels. `0` when disconnected. */
     frameHeight: number;
+    /** Source video frame rate in Hz (frames per second). `0` when disconnected. */
     frameRate: number;
+    /**
+     * Returns the latest frame as raw RGBA `ImageData` for per-pixel CPU analysis,
+     * or `null` when disconnected. Slow compared to drawing `currentFrame` directly —
+     * use only when you need to read individual pixel values.
+     */
     getFrameData: () => ImageData | null;
+    /** Detected faces (empty array when face detection is off or no faces are visible). */
     faces: FaceData[];
+    /** Detected hands (up to 2; empty array when hand tracking is off or no hands are visible). */
     hands: HandData[];
+    /** Detected body pose, or `null` when pose detection is off or no pose is visible. */
     pose: PoseData | null;
+    /** Body segmentation mask, or `null` when segmentation is off. */
     segmentation: SegmentationData | null;
+    /**
+     * Computer-vision feature control. Each `enable*` method toggles a specific CV
+     * pipeline; results land in the corresponding `faces` / `hands` / `pose` /
+     * `segmentation` field on the next available frame. Multiple features can be
+     * active simultaneously, but each adds CPU/GPU and WebGL-context cost.
+     */
     cv: {
+        /**
+         * Toggle face detection (bounding box, center, confidence, id).
+         * @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.
+         * @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.
+         * @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.
+         * @returns Resolves once the pipeline has finished switching.
+         */
         enableHandTracking(enabled: boolean): Promise<void>;
+        /**
+         * Toggle 33-point BlazePose body landmarks (face / torso / arms / legs).
+         * @returns Resolves once the pipeline has finished switching.
+         */
         enablePoseDetection(enabled: boolean): Promise<void>;
+        /**
+         * Toggle per-pixel person/background segmentation mask.
+         * @returns Resolves once the pipeline has finished switching.
+         */
         enableBodySegmentation(enabled: boolean): Promise<void>;
+        /** Returns the list of CV features currently enabled on this stream. */
         getActiveFeatures(): CVFeature[];
+        /** Returns `true` if the CV worker is actively processing frames. */
         isProcessing(): boolean;
     };
 }
@@ -1266,37 +1953,157 @@ export declare interface VideoAPI {
  */
 export declare type VideoStreamType = 'main' | 'additional' | 'directFrame' | 'device';
 
+/**
+ * The Viji API surface available to artist code as the global `viji` object.
+ * Groups canvas access, timing, connected media APIs, user interaction, device
+ * sensors, parameter helpers, and the `useContext()` selector.
+ */
 export declare interface VijiAPI {
+    /** The `OffscreenCanvas` driving the scene. The host owns its lifecycle and dimensions; prefer `useContext()` over touching this directly. */
     canvas: OffscreenCanvas;
+    /** 2D rendering context. `undefined` until `viji.useContext('2d')` is called; afterwards equals the cached context. */
     ctx?: OffscreenCanvasRenderingContext2D;
+    /** WebGL rendering context. `undefined` until `viji.useContext('webgl')` or `'webgl2'` is called; afterwards equals the cached context. */
     gl?: WebGLRenderingContext | WebGL2RenderingContext;
+    /** Current canvas width in pixels. Updates automatically when the host resizes the canvas — read every frame. */
     width: number;
+    /** Current canvas height in pixels. Updates automatically when the host resizes the canvas — read every frame. */
     height: number;
+    /** Seconds elapsed since the scene started (monotonically increasing float). Use for oscillations and absolute-time effects. */
     time: number;
+    /** Seconds since the previous frame. Use for accumulation: movement, physics, fades — anything that should progress per second regardless of FPS. */
     deltaTime: number;
+    /** Integer frame counter starting at `0` and incrementing by `1` each frame. */
     frameCount: number;
+    /** Target frames-per-second for the host's current frame-rate mode (`60` for `'full'`, `30` for `'half'`). */
     fps: number;
+    /** Real-time analysis of the main audio stream: volume, frequency bands, beat detection, spectral features. Fields are zeroed when no audio source is connected. */
     audio: AudioAPI;
+    /** Main video stream API: pixel access, frame metadata, and computer-vision results (face, hands, pose, segmentation). */
     video: VideoAPI;
+    /** Additional video streams provided by the host. These do not run CV processing — use them for raw pixel access only. */
     videoStreams: VideoAPI[];
+    /** Additional audio streams (lightweight analysis: volume, bands, spectral). No beat detection — use the main `audio` for that. */
     audioStreams: AudioStreamAPI[];
+    /** Mouse position, buttons, wheel, and per-frame movement state. Coordinates are in canvas pixels. */
     mouse: MouseAPI;
+    /** Keyboard state: per-frame press/release queries, currently held keys, and modifier flags. */
     keyboard: KeyboardAPI;
+    /** Multi-touch state: count, primary touch shortcut, and the per-frame `started` / `moved` / `ended` arrays. */
     touches: TouchAPI;
+    /** Unified pointer (mouse + primary touch) — convenient single-point input that works on both desktop and mobile. */
     pointer: PointerAPI;
+    /** Internal device sensors (motion + orientation) reported by the device running the scene. */
     device: DeviceSensorState;
+    /** External connected devices reporting sensor / camera / audio. Each entry has its own `id`, `name`, and per-device API surface. */
     devices: DeviceState[];
+    /**
+     * Declares a numeric slider parameter. The host UI renders a draggable slider.
+     * Must be called at the top level of the scene — never inside `render()`.
+     *
+     * @example
+     * const radius = viji.slider(50, { min: 10, max: 200, step: 1, label: 'Radius' });
+     * // ...
+     * function render(viji) { drawCircle(radius.value); }
+     */
     slider: (defaultValue: number, config: SliderConfig) => SliderParameter;
-    color: (defaultValue: string, config: ColorConfig) => ColorParameter;
+    /**
+     * Declares a color parameter. Accepts hex strings, CSS color functions, or RGB / HSB objects;
+     * the value is always normalized to a canonical lowercase hex string and exposes derived `.rgb` / `.hsb` accessors.
+     * Must be called at the top level of the scene — never inside `render()`.
+     *
+     * @example
+     * const tint = viji.color('#ff6600', { label: 'Tint' });
+     * // tint.value -> '#ff6600', tint.rgb -> { r: 255, g: 102, b: 0 }, tint.hsb -> { h: 24, s: 100, b: 100 }
+     */
+    color: (defaultValue: ColorInput, config: ColorConfig) => ColorParameter;
+    /**
+     * Declares a boolean toggle parameter. The host UI renders an on/off switch.
+     * Must be called at the top level of the scene — never inside `render()`.
+     *
+     * @example
+     * const showTrail = viji.toggle(true, { label: 'Show Trail' });
+     */
     toggle: (defaultValue: boolean, config: ToggleConfig) => ToggleParameter;
+    /**
+     * Declares a dropdown selection parameter. The element type of `options`
+     * (`string` or `number`) determines the parameter's value type.
+     * Must be called at the top level of the scene — never inside `render()`.
+     *
+     * @example
+     * const shape = viji.select('circle', { options: ['circle', 'square', 'triangle'], label: 'Shape' });
+     */
     select: (defaultValue: string | number, config: SelectConfig) => SelectParameter;
+    /**
+     * Declares a text input parameter. The host UI renders a single-line text field.
+     * Must be called at the top level of the scene — never inside `render()`.
+     *
+     * @example
+     * const caption = viji.text('Hello', { label: 'Caption', maxLength: 64 });
+     */
     text: (defaultValue: string, config: TextConfig) => TextParameter;
+    /**
+     * Declares a precise numeric input parameter. Like `slider()` but the host UI
+     * shows a number field instead of a draggable handle.
+     * Must be called at the top level of the scene — never inside `render()`.
+     *
+     * @example
+     * const count = viji.number(12, { min: 1, max: 64, step: 1, label: 'Count' });
+     */
     number: (defaultValue: number, config: NumberConfig) => NumberParameter;
+    /**
+     * Declares an image upload parameter. The user-supplied image becomes available
+     * as `value` (an `ImageBitmap`); in P5 scenes a `.p5` accessor is also added at runtime.
+     * Must be called at the top level of the scene — never inside `render()`.
+     *
+     * @example
+     * const tex = viji.image(null, { label: 'Texture' });
+     * if (tex.value) ctx.drawImage(tex.value, 0, 0, viji.width, viji.height);
+     */
     image: (defaultValue: null, config: ImageConfig) => ImageParameter;
+    /**
+     * Declares a momentary button parameter. `value` is `true` for one frame after
+     * the user clicks, then auto-resets — perfect for triggering discrete events.
+     * Must be called at the top level of the scene — never inside `render()`.
+     *
+     * @example
+     * const reset = viji.button({ label: 'Reset' });
+     * function render(viji) { if (reset.value) state = initialState; }
+     */
     button: (config: ButtonConfig) => ButtonParameter;
+    /**
+     * Declares a 2D coordinate parameter. Both `value.x` and `value.y` are in `-1..1`.
+     * Must be called at the top level of the scene — never inside `render()`.
+     *
+     * @example
+     * const origin = viji.coordinate({ x: 0, y: 0 }, { label: 'Origin' });
+     * const cx = viji.width / 2 + origin.value.x * viji.width * 0.4;
+     */
     coordinate: (defaultValue: CoordinateValue, config: CoordinateConfig) => CoordinateParameter;
+    /**
+     * Selects the 2D canvas rendering context. Returns the same instance on
+     * subsequent calls and also stores it on `viji.ctx`. A canvas only supports
+     * one context type — if a different context type was already requested,
+     * the call returns `null`. Choose ONE type and use it for the entire scene.
+     *
+     * @example
+     * const ctx = viji.useContext('2d');
+     * ctx.fillRect(0, 0, viji.width, viji.height);
+     */
     useContext(type: '2d'): OffscreenCanvasRenderingContext2D | null;
+    /**
+     * Selects a WebGL 1 rendering context. Returns the same instance on subsequent
+     * calls and also stores it on `viji.gl`. A canvas only supports one context
+     * type — if a different context type was already requested, the call returns
+     * `null`. Choose ONE type and use it for the entire scene.
+     */
     useContext(type: 'webgl'): WebGLRenderingContext | null;
+    /**
+     * Selects a WebGL 2 rendering context. Returns the same instance on subsequent
+     * calls and also stores it on `viji.gl`. A canvas only supports one context
+     * type — if a different context type was already requested, the call returns
+     * `null`. Choose ONE type and use it for the entire scene.
+     */
     useContext(type: 'webgl2'): WebGL2RenderingContext | null;
 }
 
@@ -1454,11 +2261,20 @@ export declare class VijiCore {
      * Get parameter definition by name
      */
     private getParameterDefinition;
+    /**
+     * For color parameters, accept rich input forms (hex, RGB/HSB objects, CSS / GLSL strings)
+     * and normalize them to canonical lowercase hex `#rrggbb` before they go on the wire.
+     * This keeps the host<->worker contract simple (always a hex string) while letting
+     * external callers use whichever form is most convenient.
+     *
+     * Non-color values are returned unchanged.
+     */
+    private normalizeColorInputIfNeeded;
     /**
      * Set a single parameter value
      * Handles all parameter types including images intelligently
      */
-    setParameter(name: string, value: ParameterValue | File | Blob): Promise<void>;
+    setParameter(name: string, value: ParameterValue | ColorInput | File | Blob): Promise<void>;
     /**
      * Internal method to handle image parameter loading and transfer
      * Loads the image on the host side and creates TWO ImageBitmaps:
@@ -1467,9 +2283,12 @@ export declare class VijiCore {
      */
     private handleImageParameter;
     /**
-     * Set multiple parameter values efficiently
+     * Set multiple parameter values efficiently.
+     *
+     * For color parameters, accepts the same rich input forms as `setParameter`
+     * (hex, RGB/HSB objects, CSS / GLSL strings); they are normalized to canonical hex.
      */
-    setParameters(values: Record<string, ParameterValue>): Promise<void>;
+    setParameters(values: Record<string, ParameterValue | ColorInput>): Promise<void>;
     /**
      * Get current parameter value
      */