@viji-dev/core 0.11.8 → 0.12.0

package/dist/index.d.ts

@@ -854,8 +854,17 @@ declare interface BeatEvent {
  * then auto-resets to `false`.
  */
 declare interface ButtonConfig {
-    /** Display name shown on the button in the parameter UI. Required. */
-    label: string;
+    /**
+     * 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 speed = viji.slider(...)` → `speed`). 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 on the button 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'`. */
@@ -873,7 +882,7 @@ declare interface ButtonParameter {
     /** `true` for the single frame after the user clicks the button, `false` otherwise. */
     value: boolean;
     /** Display name shown on the button in the parameter UI. */
-    label: string;
+    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. */
@@ -947,8 +956,17 @@ export declare interface CaptureFrameOptions {
  * label and UI grouping/visibility.
  */
 declare interface ColorConfig {
-    /** Display name shown next to the color swatch in the parameter UI. Required. */
-    label: string;
+    /**
+     * 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 speed = viji.slider(...)` → `speed`). 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 color swatch 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'`. */
@@ -1009,7 +1027,7 @@ declare interface ColorParameter {
         b: number;
     };
     /** Display name shown next to the swatch in the parameter UI. */
-    label: string;
+    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. */
@@ -1023,10 +1041,19 @@ declare interface ColorParameter {
  * draggable pad; both `x` and `y` are clamped to `-1..1`.
  */
 declare interface CoordinateConfig {
+    /**
+     * 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 speed = viji.slider(...)` → `speed`). 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;
     /** Snap increment for both `x` and `y` components. Default: `0.01`. */
     step?: number;
-    /** Display name shown next to the pad in the parameter UI. Required. */
-    label: string;
+    /** Display name shown next to the pad 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'`. */
@@ -1045,7 +1072,7 @@ declare interface CoordinateParameter {
     /** Snap increment for both `x` and `y` components. */
     step: number;
     /** Display name shown next to the pad in the parameter UI. */
-    label: string;
+    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. */
@@ -1591,8 +1618,17 @@ export declare interface HandData {
  * or a P5 image wrapper (P5 renderer).
  */
 declare interface ImageConfig {
-    /** Display name shown next to the upload field in the parameter UI. Required. */
-    label: string;
+    /**
+     * 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 speed = viji.slider(...)` → `speed`). 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 upload field 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'`. */
@@ -1612,7 +1648,7 @@ declare interface ImageParameter {
     /** 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;
+    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. */
@@ -1768,6 +1804,15 @@ export declare interface MouseEventData {
  * label, and UI grouping/visibility for a precise numeric input.
  */
 declare interface NumberConfig {
+    /**
+     * 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 speed = viji.slider(...)` → `speed`). 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;
     /** Inclusive minimum value. Default: `0`. */
     min?: number;
     /** Inclusive maximum value. Default: `100`. */
@@ -1780,8 +1825,8 @@ declare interface NumberConfig {
      * (`step: 0.001`).
      */
     step?: number;
-    /** Display name shown next to the input in the parameter UI. Required. */
-    label: string;
+    /** Display name shown next to the input 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'`. */
@@ -1804,7 +1849,7 @@ declare interface NumberParameter {
     /** Increment between values. */
     step: number;
     /** Display name shown next to the input in the parameter UI. */
-    label: string;
+    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. */
@@ -1880,8 +1925,19 @@ export declare interface ParameterConfig {
 }
 
 export declare interface ParameterDefinition {
+    /**
+     * Stable parameter identity. Always equals the Record key under which the
+     * definition is registered in `groups[].parameters` — addressing
+     * (`setParameter`), saved values, presets, locks, and the controller
+     * protocol all resolve by `name`. For script scenes (native/p5) `name` is
+     * the artist's own variable or object-key name, inferred at compile time;
+     * for shader scenes it is the GLSL uniform name. `label` is display-only —
+     * never key UI lists or lookups off `label`.
+     */
+    name: string;
     type: ParameterType;
     defaultValue: ParameterValue;
+    /** Display text shown in parameter UIs. Not an identity — see `name`. */
     label?: string;
     description?: string;
     group?: string;
@@ -2184,10 +2240,13 @@ export declare interface SceneConsoleMessage {
  * Static metadata about a scene, derived without running it. Returned by
  * `VijiCore.getSceneData()`.
  *
- * `renderer`, `p5CanvasMode`, and `capabilities` are available synchronously
- * once the core is constructed. The parameter counts populate once the scene
- * has registered its parameters (mirroring how parameter data has always
- * surfaced), so read them after the core has initialized the scene.
+ * `renderer`, `p5CanvasMode`, and `capabilities` are **final when
+ * `initialize()` resolves** — the worker analyzes the scene source and reports
+ * the results in its `scene-analysis` ack, which `initialize()` awaits before
+ * resolving. Reads before that return placeholder defaults. The parameter
+ * counts populate once the scene has registered its parameters (mirroring how
+ * parameter data has always surfaced), so read them after the core has
+ * initialized the scene.
  */
 export declare interface SceneData {
     /** Detected renderer the scene targets. */
@@ -2222,9 +2281,19 @@ export declare interface SceneData {
  * - `UNHANDLED_REJECTION`: caught by the worker's `unhandledrejection` handler.
  * - `SHADER_COMPILE_ERROR`: GLSL compile failure (shader mode).
  * - `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
+ *   have executed either).
+ * - `PARAM_NAME_MISSING`: a `viji.<type>(...)` call was not assigned to a
+ *   variable or object key and carries no explicit `name` — nothing to infer an
+ *   identity from. Assign it to a `const`, or pass `name:'...'`.
+ * - `PARAM_NAME_DUPLICATE`: two parameters resolved to the same name. Names are
+ *   scene-global; rename one, or pass `name:'...'` to distinguish them.
+ * - `PARAM_NAME_INVALID`: an explicit `name` is not a valid identifier or is a
+ *   reserved word (`__proto__`, `constructor`, `prototype`).
  * - `ENGINE_INTERNAL`: engine path with no artist attribution.
  */
-export declare type SceneErrorCode = 'SCENE_CODE_ERROR' | 'RENDER_ERROR' | 'UNCAUGHT_ERROR' | 'UNHANDLED_REJECTION' | 'SHADER_COMPILE_ERROR' | 'P5_INIT_ERROR' | 'ENGINE_INTERNAL';
+export declare type SceneErrorCode = 'SCENE_CODE_ERROR' | 'RENDER_ERROR' | 'UNCAUGHT_ERROR' | 'UNHANDLED_REJECTION' | 'SHADER_COMPILE_ERROR' | 'P5_INIT_ERROR' | 'SCENE_PARSE_ERROR' | 'PARAM_NAME_MISSING' | 'PARAM_NAME_DUPLICATE' | 'PARAM_NAME_INVALID' | 'ENGINE_INTERNAL';
 
 /**
  * Structured scene runtime error envelope surfaced via `VijiCore.onSceneRuntimeError`.
@@ -2315,10 +2384,19 @@ declare interface SegmentationData {
  * as a dropdown or segmented control.
  */
 declare interface SelectConfig {
+    /**
+     * 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 speed = viji.slider(...)` → `speed`). 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;
     /** Available choices. The element type (`string` or `number`) becomes the parameter's value type. Required. */
     options: string[] | number[];
-    /** Display name shown next to the dropdown in the parameter UI. Required. */
-    label: string;
+    /** Display name shown next to the dropdown 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'`. */
@@ -2337,7 +2415,7 @@ declare interface SelectParameter {
     /** The full list of choices originally configured. */
     options: string[] | number[];
     /** Display name shown next to the dropdown in the parameter UI. */
-    label: string;
+    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. */
@@ -2653,6 +2731,15 @@ export declare interface SerializedTempoInductionState {
  * increment, label, and UI grouping/visibility.
  */
 declare interface SliderConfig {
+    /**
+     * 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 speed = viji.slider(...)` → `speed`). 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;
     /** Inclusive minimum value of the slider. Default: `0`. */
     min?: number;
     /** Inclusive maximum value of the slider. Default: `100`. */
@@ -2665,8 +2752,8 @@ declare interface SliderConfig {
      * (`step: 1` on a range of `3..30`) or fine precision (`step: 0.001`).
      */
     step?: number;
-    /** Display name shown next to the control in the parameter UI. Required. */
-    label: string;
+    /** Display name shown next to the control 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'`. */
@@ -2689,7 +2776,7 @@ declare interface SliderParameter {
     /** Increment between values. */
     step: number;
     /** Display name shown next to the control in the parameter UI. */
-    label: string;
+    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. */
@@ -2714,8 +2801,17 @@ export declare interface StateImportError {
  * text input field.
  */
 declare interface TextConfig {
-    /** Display name shown next to the text field in the parameter UI. Required. */
-    label: string;
+    /**
+     * 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 speed = viji.slider(...)` → `speed`). 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 text field 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'`. */
@@ -2736,7 +2832,7 @@ declare interface TextParameter {
     /** Maximum character count enforced by the host UI. */
     maxLength?: number;
     /** Display name shown next to the input in the parameter UI. */
-    label: string;
+    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. */
@@ -2750,8 +2846,17 @@ declare interface TextParameter {
  * label and UI grouping/visibility.
  */
 declare interface ToggleConfig {
-    /** Display name shown next to the switch in the parameter UI. Required. */
-    label: string;
+    /**
+     * 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 speed = viji.slider(...)` → `speed`). 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 switch 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'`. */
@@ -2768,7 +2873,7 @@ declare interface ToggleParameter {
     /** Current state of the switch. Updates in real-time when the user toggles it. */
     value: boolean;
     /** Display name shown next to the switch in the parameter UI. */
-    label: string;
+    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. */
@@ -2871,7 +2976,7 @@ declare type TrackingState = 'TRACKING' | 'LOCKED' | 'BREAKDOWN' | 'LOST';
 /** Returned by `on*` listener registration calls; invoke to unsubscribe. */
 export declare type Unsubscribe = () => void;
 
-export declare const VERSION = "0.11.8";
+export declare const VERSION = "0.12.0";
 
 /**
  * Real-time video API: drawable frame, dimensions, and the source-side
@@ -3234,6 +3339,7 @@ export declare class VijiCore {
     private isInitialized;
     private isDestroyed;
     private isInitializing;
+    private engineGroupReleased;
     private instanceId;
     private screenRefreshRate;
     private refreshRateRafId;
@@ -3262,6 +3368,8 @@ export declare class VijiCore {
     private sceneConsumesAnalysedFrame;
     private sceneContextType?;
     private parametersInitialized;
+    private isAwaitingSceneAnalysis;
+    private analysisWindowSceneError;
     private parameterListeners;
     private parameterDefinedListeners;
     private parameterErrorListeners;
@@ -3359,9 +3467,36 @@ export declare class VijiCore {
      */
     hide(): void;
     /**
-     * Initializes the core components in sequence
+     * Initializes the core components in sequence. When this resolves the
+     * scene is live and `getSceneData()`'s analysis fields are final.
+     *
+     * Rejection contract — three codes pass through unwrapped so consumers
+     * can branch on them:
+     * - `INITIALIZATION_CANCELLED` — `destroy()` landed while initializing.
+     *   Expected during rapid mount/unmount (hover previews, deck swaps);
+     *   not a failure.
+     * - `INSTANCE_DESTROYED` — called on a destroyed core, or on one whose
+     *   previous `initialize()` failed and released its engine reference;
+     *   construct a fresh core instead.
+     * - `SCENE_DECRYPT_ERROR` — an encrypted (`viji-enc:`) scene could not be
+     *   decrypted (wrong/missing key component, tampered or malformed
+     *   envelope, unsupported envelope version). Permanent for this payload:
+     *   the scene genuinely cannot run — surface a typed error state, do not
+     *   retry.
+     *
+     * Every other failure (including a `scene-analysis` ack failure or
+     * timeout) rejects as `INITIALIZATION_ERROR` with the underlying error in
+     * `details.error`. Note `details` no longer carries the config.
      */
     initialize(): Promise<void>;
+    /**
+     * Release this core's engine-group reference after a failed initialize().
+     * Idempotent; skipped when destroy() owns the teardown (it detaches and
+     * releases itself). Detach + release are safe on partially-attached state:
+     * `detachSink` deletes from maps and `release` is a member-set delete with
+     * a `_destroyed`-guarded last-release dispose.
+     */
+    private releaseEngineGroupOnFailure;
     /**
      * Sets up the interaction system for Phase 7.
      *
@@ -3449,8 +3584,10 @@ export declare class VijiCore {
      * Returns static metadata about the scene: its renderer, the capabilities its
      * code declares it uses, and its parameter shape.
      *
-     * `renderer`, `p5CanvasMode`, and `capabilities` are available immediately
-     * after construction; the parameter counts populate once the scene has
+     * `renderer`, `p5CanvasMode`, and `capabilities` are **final when
+     * `initialize()` resolves** — they are assigned from the worker's
+     * `scene-analysis` ack during initialization; reads before that return
+     * placeholder defaults. The parameter counts populate once the scene has
      * registered its parameters.
      *
      * Distinct from {@link getCapabilities}, which reports what the *host*
@@ -3495,7 +3632,13 @@ export declare class VijiCore {
      */
     unlinkEventSource(): void;
     /**
-     * Link source cores that this core will pull frames from
+     * Link source cores that this core will pull frames from.
+     *
+     * Requires an initialized core: the mixer's renderer type decides the
+     * capture flip orientation, and `sceneRenderer` is final only when
+     * `initialize()` resolves (Design B). A pre-ready call would silently read
+     * the `'native'` default and composite shader mixers un-flipped — silently
+     * wrong output, so it fails loud instead.
      */
     linkFrameSources(...sourceCores: VijiCore[]): void;
     /**
@@ -4424,6 +4567,18 @@ export declare interface VijiCoreConfig {
     _sc?: string;
     /** Initial render hint (logo variant/position), applied before the first frame. */
     _rh?: number;
+    /**
+     * Per-scene key component for encrypted (`viji-enc:`) scene delivery —
+     * an opaque base64url blob served next to the scene payload. Required to
+     * decrypt an encrypted `sceneCode`; ignored for plaintext scenes. Routed
+     * to the worker inside the `set-scene-code` payload on the direct control
+     * port (never through the iframe bootstrap).
+     *
+     * Omitted from the `configuration` getter: serializing ciphertext and the
+     * key component into one log/state dump would make the dump decryptable
+     * with the shipped bundle constant — do not persist or log this value.
+     */
+    _sk?: string;
     /** Called when the scene is visually live (render loop running, branding applied) but before audio/video/WASM setup completes. */
     onRenderStart?: () => void;
     /**

package/dist/index.js

@@ -1,4 +1,4 @@
-import { A as e, C as i, I as r, V as o, a as C, c as E, b as A } from "./index-fdus0y3o.js";
+import { A as e, C as i, I as r, V as o, a as C, c as E, b as A } from "./index-BcsAA44l.js";
 export {
   e as AudioSystem,
   i as CV_FEATURE_KEYS,
@@ -8,4 +8,3 @@ export {
   E as VijiCoreError,
   A as analyzeSceneCapabilities
 };
-//# sourceMappingURL=index.js.map

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@viji-dev/core",
-  "version": "0.11.8",
+  "version": "0.12.0",
   "description": "Universal execution engine for Viji Creative scenes",
   "type": "module",
+  "sideEffects": false,
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -50,12 +51,13 @@
   "scripts": {
     "prebuild": "node scripts/prebuild-clean.mjs && node scripts/sync-version.mjs",
     "version": "npm run build && git add -A",
-    "build": "vite build && node scripts/copy-tasks-assets.mjs && node scripts/build-artist-types.mjs && node scripts/lint-artist-types-drift.mjs && node scripts/build-docs-api.mjs",
+    "build": "vite build && node scripts/copy-tasks-assets.mjs && node scripts/minify-dist.mjs && node scripts/build-artist-types.mjs && node scripts/lint-artist-types-drift.mjs && node scripts/build-docs-api.mjs",
     "build:docs": "node scripts/build-docs-api.mjs",
     "lint:ai-prompts-drift": "node scripts/lint-ai-prompts-drift.mjs",
     "dev": "node scripts/sync-version.mjs && vite build --watch",
     "integration": "vite --config integration-example/vite.config.ts",
     "test": "vitest",
+    "test:run": "vitest run",
     "test:coverage": "vitest --coverage",
     "type-check": "tsc --noEmit",
     "lint": "eslint src --ext .ts"
@@ -93,7 +95,10 @@
   },
   "dependencies": {
     "@mediapipe/tasks-vision": "^0.10.20",
+    "@noble/ciphers": "2.3.0",
     "@noble/curves": "^2.2.0",
+    "@noble/hashes": "2.2.0",
+    "acorn": "8.15.0",
     "essentia.js": "^0.1.3",
     "fft.js": "^4.0.4",
     "sucrase": "^3.35.1"