@viji-dev/core 0.16.1 → 0.18.0

package/dist/artist-global-p5.d.ts

@@ -284,16 +284,28 @@ declare global {
       group?: string;
       /** Visibility category. The control hides when its capability is unavailable. Default: `'general'`. */
       category?: ParameterCategory;
+      /**
+       * Enable a transparency channel. When `true` the canonical value is always an
+       * 8-digit `#rrggbbaa` (opaque inputs are padded `ff`), the picker shows an alpha
+       * slider, and the shader uniform is a `vec4`. When `false` (default) the value is
+       * `#rrggbb` and any alpha-bearing input is rejected. Default: `false`.
+       */
+      alpha?: boolean;
   }
 
   /**
    * Accepted input forms for color parameters. Internally normalized to canonical
-   * lowercase 6-digit hex `#rrggbb`. See `viji.color()` for full documentation.
+   * lowercase hex: `#rrggbb` for an opaque parameter, `#rrggbbaa` for a parameter
+   * declared with `alpha: true`. 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
+   *
+   * Alpha-bearing forms (`#rrggbbaa`, `#rgba`, `rgba()`, `hsla()`, `vec4()`, and the
+   * objects with an `a` field in 0..1) are accepted ONLY by a parameter declared with
+   * `alpha: true`; an opaque parameter rejects them even when the alpha is `1`.
    */
   type ColorInput = string | {
       /** Red component in 0..255. */
@@ -302,6 +314,8 @@ declare global {
       g: number;
       /** Blue component in 0..255. */
       b: number;
+      /** Alpha in 0..1. Only valid on a parameter declared with `alpha: true`. */
+      a?: number;
   } | {
       /** Hue in 0..360. */
       h: number;
@@ -309,16 +323,22 @@ declare global {
       s: number;
       /** Brightness in 0..100. */
       b: number;
+      /** Alpha in 0..1. Only valid on a parameter declared with `alpha: true`. */
+      a?: 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.
+   * lowercase hex string whose width is fixed by the parameter's mode (`#rrggbb`,
+   * or `#rrggbbaa` when declared with `alpha: true`); `rgb`, `hsb` and `alpha` are
+   * derived accessors that are recomputed (and frozen) every time the user changes
+   * the color.
    */
   interface ColorParameter {
-      /** Canonical hex color string `#rrggbb` (lowercase). Updates in real-time. */
+      /** Canonical lowercase hex color string: `#rrggbb`, or `#rrggbbaa` when `alpha: true`. Updates in real-time. */
       value: string;
+      /** Alpha in 0..1. Always present: `1` on an opaque parameter, the live alpha when `alpha: true`. */
+      alpha: number;
       /** RGB components as integers in 0..255 (frozen, recomputed when value changes). */
       rgb: {
           /** Red component, integer in 0..255. */
@@ -708,6 +728,101 @@ declare global {
       max: number;
   }
 
+  /**
+   * Configuration object passed to `viji.gradient()`. Defines the ramp editor's
+   * stop bounds, transparency mode, label and UI grouping/visibility.
+   */
+  interface GradientConfig {
+      /**
+       * Advanced: explicit parameter identity. Normally you do NOT set this —
+       * the parameter's name is inferred from the variable or object key you
+       * assign it to (`const ramp = viji.gradient(...)` → `ramp`). Set `name`
+       * only for parameters not assigned to a variable or key (created in an
+       * array, loop, or factory). Must be a valid identifier and scene-globally
+       * unique. When set, it overrides the inferred name.
+       */
+      name?: string;
+      /** Minimum number of stops the editor allows. Integer in `2..32`. Default: `2`. */
+      minStops?: number;
+      /** Maximum number of stops the editor allows. Integer in `2..32`; sizes the shader uniform arrays. Default: `8`. */
+      maxStops?: number;
+      /** Display name shown next to the ramp in the parameter UI. Optional — defaults to the parameter's name. */
+      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;
+      /**
+       * Enable per-stop transparency. When `true` every stop color is `#rrggbbaa`
+       * (opaque inputs padded `ff`) and the shader sampler returns a `vec4`. When
+       * `false` (default) stops are `#rrggbb` and alpha-bearing stop colors are rejected.
+       */
+      alpha?: boolean;
+  }
+
+  /**
+   * Stop list accepted by `viji.gradient()` and `setParameter()`. Any order;
+   * normalized to a sorted, canonical {@link GradientValue}.
+   */
+  type GradientInput = ReadonlyArray<GradientStopInput>;
+
+  /**
+   * Reactive object returned by `viji.gradient()`. `value` is the live, frozen,
+   * sorted stop list; `at(t)` samples the ramp with CSS `linear-gradient`
+   * semantics (premultiplied sRGB between stops, hard edges on duplicate
+   * positions) and returns a canonical hex string in the same width as the stops.
+   */
+  interface GradientParameter {
+      /** Current stops, frozen and sorted ascending by position. Updates in real-time. */
+      value: GradientValue;
+      /**
+       * Sample the ramp at `t` (clamped to `0..1`). Returns canonical hex in the
+       * gradient's width. The shader renderer exposes the same function as
+       * `<name>(float t)` in GLSL.
+       */
+      at(t: number): string;
+      /** Display name shown next to the ramp 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 that controls when the parameter is shown. */
+      category: ParameterCategory;
+  }
+
+  /**
+   * One stop of a gradient value. `color` is canonical lowercase hex in the
+   * gradient's mode (`#rrggbb`, or `#rrggbbaa` when declared with `alpha: true`).
+   */
+  interface GradientStop {
+      /** Canonical hex color of this stop. */
+      color: string;
+      /** Position along the ramp in `0..1`. */
+      position: number;
+  }
+
+  /**
+   * One artist- or host-supplied gradient stop. `color` accepts every form a
+   * color parameter accepts, normalized per the gradient's `alpha` mode.
+   */
+  interface GradientStopInput {
+      /** Any accepted color form (hex, CSS functions, RGB / HSB objects). */
+      color: ColorInput;
+      /** Position along the ramp in `0..1`. */
+      position: number;
+  }
+
+  /**
+   * Value of a gradient parameter: a frozen list of stops sorted ascending by
+   * position. Duplicate positions are allowed and form a hard edge. The length is
+   * within the parameter's `minStops..maxStops`. No wrapper: geometry (linear,
+   * radial, angle) is the scene's concern.
+   */
+  type GradientValue = readonly GradientStop[];
+
   /**
    * One detected hand produced by the video CV pipeline. Carries 21 landmarks,
    * a palm shortcut, and ML-classified gesture confidence scores. Up to two
@@ -802,7 +917,12 @@ declare global {
    * the image works directly with `image()`, `texture()`, etc.
    */
   interface ImageParameter {
-      /** Uploaded image as an `ImageBitmap`, or `null` until the user provides one. */
+      /**
+       * Uploaded image as an `ImageBitmap`, or `null` until the user provides one.
+       * Read it where you use it (inside `render()`): when the host replaces or
+       * clears the image, the previous bitmap is closed, so a reference kept from
+       * an earlier frame becomes unusable.
+       */
       value: ImageBitmap | null;
       /** P5-compatible image wrapper. Only available in the P5 renderer; added at runtime by the P5 adapter. */
       readonly p5?: any;
@@ -1350,7 +1470,7 @@ declare global {
       isEnding: boolean;
   }
 
-  const VERSION = "0.16.1";
+  const VERSION = "0.18.0";
 
   /**
    * Real-time video API: drawable frame, dimensions, and the source-side
@@ -1594,12 +1714,17 @@ declare global {
       slider: (defaultValue: number, config: SliderConfig) => SliderParameter;
       /**
        * 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.
+       * the value is always normalized to a canonical lowercase hex string and exposes derived
+       * `.rgb` / `.hsb` / `.alpha` accessors. Pass `alpha: true` to enable transparency: the value
+       * becomes `#rrggbbaa` and alpha-bearing inputs (`rgba()`, `#rrggbbaa`, ...) are accepted.
+       * Without it, alpha-bearing inputs are rejected.
        * 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 }
+       * // tint.value -> '#ff6600', tint.rgb -> { r: 255, g: 102, b: 0 }, tint.hsb -> { h: 24, s: 100, b: 100 }, tint.alpha -> 1
+       * const glow = viji.color('#ffffff80', { label: 'Glow', alpha: true });
+       * // glow.value -> '#ffffff80', glow.alpha -> 0.5
        */
       color: (defaultValue: ColorInput, config: ColorConfig) => ColorParameter;
       /**
@@ -1665,6 +1790,27 @@ declare global {
        * const cx = viji.width / 2 + origin.value.x * viji.width * 0.4;
        */
       coordinate: (defaultValue: CoordinateValue, config: CoordinateConfig) => CoordinateParameter;
+      /**
+       * Declares a gradient parameter. The host renders a ramp editor; `value` is the live,
+       * sorted stop list and `at(t)` samples the ramp (CSS `linear-gradient` semantics).
+       * Stop colors accept every color form; pass `alpha: true` for per-stop transparency.
+       * `default` is required (no evenly-spaced shorthand). Must be called at the top level
+       * of the scene, never inside `render()`.
+       *
+       * @example
+       * const ramp = viji.gradient(
+       *   [{ color: '#ff6b6b', position: 0 }, { color: '#4ecdc4', position: 1 }],
+       *   { label: 'Ramp' }
+       * );
+       * function render(viji) {
+       *   const fill = viji.ctx.createLinearGradient(0, 0, viji.width, 0);
+       *   for (const stop of ramp.value) fill.addColorStop(stop.position, stop.color);
+       *   viji.ctx.fillStyle = fill;
+       *   viji.ctx.fillRect(0, 0, viji.width, viji.height);
+       *   viji.ctx.fillStyle = ramp.at(0.5); // per-element color, same math as the fill
+       * }
+       */
+      gradient: (defaultValue: GradientInput, config: GradientConfig) => GradientParameter;
       /**
        * Selects the 2D canvas rendering context. Returns the same instance on
        * subsequent calls and also stores it on `viji.ctx`. A canvas only supports

package/dist/artist-global.d.ts

@@ -284,16 +284,28 @@ declare global {
       group?: string;
       /** Visibility category. The control hides when its capability is unavailable. Default: `'general'`. */
       category?: ParameterCategory;
+      /**
+       * Enable a transparency channel. When `true` the canonical value is always an
+       * 8-digit `#rrggbbaa` (opaque inputs are padded `ff`), the picker shows an alpha
+       * slider, and the shader uniform is a `vec4`. When `false` (default) the value is
+       * `#rrggbb` and any alpha-bearing input is rejected. Default: `false`.
+       */
+      alpha?: boolean;
   }
 
   /**
    * Accepted input forms for color parameters. Internally normalized to canonical
-   * lowercase 6-digit hex `#rrggbb`. See `viji.color()` for full documentation.
+   * lowercase hex: `#rrggbb` for an opaque parameter, `#rrggbbaa` for a parameter
+   * declared with `alpha: true`. 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
+   *
+   * Alpha-bearing forms (`#rrggbbaa`, `#rgba`, `rgba()`, `hsla()`, `vec4()`, and the
+   * objects with an `a` field in 0..1) are accepted ONLY by a parameter declared with
+   * `alpha: true`; an opaque parameter rejects them even when the alpha is `1`.
    */
   type ColorInput = string | {
       /** Red component in 0..255. */
@@ -302,6 +314,8 @@ declare global {
       g: number;
       /** Blue component in 0..255. */
       b: number;
+      /** Alpha in 0..1. Only valid on a parameter declared with `alpha: true`. */
+      a?: number;
   } | {
       /** Hue in 0..360. */
       h: number;
@@ -309,16 +323,22 @@ declare global {
       s: number;
       /** Brightness in 0..100. */
       b: number;
+      /** Alpha in 0..1. Only valid on a parameter declared with `alpha: true`. */
+      a?: 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.
+   * lowercase hex string whose width is fixed by the parameter's mode (`#rrggbb`,
+   * or `#rrggbbaa` when declared with `alpha: true`); `rgb`, `hsb` and `alpha` are
+   * derived accessors that are recomputed (and frozen) every time the user changes
+   * the color.
    */
   interface ColorParameter {
-      /** Canonical hex color string `#rrggbb` (lowercase). Updates in real-time. */
+      /** Canonical lowercase hex color string: `#rrggbb`, or `#rrggbbaa` when `alpha: true`. Updates in real-time. */
       value: string;
+      /** Alpha in 0..1. Always present: `1` on an opaque parameter, the live alpha when `alpha: true`. */
+      alpha: number;
       /** RGB components as integers in 0..255 (frozen, recomputed when value changes). */
       rgb: {
           /** Red component, integer in 0..255. */
@@ -708,6 +728,101 @@ declare global {
       max: number;
   }
 
+  /**
+   * Configuration object passed to `viji.gradient()`. Defines the ramp editor's
+   * stop bounds, transparency mode, label and UI grouping/visibility.
+   */
+  interface GradientConfig {
+      /**
+       * Advanced: explicit parameter identity. Normally you do NOT set this —
+       * the parameter's name is inferred from the variable or object key you
+       * assign it to (`const ramp = viji.gradient(...)` → `ramp`). Set `name`
+       * only for parameters not assigned to a variable or key (created in an
+       * array, loop, or factory). Must be a valid identifier and scene-globally
+       * unique. When set, it overrides the inferred name.
+       */
+      name?: string;
+      /** Minimum number of stops the editor allows. Integer in `2..32`. Default: `2`. */
+      minStops?: number;
+      /** Maximum number of stops the editor allows. Integer in `2..32`; sizes the shader uniform arrays. Default: `8`. */
+      maxStops?: number;
+      /** Display name shown next to the ramp in the parameter UI. Optional — defaults to the parameter's name. */
+      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;
+      /**
+       * Enable per-stop transparency. When `true` every stop color is `#rrggbbaa`
+       * (opaque inputs padded `ff`) and the shader sampler returns a `vec4`. When
+       * `false` (default) stops are `#rrggbb` and alpha-bearing stop colors are rejected.
+       */
+      alpha?: boolean;
+  }
+
+  /**
+   * Stop list accepted by `viji.gradient()` and `setParameter()`. Any order;
+   * normalized to a sorted, canonical {@link GradientValue}.
+   */
+  type GradientInput = ReadonlyArray<GradientStopInput>;
+
+  /**
+   * Reactive object returned by `viji.gradient()`. `value` is the live, frozen,
+   * sorted stop list; `at(t)` samples the ramp with CSS `linear-gradient`
+   * semantics (premultiplied sRGB between stops, hard edges on duplicate
+   * positions) and returns a canonical hex string in the same width as the stops.
+   */
+  interface GradientParameter {
+      /** Current stops, frozen and sorted ascending by position. Updates in real-time. */
+      value: GradientValue;
+      /**
+       * Sample the ramp at `t` (clamped to `0..1`). Returns canonical hex in the
+       * gradient's width. The shader renderer exposes the same function as
+       * `<name>(float t)` in GLSL.
+       */
+      at(t: number): string;
+      /** Display name shown next to the ramp 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 that controls when the parameter is shown. */
+      category: ParameterCategory;
+  }
+
+  /**
+   * One stop of a gradient value. `color` is canonical lowercase hex in the
+   * gradient's mode (`#rrggbb`, or `#rrggbbaa` when declared with `alpha: true`).
+   */
+  interface GradientStop {
+      /** Canonical hex color of this stop. */
+      color: string;
+      /** Position along the ramp in `0..1`. */
+      position: number;
+  }
+
+  /**
+   * One artist- or host-supplied gradient stop. `color` accepts every form a
+   * color parameter accepts, normalized per the gradient's `alpha` mode.
+   */
+  interface GradientStopInput {
+      /** Any accepted color form (hex, CSS functions, RGB / HSB objects). */
+      color: ColorInput;
+      /** Position along the ramp in `0..1`. */
+      position: number;
+  }
+
+  /**
+   * Value of a gradient parameter: a frozen list of stops sorted ascending by
+   * position. Duplicate positions are allowed and form a hard edge. The length is
+   * within the parameter's `minStops..maxStops`. No wrapper: geometry (linear,
+   * radial, angle) is the scene's concern.
+   */
+  type GradientValue = readonly GradientStop[];
+
   /**
    * One detected hand produced by the video CV pipeline. Carries 21 landmarks,
    * a palm shortcut, and ML-classified gesture confidence scores. Up to two
@@ -802,7 +917,12 @@ declare global {
    * the image works directly with `image()`, `texture()`, etc.
    */
   interface ImageParameter {
-      /** Uploaded image as an `ImageBitmap`, or `null` until the user provides one. */
+      /**
+       * Uploaded image as an `ImageBitmap`, or `null` until the user provides one.
+       * Read it where you use it (inside `render()`): when the host replaces or
+       * clears the image, the previous bitmap is closed, so a reference kept from
+       * an earlier frame becomes unusable.
+       */
       value: ImageBitmap | null;
       /** P5-compatible image wrapper. Only available in the P5 renderer; added at runtime by the P5 adapter. */
       readonly p5?: any;
@@ -1339,7 +1459,7 @@ declare global {
       isEnding: boolean;
   }
 
-  const VERSION = "0.16.1";
+  const VERSION = "0.18.0";
 
   /**
    * Real-time video API: drawable frame, dimensions, and the source-side
@@ -1583,12 +1703,17 @@ declare global {
       slider: (defaultValue: number, config: SliderConfig) => SliderParameter;
       /**
        * 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.
+       * the value is always normalized to a canonical lowercase hex string and exposes derived
+       * `.rgb` / `.hsb` / `.alpha` accessors. Pass `alpha: true` to enable transparency: the value
+       * becomes `#rrggbbaa` and alpha-bearing inputs (`rgba()`, `#rrggbbaa`, ...) are accepted.
+       * Without it, alpha-bearing inputs are rejected.
        * 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 }
+       * // tint.value -> '#ff6600', tint.rgb -> { r: 255, g: 102, b: 0 }, tint.hsb -> { h: 24, s: 100, b: 100 }, tint.alpha -> 1
+       * const glow = viji.color('#ffffff80', { label: 'Glow', alpha: true });
+       * // glow.value -> '#ffffff80', glow.alpha -> 0.5
        */
       color: (defaultValue: ColorInput, config: ColorConfig) => ColorParameter;
       /**
@@ -1654,6 +1779,27 @@ declare global {
        * const cx = viji.width / 2 + origin.value.x * viji.width * 0.4;
        */
       coordinate: (defaultValue: CoordinateValue, config: CoordinateConfig) => CoordinateParameter;
+      /**
+       * Declares a gradient parameter. The host renders a ramp editor; `value` is the live,
+       * sorted stop list and `at(t)` samples the ramp (CSS `linear-gradient` semantics).
+       * Stop colors accept every color form; pass `alpha: true` for per-stop transparency.
+       * `default` is required (no evenly-spaced shorthand). Must be called at the top level
+       * of the scene, never inside `render()`.
+       *
+       * @example
+       * const ramp = viji.gradient(
+       *   [{ color: '#ff6b6b', position: 0 }, { color: '#4ecdc4', position: 1 }],
+       *   { label: 'Ramp' }
+       * );
+       * function render(viji) {
+       *   const fill = viji.ctx.createLinearGradient(0, 0, viji.width, 0);
+       *   for (const stop of ramp.value) fill.addColorStop(stop.position, stop.color);
+       *   viji.ctx.fillStyle = fill;
+       *   viji.ctx.fillRect(0, 0, viji.width, viji.height);
+       *   viji.ctx.fillStyle = ramp.at(0.5); // per-element color, same math as the fill
+       * }
+       */
+      gradient: (defaultValue: GradientInput, config: GradientConfig) => GradientParameter;
       /**
        * Selects the 2D canvas rendering context. Returns the same instance on
        * subsequent calls and also stores it on `viji.ctx`. A canvas only supports

package/dist/artist-jsdoc.d.ts

@@ -24,6 +24,7 @@
  * @property {string} [description] - Optional tooltip / help text shown next to the control.
  * @property {string} [group] - Group name for organizing related parameters under a shared heading. Default: `'general'`.
  * @property {ParameterCategory} [category] - Visibility category. The control hides when its capability is unavailable. Default: `'general'`.
+ * @property {boolean} [alpha] - Enable a transparency channel. When `true` the canonical value is always an 8-digit `#rrggbbaa` (opaque inputs are padded `ff`), the picker shows an alpha slider, and the shader uniform is a `vec4`. When `false` (default) the value is `#rrggbb` and any alpha-bearing input is rejected. Default: `false`.
  */
 
 /**
@@ -102,6 +103,19 @@
  * @property {ParameterCategory} [category] - Visibility category. The control hides when its capability is unavailable. Default: `'general'`.
  */
 
+/**
+ * Configuration object passed to `viji.gradient()`. Defines the ramp editor's stop bounds, transparency mode, label and UI grouping/visibility.
+ * @typedef {Object} GradientConfig
+ * @property {string} [name] - Advanced: explicit parameter identity. Normally you do NOT set this — the parameter's name is inferred from the variable or object key you assign it to (`const ramp = viji.gradient(...)` → `ramp`). Set `name` only for parameters not assigned to a variable or key (created in an array, loop, or factory). Must be a valid identifier and scene-globally unique. When set, it overrides the inferred name.
+ * @property {number} [minStops] - Minimum number of stops the editor allows. Integer in `2..32`. Default: `2`.
+ * @property {number} [maxStops] - Maximum number of stops the editor allows. Integer in `2..32`; sizes the shader uniform arrays. Default: `8`.
+ * @property {string} [label] - Display name shown next to the ramp in the parameter UI. Optional — defaults to the parameter's name.
+ * @property {string} [description] - Optional tooltip / help text shown next to the control.
+ * @property {string} [group] - Group name for organizing related parameters under a shared heading. Default: `'general'`.
+ * @property {ParameterCategory} [category] - Visibility category. The control hides when its capability is unavailable. Default: `'general'`.
+ * @property {boolean} [alpha] - Enable per-stop transparency. When `true` every stop color is `#rrggbbaa` (opaque inputs padded `ff`) and the shader sampler returns a `vec4`. When `false` (default) stops are `#rrggbb` and alpha-bearing stop colors are rejected.
+ */
+
 /**
  * Reactive object returned by `viji.slider()`. `value` updates in real-time as the user drags the control; the remaining fields mirror the configuration.
  * @typedef {Object} SliderParameter
@@ -116,9 +130,10 @@
  */
 
 /**
- * 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.
+ * Reactive object returned by `viji.color()`. `value` is always a canonical lowercase hex string whose width is fixed by the parameter's mode (`#rrggbb`, or `#rrggbbaa` when declared with `alpha: true`); `rgb`, `hsb` and `alpha` are derived accessors that are recomputed (and frozen) every time the user changes the color.
  * @typedef {Object} ColorParameter
- * @property {string} value - Canonical hex color string `#rrggbb` (lowercase). Updates in real-time.
+ * @property {string} value - Canonical lowercase hex color string: `#rrggbb`, or `#rrggbbaa` when `alpha: true`. Updates in real-time.
+ * @property {number} alpha - Alpha in 0..1. Always present: `1` on an opaque parameter, the live alpha when `alpha: true`.
  * @property {Object} rgb - RGB components as integers in 0..255 (frozen, recomputed when value changes).
  * @property {number} rgb.r - Red component, integer in 0..255.
  * @property {number} rgb.g - Green component, integer in 0..255.
@@ -181,7 +196,7 @@
 /**
  * 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.
  * @typedef {Object} ImageParameter
- * @property {ImageBitmap |null} value - Uploaded image as an `ImageBitmap`, or `null` until the user provides one.
+ * @property {ImageBitmap |null} value - Uploaded image as an `ImageBitmap`, or `null` until the user provides one. Read it where you use it (inside `render()`): when the host replaces or clears the image, the previous bitmap is closed, so a reference kept from an earlier frame becomes unusable.
  * @property {string} [label] - P5-compatible image wrapper. Only available in the P5 renderer; added at runtime by the P5 adapter. Display name shown next to the upload field in the parameter UI.
  * @property {string} [description] - Tooltip / help text for the control (empty string when not configured).
  * @property {string} group - Group name under which the control appears in the UI.
@@ -209,6 +224,31 @@
  * @property {ParameterCategory} category - Visibility category that controls when the parameter is shown.
  */
 
+/**
+ * Reactive object returned by `viji.gradient()`. `value` is the live, frozen, sorted stop list; `at(t)` samples the ramp with CSS `linear-gradient` semantics (premultiplied sRGB between stops, hard edges on duplicate positions) and returns a canonical hex string in the same width as the stops.
+ * @typedef {Object} GradientParameter
+ * @property {GradientValue} value - Current stops, frozen and sorted ascending by position. Updates in real-time.
+ * @property {(t: number) => string} at - Sample the ramp at `t` (clamped to `0..1`). Returns canonical hex in the gradient's width. The shader renderer exposes the same function as `<name>(float t)` in GLSL.
+ * @property {string} [label] - Display name shown next to the ramp in the parameter UI.
+ * @property {string} [description] - Tooltip / help text for the control (empty string when not configured).
+ * @property {string} group - Group name under which the control appears in the UI.
+ * @property {ParameterCategory} category - Visibility category that controls when the parameter is shown.
+ */
+
+/**
+ * One stop of a gradient value. `color` is canonical lowercase hex in the gradient's mode (`#rrggbb`, or `#rrggbbaa` when declared with `alpha: true`).
+ * @typedef {Object} GradientStop
+ * @property {string} color - Canonical hex color of this stop.
+ * @property {number} position - Position along the ramp in `0..1`.
+ */
+
+/**
+ * One artist- or host-supplied gradient stop. `color` accepts every form a color parameter accepts, normalized per the gradient's `alpha` mode.
+ * @typedef {Object} GradientStopInput
+ * @property {ColorInput} color - Any accepted color form (hex, CSS functions, RGB / HSB objects).
+ * @property {number} position - Position along the ramp in `0..1`.
+ */
+
 /**
  * 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`.
  * @typedef {Object} AudioAPI
@@ -358,7 +398,7 @@
  * @property {DeviceSensorState} device - Internal device sensors (motion + orientation) reported by the device running the scene.
  * @property {DeviceState[]} devices - External connected devices reporting sensor / camera / audio. Each entry has its own `id`, `name`, and per-device API surface.
  * @property {(defaultValue: number, config: SliderConfig) => SliderParameter} slider - 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); }
- * @property {(defaultValue: ColorInput, config: ColorConfig) => ColorParameter} color - 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 }
+ * @property {(defaultValue: ColorInput, config: ColorConfig) => ColorParameter} color - 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` / `.alpha` accessors. Pass `alpha: true` to enable transparency: the value becomes `#rrggbbaa` and alpha-bearing inputs (`rgba()`, `#rrggbbaa`, ...) are accepted. Without it, alpha-bearing inputs are rejected. 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 }, tint.alpha -> 1 const glow = viji.color('#ffffff80', { label: 'Glow', alpha: true }); // glow.value -> '#ffffff80', glow.alpha -> 0.5
  * @property {(defaultValue: boolean, config: ToggleConfig) => ToggleParameter} toggle - 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' });
  * @property {(defaultValue: string | number, config: SelectConfig) => SelectParameter} select - 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' });
  * @property {(defaultValue: string, config: TextConfig) => TextParameter} text - 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 });
@@ -366,6 +406,7 @@
  * @property {(defaultValue: null, config: ImageConfig) => ImageParameter} image - 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);
  * @property {(config: ButtonConfig) => ButtonParameter} button - 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; }
  * @property {(defaultValue: CoordinateValue, config: CoordinateConfig) => CoordinateParameter} coordinate - 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;
+ * @property {(defaultValue: GradientInput, config: GradientConfig) => GradientParameter} gradient - Declares a gradient parameter. The host renders a ramp editor; `value` is the live, sorted stop list and `at(t)` samples the ramp (CSS `linear-gradient` semantics). Stop colors accept every color form; pass `alpha: true` for per-stop transparency. `default` is required (no evenly-spaced shorthand). Must be called at the top level of the scene, never inside `render()`. @example const ramp = viji.gradient( [{ color: '#ff6b6b', position: 0 }, { color: '#4ecdc4', position: 1 }], { label: 'Ramp' } ); function render(viji) { const fill = viji.ctx.createLinearGradient(0, 0, viji.width, 0); for (const stop of ramp.value) fill.addColorStop(stop.position, stop.color); viji.ctx.fillStyle = fill; viji.ctx.fillRect(0, 0, viji.width, viji.height); viji.ctx.fillStyle = ramp.at(0.5); // per-element color, same math as the fill }
  * @property {(type: '2d') => OffscreenCanvasRenderingContext2D} useContext - 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);
  * @property {(type: 'webgl') => WebGLRenderingContext} useContext - 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.
  * @property {(type: 'webgl2') => WebGL2RenderingContext} useContext - 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.