@viji-dev/core 0.19.0 → 0.21.0

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 }