@viji-dev/core 0.4.1 → 0.4.3

package/dist/artist-global.d.ts

@@ -25,15 +25,15 @@ declare global {
       };
       /** 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. */
+          /** Instant low-band energy (20-120 Hz, bass/kick range). 0..1. */
           low: number;
-          /** Instant low-mid energy (120–400 Hz). 0..1. */
+          /** Instant low-mid energy (120-400 Hz). 0..1. */
           lowMid: number;
-          /** Instant mid energy (400–1600 Hz, vocals/instruments). 0..1. */
+          /** Instant mid energy (400-1600 Hz, vocals/instruments). 0..1. */
           mid: number;
-          /** Instant high-mid energy (1600–6000 Hz, cymbals/hi-hats). 0..1. */
+          /** 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. */
+          /** Instant high-band energy (6000-16000 Hz, air/brilliance). 0..1. */
           high: number;
           /** Smoothed `low` (~150ms decay). 0..1. */
           lowSmoothed: number;
@@ -93,15 +93,15 @@ declare global {
       };
       /** High-level spectral features derived from the FFT. */
       spectral: {
-          /** Normalized spectral centroid in 0..1 — higher values mean brighter, more treble-heavy sound. */
+          /** 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. */
+          /** 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.
+       * snapshot from the latest analysis tick; repeated calls in the same frame return the same data.
        *
        * @example
        * const fft = viji.audio.getFrequencyData();
@@ -110,7 +110,7 @@ declare global {
       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.
+       * The returned array is a snapshot; repeated calls in the same frame return the same data.
        *
        * @example
        * const wave = viji.audio.getWaveform();
@@ -121,7 +121,7 @@ declare global {
 
   /**
    * Lightweight audio analysis for additional or device audio streams. A strict
-   * subset of `AudioAPI` — exposes volume, frequency bands, spectral features,
+   * subset of `AudioAPI` that exposes volume, frequency bands, spectral features,
    * and raw FFT/waveform access, but **no beat detection** (no `beat`, no BPM,
    * no triggers, no events).
    */
@@ -139,15 +139,15 @@ declare global {
       };
       /** 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. */
+          /** Instant low-band energy (20-120 Hz). 0..1. */
           low: number;
-          /** Instant low-mid energy (120–400 Hz). 0..1. */
+          /** Instant low-mid energy (120-400 Hz). 0..1. */
           lowMid: number;
-          /** Instant mid energy (400–1600 Hz). 0..1. */
+          /** Instant mid energy (400-1600 Hz). 0..1. */
           mid: number;
-          /** Instant high-mid energy (1600–6000 Hz). 0..1. */
+          /** Instant high-mid energy (1600-6000 Hz). 0..1. */
           highMid: number;
-          /** Instant high-band energy (6000–16000 Hz). 0..1. */
+          /** Instant high-band energy (6000-16000 Hz). 0..1. */
           high: number;
           /** Smoothed `low` (~150ms decay). 0..1. */
           lowSmoothed: number;
@@ -169,19 +169,19 @@ declare global {
       };
       /**
        * Returns the raw FFT magnitude spectrum for this stream as a `Uint8Array`
-       * (1024 bins, each 0..255). Snapshot semantics — see `AudioAPI.getFrequencyData`.
+       * (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`.
+       * (2048 samples, each -1..1). Snapshot semantics; see `AudioAPI.getWaveform`.
        */
       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,
+   * momentary button. The resulting `value` is `true` for one frame after press,
    * then auto-resets to `false`.
    */
   interface ButtonConfig {
@@ -191,12 +191,12 @@ declare global {
       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'`. */
+      /** 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 —
+   * 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()`.
    */
@@ -209,7 +209,7 @@ declare global {
       description?: string;
       /** Group name under which the control appears in the UI. */
       group: string;
-      /** Visibility category — controls when the parameter is shown. */
+      /** Visibility category that controls when the parameter is shown. */
       category: ParameterCategory;
   }
 
@@ -242,7 +242,7 @@ declare global {
       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'`. */
+      /** Visibility category. The control hides when its capability is unavailable. Default: `'general'`. */
       category?: ParameterCategory;
   }
 
@@ -303,7 +303,7 @@ declare global {
       description?: string;
       /** Group name under which the control appears in the UI. */
       group: string;
-      /** Visibility category — controls when the parameter is shown. */
+      /** Visibility category that controls when the parameter is shown. */
       category: ParameterCategory;
   }
 
@@ -320,7 +320,7 @@ declare global {
       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'`. */
+      /** Visibility category. The control hides when its capability is unavailable. Default: `'general'`. */
       category?: ParameterCategory;
   }
 
@@ -339,7 +339,7 @@ declare global {
       description?: string;
       /** Group name under which the control appears in the UI. */
       group: string;
-      /** Visibility category — controls when the parameter is shown. */
+      /** Visibility category that controls when the parameter is shown. */
       category: ParameterCategory;
   }
 
@@ -363,7 +363,7 @@ declare global {
   /**
    * 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.
+   * fourth, `'eighth'` every eighth. Lower rates reduce CPU/GPU cost.
    */
   type CVFrameRateMode = 'full' | 'half' | 'quarter' | 'eighth';
 
@@ -678,7 +678,7 @@ declare global {
           /** Depth (relative). */
           z: number;
       }[];
-      /** Palm center — equivalent to `landmarks[9]` (middle-finger MCP). */
+      /** Palm center, equivalent to `landmarks[9]` (middle-finger MCP). */
       palm: {
           /** Palm horizontal coordinate, normalized 0..1. */
           x: number;
@@ -721,7 +721,7 @@ declare global {
       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'`. */
+      /** Visibility category. The control hides when its capability is unavailable. Default: `'general'`. */
       category?: ParameterCategory;
   }
 
@@ -733,7 +733,7 @@ declare global {
   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. */
+      /** 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;
@@ -741,7 +741,7 @@ declare global {
       description?: string;
       /** Group name under which the control appears in the UI. */
       group: string;
-      /** Visibility category — controls when the parameter is shown. */
+      /** Visibility category that controls when the parameter is shown. */
       category: ParameterCategory;
   }
 
@@ -843,7 +843,7 @@ declare global {
       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'`. */
+      /** Visibility category. The control hides when its capability is unavailable. Default: `'general'`. */
       category?: ParameterCategory;
   }
 
@@ -866,7 +866,7 @@ declare global {
       description?: string;
       /** Group name under which the control appears in the UI. */
       group: string;
-      /** Visibility category — controls when the parameter is shown. */
+      /** Visibility category that controls when the parameter is shown. */
       category: ParameterCategory;
   }
 
@@ -894,7 +894,7 @@ declare global {
       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. */
+      /** `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;
@@ -902,7 +902,7 @@ declare global {
       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). */
+      /** 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';
   }
 
@@ -1005,7 +1005,7 @@ declare global {
       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'`. */
+      /** Visibility category. The control hides when its capability is unavailable. Default: `'general'`. */
       category?: ParameterCategory;
   }
 
@@ -1024,7 +1024,7 @@ declare global {
       description?: string;
       /** Group name under which the control appears in the UI. */
       group: string;
-      /** Visibility category — controls when the parameter is shown. */
+      /** Visibility category that controls when the parameter is shown. */
       category: ParameterCategory;
   }
 
@@ -1045,7 +1045,7 @@ declare global {
       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'`. */
+      /** Visibility category. The control hides when its capability is unavailable. Default: `'general'`. */
       category?: ParameterCategory;
   }
 
@@ -1068,7 +1068,7 @@ declare global {
       description?: string;
       /** Group name under which the control appears in the UI. */
       group: string;
-      /** Visibility category — controls when the parameter is shown. */
+      /** Visibility category that controls when the parameter is shown. */
       category: ParameterCategory;
   }
 
@@ -1083,7 +1083,7 @@ declare global {
       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'`. */
+      /** 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;
@@ -1104,7 +1104,7 @@ declare global {
       description?: string;
       /** Group name under which the control appears in the UI. */
       group: string;
-      /** Visibility category — controls when the parameter is shown. */
+      /** Visibility category that controls when the parameter is shown. */
       category: ParameterCategory;
   }
 
@@ -1119,7 +1119,7 @@ declare global {
       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'`. */
+      /** Visibility category. The control hides when its capability is unavailable. Default: `'general'`. */
       category?: ParameterCategory;
   }
 
@@ -1136,7 +1136,7 @@ declare global {
       description?: string;
       /** Group name under which the control appears in the UI. */
       group: string;
-      /** Visibility category — controls when the parameter is shown. */
+      /** Visibility category that controls when the parameter is shown. */
       category: ParameterCategory;
   }
 
@@ -1145,7 +1145,7 @@ declare global {
    * `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.
+   * `viji.pointer`. It switches automatically between mouse and primary touch.
    */
   interface TouchAPI {
       /** All currently active touch points. Order is stable but not ordered by id. */
@@ -1168,7 +1168,7 @@ declare global {
    * in canvas-space pixels.
    *
    * Some fields (notably `pressure` / `force`, `radiusX` / `radiusY`,
-   * `rotationAngle`) are passed through from the device — values vary by
+   * `rotationAngle`) are passed through from the device; values vary by
    * platform; many devices report `0` when unsupported.
    */
   interface TouchPoint {
@@ -1180,7 +1180,7 @@ declare global {
       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. */
+      /** Contact radius, `Math.max(radiusX, radiusY)` in pixels. */
       radius: number;
       /** Horizontal contact radius in pixels (raw device value). */
       radiusX: number;
@@ -1188,7 +1188,7 @@ declare global {
       radiusY: number;
       /** Contact area rotation in radians (raw device value). */
       rotationAngle: number;
-      /** Touch force in 0..1 — alias of `pressure`. */
+      /** Touch force in 0..1; alias of `pressure`. */
       force: number;
       /** `true` while the touch position is within the canvas bounds. */
       isInCanvas: boolean;
@@ -1211,7 +1211,7 @@ declare global {
       isEnding: boolean;
   }
 
-  const VERSION = "0.4.0";
+  const VERSION = "0.4.2";
 
   /**
    * Real-time video API: drawable frame, dimensions, and computer-vision results
@@ -1233,7 +1233,7 @@ declare global {
       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 —
+       * or `null` when disconnected. Slow compared to drawing `currentFrame` directly;
        * use only when you need to read individual pixel values.
        */
       getFrameData: () => ImageData | null;
@@ -1304,13 +1304,13 @@ declare global {
       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. */
+      /** 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. */
+      /** 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. */
+      /** 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;
@@ -1320,9 +1320,9 @@ declare global {
       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. */
+      /** 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. */
+      /** 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;
@@ -1330,7 +1330,7 @@ declare global {
       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. */
+      /** 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;
@@ -1338,7 +1338,7 @@ declare global {
       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()`.
+       * 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' });
@@ -1349,7 +1349,7 @@ declare global {
       /**
        * 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()`.
+       * Must be called at the top level of the scene, never inside `render()`.
        *
        * @example
        * const tint = viji.color('#ff6600', { label: 'Tint' });
@@ -1358,7 +1358,7 @@ declare global {
       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()`.
+       * Must be called at the top level of the scene, never inside `render()`.
        *
        * @example
        * const showTrail = viji.toggle(true, { label: 'Show Trail' });
@@ -1367,7 +1367,7 @@ declare global {
       /**
        * 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()`.
+       * 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' });
@@ -1375,7 +1375,7 @@ declare global {
       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()`.
+       * Must be called at the top level of the scene, never inside `render()`.
        *
        * @example
        * const caption = viji.text('Hello', { label: 'Caption', maxLength: 64 });
@@ -1384,7 +1384,7 @@ declare global {
       /**
        * 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()`.
+       * 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' });
@@ -1393,7 +1393,7 @@ declare global {
       /**
        * 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()`.
+       * Must be called at the top level of the scene, never inside `render()`.
        *
        * @example
        * const tex = viji.image(null, { label: 'Texture' });
@@ -1402,8 +1402,8 @@ declare global {
       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()`.
+       * 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' });
@@ -1412,7 +1412,7 @@ declare global {
       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()`.
+       * Must be called at the top level of the scene, never inside `render()`.
        *
        * @example
        * const origin = viji.coordinate({ x: 0, y: 0 }, { label: 'Origin' });
@@ -1422,7 +1422,7 @@ declare global {
       /**
        * 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,
+       * 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
@@ -1433,14 +1433,14 @@ declare global {
       /**
        * 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
+       * 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;
       /**
        * 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
+       * 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;