@viji-dev/core 0.20.0 → 0.21.0

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

@@ -988,6 +988,92 @@ declare global {
       textureData: Uint8Array;
   }
 
+  /**
+   * Configuration object passed to `viji.model()`. The host renders a file
+   * picker for 3D model files; the user-supplied file becomes available as a
+   * {@link ModelValue} (bytes plus a blob URL) that your own loader parses.
+   */
+  interface ModelConfig {
+      /**
+       * 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 statue = viji.model(...)` → `statue`). 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;
+      /** Display name shown next to the file picker 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;
+      /**
+       * Required: the formats your scene can parse, for example `['glb']` for a
+       * three.js `GLTFLoader` scene or `['obj', 'stl']` for p5 `loadModel()`.
+       * The host filters its picker by this list and core rejects files of other
+       * formats before the scene sees them. Must not be empty; list only what
+       * your loader handles.
+       */
+      formats: ModelFormat[];
+  }
+
+  /**
+   * Format tag of a 3D model file. One tag per supported file type; the
+   * extension and canonical MIME type of each live in `MODEL_FORMATS`.
+   */
+  type ModelFormat = 'glb' | 'obj' | 'stl' | 'ply' | 'las' | 'laz' | 'splat';
+
+  /**
+   * Reactive object returned by `viji.model()`. `value` is `null` until the user
+   * provides a 3D model file.
+   */
+  interface ModelParameter {
+      /** The current model as a {@link ModelValue}, or `null` until the user provides one. */
+      value: ModelValue | null;
+      /** Formats this parameter accepts (the `formats` you passed). */
+      readonly formats: ReadonlyArray<ModelFormat>;
+      /** 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 that controls when the parameter is shown. */
+      category: ParameterCategory;
+  }
+
+  /**
+   * The model a `viji.model()` parameter currently holds: the file as bytes plus
+   * a lazily created blob URL, tagged with its format. Core never parses the
+   * file; pass `bytes` to a loader's `parse()` or `url` to its `load()`.
+   *
+   * Read `value` where you parse it. When the host replaces or clears the
+   * model, core drops the bytes and revokes `url`; geometry you already built
+   * from them stays valid, but a URL taken from the replaced value rejects
+   * when loaded afterwards.
+   */
+  interface ModelValue {
+      /** Format tag of the file, resolved by the host before transfer. */
+      readonly format: ModelFormat;
+      /**
+       * The whole file, transferred from the host without a copy. `byteLength`
+       * is the file size. Some loaders transfer the buffer to their own worker
+       * and detach it; pass `bytes.slice(0)` to those, or disable their worker.
+       */
+      readonly bytes: ArrayBuffer;
+      /**
+       * Blob URL for loaders that take a URL (three.js `.load()`, p5 `loadModel()`).
+       * Created on first read (a Blob copies the bytes, so it is never built
+       * eagerly), cached, and revoked when the host replaces or clears the model.
+       * Reading it on a value the host already replaced throws.
+       */
+      readonly url: string;
+  }
+
   /**
    * Mouse input state for the current frame: position, individual button states,
    * per-frame movement, scroll wheel, and frame-based press / release events.
@@ -1470,7 +1556,7 @@ declare global {
       isEnding: boolean;
   }
 
-  const VERSION = "0.20.0";
+  const VERSION = "0.21.0";
 
   /**
    * Real-time video API: drawable frame, dimensions, and the source-side
@@ -1771,6 +1857,20 @@ declare global {
        * if (tex.value) ctx.drawImage(tex.value, 0, 0, viji.width, viji.height);
        */
       image: (defaultValue: null, config: ImageConfig) => ImageParameter;
+      /**
+       * Declares a 3D model parameter. `formats` is required: list only the formats
+       * your loader parses, so the host picker offers nothing the scene cannot show.
+       * The user-supplied file becomes available as `value` (a `ModelValue` with
+       * `bytes`, `url` and `format`); parse it with your own loader (three.js loaders,
+       * p5 `loadModel()`, loaders.gl). Core never parses the file. Must be called at
+       * the top level of the scene, never inside `render()`.
+       *
+       * @example
+       * const statue = viji.model(null, { label: 'Statue', formats: ['glb'] });
+       * // later, when statue.value changes:
+       * loader.parse(statue.value.bytes, '', (gltf) => scene.add(gltf.scene));
+       */
+      model: (defaultValue: null, config: ModelConfig) => ModelParameter;
       /**
        * Declares a momentary button parameter. `value` is `true` for one frame after
        * the user clicks, then auto-resets. Perfect for triggering discrete events.

package/dist/artist-global.d.ts

@@ -977,6 +977,92 @@ declare global {
       textureData: Uint8Array;
   }
 
+  /**
+   * Configuration object passed to `viji.model()`. The host renders a file
+   * picker for 3D model files; the user-supplied file becomes available as a
+   * {@link ModelValue} (bytes plus a blob URL) that your own loader parses.
+   */
+  interface ModelConfig {
+      /**
+       * 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 statue = viji.model(...)` → `statue`). 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;
+      /** Display name shown next to the file picker 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;
+      /**
+       * Required: the formats your scene can parse, for example `['glb']` for a
+       * three.js `GLTFLoader` scene or `['obj', 'stl']` for p5 `loadModel()`.
+       * The host filters its picker by this list and core rejects files of other
+       * formats before the scene sees them. Must not be empty; list only what
+       * your loader handles.
+       */
+      formats: ModelFormat[];
+  }
+
+  /**
+   * Format tag of a 3D model file. One tag per supported file type; the
+   * extension and canonical MIME type of each live in `MODEL_FORMATS`.
+   */
+  type ModelFormat = 'glb' | 'obj' | 'stl' | 'ply' | 'las' | 'laz' | 'splat';
+
+  /**
+   * Reactive object returned by `viji.model()`. `value` is `null` until the user
+   * provides a 3D model file.
+   */
+  interface ModelParameter {
+      /** The current model as a {@link ModelValue}, or `null` until the user provides one. */
+      value: ModelValue | null;
+      /** Formats this parameter accepts (the `formats` you passed). */
+      readonly formats: ReadonlyArray<ModelFormat>;
+      /** 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 that controls when the parameter is shown. */
+      category: ParameterCategory;
+  }
+
+  /**
+   * The model a `viji.model()` parameter currently holds: the file as bytes plus
+   * a lazily created blob URL, tagged with its format. Core never parses the
+   * file; pass `bytes` to a loader's `parse()` or `url` to its `load()`.
+   *
+   * Read `value` where you parse it. When the host replaces or clears the
+   * model, core drops the bytes and revokes `url`; geometry you already built
+   * from them stays valid, but a URL taken from the replaced value rejects
+   * when loaded afterwards.
+   */
+  interface ModelValue {
+      /** Format tag of the file, resolved by the host before transfer. */
+      readonly format: ModelFormat;
+      /**
+       * The whole file, transferred from the host without a copy. `byteLength`
+       * is the file size. Some loaders transfer the buffer to their own worker
+       * and detach it; pass `bytes.slice(0)` to those, or disable their worker.
+       */
+      readonly bytes: ArrayBuffer;
+      /**
+       * Blob URL for loaders that take a URL (three.js `.load()`, p5 `loadModel()`).
+       * Created on first read (a Blob copies the bytes, so it is never built
+       * eagerly), cached, and revoked when the host replaces or clears the model.
+       * Reading it on a value the host already replaced throws.
+       */
+      readonly url: string;
+  }
+
   /**
    * Mouse input state for the current frame: position, individual button states,
    * per-frame movement, scroll wheel, and frame-based press / release events.
@@ -1459,7 +1545,7 @@ declare global {
       isEnding: boolean;
   }
 
-  const VERSION = "0.20.0";
+  const VERSION = "0.21.0";
 
   /**
    * Real-time video API: drawable frame, dimensions, and the source-side
@@ -1760,6 +1846,20 @@ declare global {
        * if (tex.value) ctx.drawImage(tex.value, 0, 0, viji.width, viji.height);
        */
       image: (defaultValue: null, config: ImageConfig) => ImageParameter;
+      /**
+       * Declares a 3D model parameter. `formats` is required: list only the formats
+       * your loader parses, so the host picker offers nothing the scene cannot show.
+       * The user-supplied file becomes available as `value` (a `ModelValue` with
+       * `bytes`, `url` and `format`); parse it with your own loader (three.js loaders,
+       * p5 `loadModel()`, loaders.gl). Core never parses the file. Must be called at
+       * the top level of the scene, never inside `render()`.
+       *
+       * @example
+       * const statue = viji.model(null, { label: 'Statue', formats: ['glb'] });
+       * // later, when statue.value changes:
+       * loader.parse(statue.value.bytes, '', (gltf) => scene.add(gltf.scene));
+       */
+      model: (defaultValue: null, config: ModelConfig) => ModelParameter;
       /**
        * Declares a momentary button parameter. `value` is `true` for one frame after
        * the user clicks, then auto-resets. Perfect for triggering discrete events.

package/dist/artist-jsdoc.d.ts

@@ -82,6 +82,17 @@
  * @property {ParameterCategory} [category] - Visibility category. The control hides when its capability is unavailable. Default: `'general'`.
  */
 
+/**
+ * Configuration object passed to `viji.model()`. The host renders a file picker for 3D model files; the user-supplied file becomes available as a {@link ModelValue} (bytes plus a blob URL) that your own loader parses.
+ * @typedef {Object} ModelConfig
+ * @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 statue = viji.model(...)` → `statue`). 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 {string} [label] - Display name shown next to the file picker 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 {ModelFormat[]} formats - Required: the formats your scene can parse, for example `['glb']` for a three.js `GLTFLoader` scene or `['obj', 'stl']` for p5 `loadModel()`. The host filters its picker by this list and core rejects files of other formats before the scene sees them. Must not be empty; list only what your loader handles.
+ */
+
 /**
  * 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`.
  * @typedef {Object} ButtonConfig
@@ -203,6 +214,16 @@
  * @property {ParameterCategory} category - Visibility category that controls when the parameter is shown.
  */
 
+/**
+ * Reactive object returned by `viji.model()`. `value` is `null` until the user provides a 3D model file.
+ * @typedef {Object} ModelParameter
+ * @property {ModelValue |null} value - The current model as a {@link ModelValue}, or `null` until the user provides one.
+ * @property {string} [label] - Formats this parameter accepts (the `formats` you passed). 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.
+ * @property {ParameterCategory} category - Visibility category that controls when the parameter is shown.
+ */
+
 /**
  * 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()`.
  * @typedef {Object} ButtonParameter
@@ -249,6 +270,11 @@
  * @property {number} position - Position along the ramp in `0..1`.
  */
 
+/**
+ * The model a `viji.model()` parameter currently holds: the file as bytes plus a lazily created blob URL, tagged with its format. Core never parses the file; pass `bytes` to a loader's `parse()` or `url` to its `load()`. Read `value` where you parse it. When the host replaces or clears the model, core drops the bytes and revokes `url`; geometry you already built from them stays valid, but a URL taken from the replaced value rejects when loaded afterwards.
+ * @typedef {Object} ModelValue
+ */
+
 /**
  * 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
@@ -404,6 +430,7 @@
  * @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 });
  * @property {(defaultValue: number, config: NumberConfig) => NumberParameter} number - 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' });
  * @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 {(defaultValue: null, config: ModelConfig) => ModelParameter} model - Declares a 3D model parameter. `formats` is required: list only the formats your loader parses, so the host picker offers nothing the scene cannot show. The user-supplied file becomes available as `value` (a `ModelValue` with `bytes`, `url` and `format`); parse it with your own loader (three.js loaders, p5 `loadModel()`, loaders.gl). Core never parses the file. Must be called at the top level of the scene, never inside `render()`. @example const statue = viji.model(null, { label: 'Statue', formats: ['glb'] }); // later, when statue.value changes: loader.parse(statue.value.bytes, '', (gltf) => scene.add(gltf.scene));
  * @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 }