@viji-dev/core 0.16.1 → 0.17.0

package/dist/index.d.ts

@@ -332,16 +332,28 @@ declare interface ColorConfig {
     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`.
  */
 declare type ColorInput = string | {
     /** Red component in 0..255. */
@@ -350,6 +362,8 @@ declare type ColorInput = string | {
     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;
@@ -357,16 +371,22 @@ declare type ColorInput = string | {
     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.
  */
 declare 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. */
@@ -908,6 +928,101 @@ export declare interface FrequencyBand {
     max: number;
 }
 
+/**
+ * Configuration object passed to `viji.gradient()`. Defines the ramp editor's
+ * stop bounds, transparency mode, label and UI grouping/visibility.
+ */
+declare 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}.
+ */
+export declare 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.
+ */
+declare 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`).
+ */
+export declare 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.
+ */
+export declare 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.
+ */
+export declare 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
@@ -1273,6 +1388,16 @@ export declare interface ParameterConfig {
     step?: number;
     options?: string[] | number[];
     maxLength?: number;
+    /**
+     * For color and gradient types: the value carries a transparency channel
+     * (`#rrggbbaa` canonical form). Always present on color / gradient
+     * definitions so validators can branch on it. Default `false`.
+     */
+    alpha?: boolean;
+    /** For gradient type: minimum number of stops the control allows (integer, 2..32). */
+    minStops?: number;
+    /** For gradient type: maximum number of stops the control allows (integer, 2..32). Sizes the shader uniform arrays. */
+    maxStops?: number;
     label?: string;
     description?: string;
     hidden?: boolean;
@@ -1314,9 +1439,9 @@ export declare interface ParameterGroup {
  * The kind of UI control a parameter renders as. Used for the per-type
  * breakdown in {@link SceneData.parameterCounts}.
  */
-export declare type ParameterType = 'slider' | 'color' | 'toggle' | 'select' | 'text' | 'number' | 'image' | 'button' | 'coordinate';
+export declare type ParameterType = 'slider' | 'color' | 'toggle' | 'select' | 'text' | 'number' | 'image' | 'button' | 'coordinate' | 'gradient';
 
-export declare type ParameterValue = string | number | boolean | ImageBitmap | CoordinateValue | null;
+export declare type ParameterValue = string | number | boolean | ImageBitmap | CoordinateValue | GradientValue | null;
 
 export declare interface PerformanceStats {
     resolution: Resolution;
@@ -1634,7 +1759,10 @@ export declare interface SceneData {
  * - `RENDER_ERROR`: synchronous throw inside the artist's `render()` function.
  * - `UNCAUGHT_ERROR`: caught by the worker's `self.onerror` (async / RAF / setTimeout).
  * - `UNHANDLED_REJECTION`: caught by the worker's `unhandledrejection` handler.
- * - `SHADER_COMPILE_ERROR`: GLSL compile failure (shader mode).
+ * - `SHADER_COMPILE_ERROR`: GLSL compile / link failure, or (since 0.17.0) an invalid
+ *   `// @viji-*` directive (bad default, alpha default without `alpha:true`, gradient
+ *   stop or bounds errors, reserved-name collisions). `sourceLocation.line` is the
+ *   artist line of the failing GLSL or of the first offending directive.
  * - `P5_INIT_ERROR`: failure during P5 mode initialization (e.g. missing `render`).
  * - `SCENE_PARSE_ERROR`: the script scene could not be parsed by the load-time
  *   parameter name-inference pass (a genuine syntax error — the scene would not
@@ -2325,7 +2453,7 @@ declare interface TouchPoint {
 /** Returned by `on*` listener registration calls; invoke to unsubscribe. */
 export declare type Unsubscribe = () => void;
 
-export declare const VERSION = "0.16.1";
+export declare const VERSION = "0.17.0";
 
 /**
  * Real-time video API: drawable frame, dimensions, and the source-side
@@ -2569,12 +2697,17 @@ export declare interface VijiAPI {
     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;
     /**
@@ -2640,6 +2773,27 @@ export declare interface VijiAPI {
      * 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
@@ -2910,18 +3064,20 @@ export declare class VijiCore {
     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.
+     * and normalize them to canonical lowercase hex (`#rrggbb`, or `#rrggbbaa` when the
+     * definition declares `alpha`) before they go on the wire. For gradient parameters,
+     * accept any stop list (stop colors in any color form, any order) and normalize it to
+     * the sorted, frozen canonical stop array. This keeps the host<->worker contract simple
+     * while letting external callers use whichever form is most convenient.
      *
-     * Non-color values are returned unchanged.
+     * Other values are returned unchanged.
      */
-    private normalizeColorInputIfNeeded;
+    private normalizeParameterInput;
     /**
      * Set a single parameter value
      * Handles all parameter types including images intelligently
      */
-    setParameter(name: string, value: ParameterValue | ColorInput | File | Blob): Promise<void>;
+    setParameter(name: string, value: ParameterValue | ColorInput | GradientInput | File | Blob): Promise<void>;
     /**
      * Internal method to handle image parameter loading and transfer
      * Loads the image on the host side and creates TWO ImageBitmaps:
@@ -2935,7 +3091,7 @@ export declare class VijiCore {
      * 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 | ColorInput>): Promise<void>;
+    setParameters(values: Record<string, ParameterValue | ColorInput | GradientInput>): Promise<void>;
     /**
      * Get current parameter value
      */

package/dist/index.js

@@ -1,4 +1,4 @@
-import { C as E, I as o, V as s, a as C, b as I } from "./index-BElGM0ub.js";
+import { C as E, I as o, V as s, a as C, b as I } from "./index-BxSadexI.js";
 export {
   E as CV_FEATURE_KEYS,
   o as INPUT_CAPABILITY_KEYS,

package/dist/param-inference.js

@@ -3101,7 +3101,8 @@ const ai = /* @__PURE__ */ new Set([
   "text",
   "image",
   "button",
-  "coordinate"
+  "coordinate",
+  "gradient"
 ]);
 function ri(e) {
   return e === "button" ? 0 : 1;

package/dist/{scene-analysis-CEQRlNUL.js → scene-analysis-2Ov0HS52.js}

@@ -125,7 +125,7 @@ class a {
    * signal — a scene must enable a feature to receive its data).
    */
   static detectScriptCapabilities(e, t) {
-    /\bviji\.audio/.test(e) && (t.audio = !0), /\bviji\.video/.test(e) && (t.video = !0), /\bviji\.mouse/.test(e) && (t.mouse = !0), /\bviji\.keyboard/.test(e) && (t.keyboard = !0), /\bviji\.touches/.test(e) && (t.touch = !0), /\bviji\.pointer/.test(e) && (t.pointer = !0), /\bviji\.device\b/.test(e) && (t.sensors = !0), /\bviji\.devices/.test(e) && (t.devices = !0), /\bviji\.(slider|color|toggle|select|text|number|image|button|coordinate)\s*\(/.test(e) && (t.parameters = !0), /\benableFaceDetection\b/.test(e) && (t.cv.faceDetection = !0), /\benableFaceMesh\b/.test(e) && (t.cv.faceMesh = !0), /\benableEmotionDetection\b/.test(e) && (t.cv.emotion = !0), /\benableHandTracking\b/.test(e) && (t.cv.handTracking = !0), /\benablePoseDetection\b/.test(e) && (t.cv.poseDetection = !0), /\benableBodySegmentation\b/.test(e) && (t.cv.segmentation = !0);
+    /\bviji\.audio/.test(e) && (t.audio = !0), /\bviji\.video/.test(e) && (t.video = !0), /\bviji\.mouse/.test(e) && (t.mouse = !0), /\bviji\.keyboard/.test(e) && (t.keyboard = !0), /\bviji\.touches/.test(e) && (t.touch = !0), /\bviji\.pointer/.test(e) && (t.pointer = !0), /\bviji\.device\b/.test(e) && (t.sensors = !0), /\bviji\.devices/.test(e) && (t.devices = !0), /\bviji\.(slider|color|toggle|select|text|number|image|button|coordinate|gradient)\s*\(/.test(e) && (t.parameters = !0), /\benableFaceDetection\b/.test(e) && (t.cv.faceDetection = !0), /\benableFaceMesh\b/.test(e) && (t.cv.faceMesh = !0), /\benableEmotionDetection\b/.test(e) && (t.cv.emotion = !0), /\benableHandTracking\b/.test(e) && (t.cv.handTracking = !0), /\benablePoseDetection\b/.test(e) && (t.cv.poseDetection = !0), /\benableBodySegmentation\b/.test(e) && (t.cv.segmentation = !0);
   }
   /**
    * Detects which specific interaction inputs a scene reads (positions and

package/dist/scene-analysis.js

@@ -1,4 +1,4 @@
-import { a as n } from "./scene-analysis-CEQRlNUL.js";
+import { a as n } from "./scene-analysis-2Ov0HS52.js";
 export {
   n as analyzeScene
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viji-dev/core",
-  "version": "0.16.1",
+  "version": "0.17.0",
   "description": "Universal execution engine for Viji Creative scenes",
   "type": "module",
   "sideEffects": false,