@viji-dev/core 0.7.0 → 0.7.5

package/dist/{essentia-wasm.web-iwIx5LHu.js → essentia-wasm.web-Bh9tTilM.js}

@@ -1,4 +1,4 @@
-import { g as kn } from "./index-BCIUaaLW.js";
+import { g as kn } from "./index-B1JJ8Mko.js";
 function jn(Oe, ot) {
   for (var ve = 0; ve < ot.length; ve++) {
     const Z = ot[ve];
@@ -3374,4 +3374,4 @@ const xn = /* @__PURE__ */ kn(yi), Ln = /* @__PURE__ */ jn({
 export {
   Ln as e
 };
-//# sourceMappingURL=essentia-wasm.web-iwIx5LHu.js.map
+//# sourceMappingURL=essentia-wasm.web-Bh9tTilM.js.map

package/dist/{index-BCIUaaLW.js → index-B1JJ8Mko.js}

@@ -536,7 +536,7 @@ class DB {
       }
   }
 }
-const oB = "" + new URL("assets/viji.worker-sMAb5DcQ.js", import.meta.url).href, hB = new URL("assets/wasm/vision_wasm_internal.js", import.meta.url).href, RB = new URL("assets/wasm/vision_wasm_internal.wasm", import.meta.url).href, wB = new URL("assets/wasm/vision_wasm_nosimd_internal.js", import.meta.url).href, sB = new URL("assets/wasm/vision_wasm_nosimd_internal.wasm", import.meta.url).href;
+const oB = "" + new URL("assets/viji.worker-CXp6CGrq.js", import.meta.url).href, hB = new URL("assets/wasm/vision_wasm_internal.js", import.meta.url).href, RB = new URL("assets/wasm/vision_wasm_internal.wasm", import.meta.url).href, wB = new URL("assets/wasm/vision_wasm_nosimd_internal.js", import.meta.url).href, sB = new URL("assets/wasm/vision_wasm_nosimd_internal.wasm", import.meta.url).href;
 class FB {
   constructor(A, B, I) {
     this.iframeManager = A, this.sceneCode = B, this.init = I;
@@ -1520,7 +1520,7 @@ class YB {
     if (!this.isInitialized)
       return this.initPromise ? this.initPromise : (this.initPromise = (async () => {
         try {
-          const A = await import("./essentia.js-core.es-CC_3Ap1i.js"), B = await import("./essentia-wasm.web-iwIx5LHu.js").then((g) => g.e), I = A.Essentia || A.default?.Essentia || A.default;
+          const A = await import("./essentia.js-core.es-CC_3Ap1i.js"), B = await import("./essentia-wasm.web-Bh9tTilM.js").then((g) => g.e), I = A.Essentia || A.default?.Essentia || A.default;
           let Q = B.default || B.EssentiaWASM || B.default?.EssentiaWASM;
           if (!Q)
             throw new Error("WASM module not found - check essentia-wasm.web.js export");
@@ -8398,7 +8398,7 @@ function DI(R) {
     expectedVersion: 1
   } : typeof A.senderTime != "number" ? { code: "invalid-field", details: "senderTime must be a number", field: "senderTime" } : null;
 }
-const oI = "0.7.0";
+const oI = "0.7.4";
 export {
   yA as A,
   oI as V,
@@ -8406,4 +8406,4 @@ export {
   S as b,
   vB as g
 };
-//# sourceMappingURL=index-BCIUaaLW.js.map
+//# sourceMappingURL=index-B1JJ8Mko.js.map

package/dist/index.d.ts

@@ -1111,15 +1111,25 @@ declare interface FaceBlendshapes {
 }
 
 /**
- * One detected face produced by the video CV pipeline. Always carries `id`,
- * `bounds`, `center`, and `confidence`; the rest is populated only when the
- * matching CV feature is enabled (face mesh for `landmarks` and `headPose`,
- * emotion detection for `expressions` and `blendshapes`).
+ * One detected face produced by the video CV pipeline. Each field is
+ * populated only by its source model; fields whose source model is not
+ * enabled read as `null` so the absence is loud rather than silent. Enable
+ * the relevant `enable*` verb on `viji.video.cv` to populate each group:
+ *
+ * - `bounds`, `center`, `confidence`: populated by `enableFaceDetection(true)`.
+ * - `landmarks`: populated by `enableFaceMesh(true)` (empty array otherwise).
+ * - `headPose`: populated by `enableFaceMesh(true)`.
+ * - `blendshapes`, `expressions`: populated by `enableEmotionDetection(true)`.
+ *
+ * If a field is `null`, call the corresponding `enable*` verb on
+ * `viji.video.cv` to populate it. Each active CV feature consumes its own
+ * WebGL context for MediaPipe; enabling many at once on lower-end hardware
+ * can hit context limits.
  */
 export declare interface FaceData {
     /** Index-based face identifier (`0`, `1`, …). Stable within a single frame, may change between frames. */
     id: number;
-    /** Bounding box, all components normalized to 0..1 of the source frame. */
+    /** Bounding box, all components normalized to 0..1 of the source frame. `null` unless face detection is enabled. */
     bounds: {
         /** Left edge of the face bounding box, normalized 0..1. */
         x: number;
@@ -1129,16 +1139,16 @@ export declare interface FaceData {
         width: number;
         /** Height of the face bounding box, normalized 0..1. */
         height: number;
-    };
-    /** Center of the bounding box, normalized 0..1. */
+    } | null;
+    /** Center of the bounding box, normalized 0..1. `null` unless face detection is enabled. */
     center: {
         /** Horizontal center of the face, normalized 0..1. */
         x: number;
         /** Vertical center of the face, normalized 0..1. */
         y: number;
-    };
-    /** Detection confidence in 0..1. */
-    confidence: number;
+    } | null;
+    /** Detection confidence in 0..1. `null` unless face detection is enabled. */
+    confidence: number | null;
     /** 468 normalized face mesh landmarks when face mesh is enabled; empty array otherwise. */
     landmarks: {
         /** Horizontal landmark coordinate, normalized 0..1. */
@@ -1148,7 +1158,16 @@ export declare interface FaceData {
         /** Optional depth (relative). */
         z?: number;
     }[];
-    /** Seven expression confidence scores in 0..1. All zero unless emotion detection is enabled. */
+    /** Estimated head rotation in degrees. `null` unless face mesh is enabled. */
+    headPose: {
+        /** Up/down rotation in degrees (-90..90). Positive = head looking up, negative = looking down. */
+        pitch: number;
+        /** Left/right rotation in degrees (-90..90). Positive = head turned to the subject's right, negative = to the left. */
+        yaw: number;
+        /** Tilt rotation in degrees (-180..180). Positive = head tilted to the subject's right (right ear toward right shoulder). */
+        roll: number;
+    } | null;
+    /** Seven expression confidence scores in 0..1. `null` unless emotion detection is enabled. */
     expressions: {
         /** Confidence (0..1) of a neutral expression. */
         neutral: number;
@@ -1164,18 +1183,9 @@ export declare interface FaceData {
         disgusted: number;
         /** Confidence (0..1) of a fearful expression. */
         fearful: number;
-    };
-    /** Estimated head rotation. All zero unless face mesh is enabled. */
-    headPose: {
-        /** Up/down rotation in degrees (-90..90). Positive = head looking up, negative = looking down. */
-        pitch: number;
-        /** Left/right rotation in degrees (-90..90). Positive = head turned to the subject's right, negative = to the left. */
-        yaw: number;
-        /** Tilt rotation in degrees (-180..180). Positive = head tilted to the subject's right (right ear toward right shoulder). */
-        roll: number;
-    };
-    /** 52 ARKit-compatible facial muscle coefficients. All zero unless emotion detection is enabled. */
-    blendshapes: FaceBlendshapes;
+    } | null;
+    /** 52 ARKit-compatible facial muscle coefficients. `null` unless emotion detection is enabled. */
+    blendshapes: FaceBlendshapes | null;
 }
 
 declare interface FrameRateInfo {
@@ -1711,6 +1721,10 @@ export declare type Resolution = {
  * inspection, a per-argument byte cap (`consoleArgMaxBytes`), and an argument
  * count cap (`consoleMaxArgsPerCall`). High-cardinality logs are rate-limited
  * by `consoleMaxUniqueSignaturesPerSecond`.
+ *
+ * Coalescing semantics match `SceneRuntimeError`: `count` and `firstSeenAt`
+ * are cumulative for the scene session (monotonically non-decreasing across
+ * coalescing windows), reset only when the worker terminates.
  */
 export declare interface SceneConsoleMessage {
     /** Console method invoked. */
@@ -1719,9 +1733,19 @@ export declare interface SceneConsoleMessage {
     args: string[];
     /** Stable hash of `level` and the stringified arguments, used for coalescing. */
     signatureHash: string;
-    /** Number of occurrences of this signature accumulated in the current window. */
+    /**
+     * Cumulative number of occurrences of this signature since it was first
+     * seen in this scene session. Monotonically non-decreasing across
+     * coalescing windows; each fire carries the up-to-date total. Consumers
+     * that maintain a per-signature view should REPLACE their stored count
+     * with this value on each fire, not add to it.
+     */
     count: number;
-    /** Millisecond timestamp of the first occurrence of this signature in the current window. */
+    /**
+     * Millisecond timestamp of the FIRST occurrence of this signature in this
+     * scene session. Set once and unchanged for every subsequent fire of the
+     * same signature.
+     */
     firstSeenAt: number;
     /** Millisecond timestamp of the most recent occurrence. */
     lastSeenAt: number;
@@ -1749,9 +1773,15 @@ export declare type SceneErrorCode = 'SCENE_CODE_ERROR' | 'RENDER_ERROR' | 'UNCA
 /**
  * Structured scene runtime error envelope surfaced via `VijiCore.onSceneRuntimeError`.
  *
- * Identical signatures are coalesced inside the worker: the first occurrence in
- * a window fires with `count: 1`, subsequent occurrences increment `count`, and
- * a trailing rollup fires at window close if more than one occurrence was seen.
+ * Identical signatures are coalesced inside the worker. The first ever
+ * occurrence of a signature in this scene session fires immediately with
+ * `count: 1`; further occurrences within the coalescing window are absorbed
+ * silently and emitted as a single trailing rollup with the up-to-date
+ * cumulative count at window close. Subsequent bursts of the same signature
+ * refire a leading edge with the up-to-date cumulative count and re-arm the
+ * rollup timer. `count` and `firstSeenAt` are cumulative for the scene
+ * session — they persist across coalescing windows and are reset only when
+ * the worker terminates (scene teardown).
  *
  * The host-side `console.error('Scene error:', data)` tee continues to fire
  * alongside the listener (never silenced based on listener presence).
@@ -1775,9 +1805,20 @@ export declare interface SceneRuntimeError {
     code: SceneErrorCode;
     /** Stable hash of `message` and the first artist stack frame, used for coalescing. */
     signatureHash: string;
-    /** Number of occurrences of this signature accumulated in the current window. */
+    /**
+     * Cumulative number of occurrences of this signature since it was first
+     * seen in this scene session. Monotonically non-decreasing across
+     * coalescing windows; each fire carries the up-to-date total. Consumers
+     * that maintain a per-signature view should REPLACE their stored count
+     * with this value on each fire, not add to it.
+     */
     count: number;
-    /** Millisecond timestamp of the first occurrence of this signature in the current window. */
+    /**
+     * Millisecond timestamp of the FIRST occurrence of this signature in this
+     * scene session. Set once and unchanged for every subsequent fire of the
+     * same signature — `Date.now() - firstSeenAt` is the lifetime of the
+     * signature in this session, useful for chronicity reasoning.
+     */
     firstSeenAt: number;
     /** Millisecond timestamp of the most recent occurrence. */
     lastSeenAt: number;
@@ -2368,7 +2409,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.7.0";
+export declare const VERSION = "0.7.4";
 
 /**
  * Real-time video API: drawable frame, dimensions, and the source-side
@@ -2477,35 +2518,73 @@ export declare interface VideoCVAPI {
     /** Body segmentation mask, or `null` when segmentation is off. */
     segmentation: SegmentationData | null;
     /**
-     * Toggle face detection (bounding box, center, confidence, id).
+     * Toggle face detection. Populates `face.bounds`, `face.center`,
+     * `face.confidence` on each detected face. Independent of face mesh and
+     * emotion detection.
+     *
+     * Safe to call from module scope as well as from inside `render()`. The
+     * verb is idempotent and reference-counted; per-frame calls inside
+     * `render()` (the canonical toggle-gated pattern) are cheap.
+     *
      * @returns Resolves once the underlying pipeline has finished switching.
      */
     enableFaceDetection(enabled: boolean): Promise<void>;
     /**
-     * Toggle 468-point face mesh + head pose (`pitch`, `yaw`, `roll`). Implies
-     * face detection.
+     * Toggle 468-point face mesh and computed head pose (`pitch`, `yaw`,
+     * `roll`). Populates `face.landmarks` and `face.headPose` on the face
+     * entry. Does NOT populate `face.bounds` / `face.center` / `face.confidence`
+     * — those are produced only by face detection. Enable both if you need
+     * both, or compute bounds from `face.landmarks` min/max yourself.
+     *
+     * Safe to call from module scope as well as from inside `render()`. The
+     * verb is idempotent and reference-counted.
+     *
      * @returns Resolves once the pipeline has finished switching.
      */
     enableFaceMesh(enabled: boolean): Promise<void>;
     /**
      * Toggle 7 expressions + 52 ARKit blendshape coefficients on each face.
-     * Implies face mesh.
+     * Populates `face.blendshapes` and `face.expressions`. Internally requires
+     * the face landmarker model (loads it alongside `enableFaceMesh` if both
+     * are enabled; loads it on its own otherwise so `face.landmarks` and
+     * `face.headPose` are also populated). Does NOT populate
+     * `face.bounds` / `face.center` / `face.confidence` — enable face
+     * detection for those.
+     *
+     * Safe to call from module scope as well as from inside `render()`. The
+     * verb is idempotent and reference-counted.
+     *
      * @returns Resolves once the pipeline has finished switching.
      */
     enableEmotionDetection(enabled: boolean): Promise<void>;
     /**
-     * Toggle 21-point hand landmarks + ML-classified gesture confidences for up
-     * to two hands.
+     * Toggle 21-point hand landmarks and ML-classified gesture confidences
+     * for up to two hands. Populates `viji.video.cv.hands[]` with `landmarks`,
+     * `palm`, `bounds` (computed from landmarks), and `gestures`.
+     *
+     * Safe to call from module scope as well as from inside `render()`. The
+     * verb is idempotent and reference-counted.
+     *
      * @returns Resolves once the pipeline has finished switching.
      */
     enableHandTracking(enabled: boolean): Promise<void>;
     /**
      * Toggle 33-point BlazePose body landmarks (face / torso / arms / legs).
+     * Populates `viji.video.cv.pose`.
+     *
+     * Safe to call from module scope as well as from inside `render()`. The
+     * verb is idempotent and reference-counted.
+     *
      * @returns Resolves once the pipeline has finished switching.
      */
     enablePoseDetection(enabled: boolean): Promise<void>;
     /**
-     * Toggle per-pixel person/background segmentation mask.
+     * Toggle per-pixel person/background segmentation mask. Populates
+     * `viji.video.cv.segmentation`.
+     *
+     * Safe to call from module scope as well as from inside `render()`. The
+     * verb is idempotent and reference-counted.
+     *
      * @returns Resolves once the pipeline has finished switching.
      */
     enableBodySegmentation(enabled: boolean): Promise<void>;

package/dist/index.js

@@ -1,4 +1,4 @@
-import { A as a, V as i, a as s, b as e } from "./index-BCIUaaLW.js";
+import { A as a, V as i, a as s, b as e } from "./index-B1JJ8Mko.js";
 export {
   a as AudioSystem,
   i as VERSION,

package/package.json

@@ -1,100 +1,100 @@
-{
-  "name": "@viji-dev/core",
-  "version": "0.7.0",
-  "description": "Universal execution engine for Viji Creative scenes",
-  "type": "module",
-  "main": "./dist/index.js",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
-    },
-    "./artist-global": {
-      "types": "./dist/artist-global.d.ts"
-    },
-    "./artist-dts": {
-      "import": "./dist/artist-dts.js",
-      "types": "./dist/artist-dts.d.ts"
-    },
-    "./artist-jsdoc": {
-      "types": "./dist/artist-jsdoc.d.ts"
-    },
-    "./artist-js-ambient": {
-      "types": "./dist/artist-js-ambient.d.ts"
-    },
-    "./artist-dts-p5": {
-      "import": "./dist/artist-dts-p5.js",
-      "types": "./dist/artist-dts-p5.d.ts"
-    },
-    "./artist-global-p5": {
-      "types": "./dist/artist-global-p5.d.ts"
-    },
-    "./shader-uniforms": {
-      "import": "./dist/shader-uniforms.js",
-      "types": "./dist/shader-uniforms.d.ts"
-    },
-    "./docs-api": {
-      "import": "./dist/docs-api.js",
-      "types": "./dist/docs-api.d.ts"
-    }
-  },
-  "files": [
-    "dist/*.js",
-    "dist/*.d.ts",
-    "dist/assets",
-    "!dist/**/*.map",
-    "README.md"
-  ],
-  "scripts": {
-    "prebuild": "node scripts/prebuild-clean.mjs",
-    "build": "vite build && node scripts/copy-tasks-assets.mjs && node scripts/build-artist-types.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": "vite build --watch",
-    "integration": "vite --config integration-example/vite.config.ts",
-    "test": "vitest",
-    "test:coverage": "vitest --coverage",
-    "type-check": "tsc --noEmit",
-    "lint": "eslint src --ext .ts"
-  },
-  "keywords": [
-    "viji",
-    "creative",
-    "webgl",
-    "audio-reactive",
-    "canvas",
-    "webworker"
-  ],
-  "author": "Viji Team",
-  "license": "SEE LICENSE IN LICENSE",
-  "devDependencies": {
-    "@types/node": "^20.0.0",
-    "@types/p5": "^1.7.6",
-    "@typescript-eslint/eslint-plugin": "^6.0.0",
-    "@typescript-eslint/parser": "^6.0.0",
-    "@vitest/coverage-v8": "^1.0.0",
-    "dts-bundle-generator": "^9.5.1",
-    "eslint": "^8.0.0",
-    "github-slugger": "^2.0.0",
-    "happy-dom": "^18.0.1",
-    "mdast-util-to-string": "^4.0.0",
-    "remark-parse": "^11.0.0",
-    "typescript": "^5.0.0",
-    "unified": "^11.0.5",
-    "vite": "^5.0.0",
-    "vite-plugin-dts": "^3.0.0",
-    "vitest": "^1.0.0"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "dependencies": {
-    "@mediapipe/tasks-vision": "^0.10.20",
-    "@noble/curves": "^2.2.0",
-    "essentia.js": "^0.1.3",
-    "fft.js": "^4.0.4",
-    "sucrase": "^3.35.1"
-  }
-}
+{
+  "name": "@viji-dev/core",
+  "version": "0.7.5",
+  "description": "Universal execution engine for Viji Creative scenes",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./artist-global": {
+      "types": "./dist/artist-global.d.ts"
+    },
+    "./artist-dts": {
+      "import": "./dist/artist-dts.js",
+      "types": "./dist/artist-dts.d.ts"
+    },
+    "./artist-jsdoc": {
+      "types": "./dist/artist-jsdoc.d.ts"
+    },
+    "./artist-js-ambient": {
+      "types": "./dist/artist-js-ambient.d.ts"
+    },
+    "./artist-dts-p5": {
+      "import": "./dist/artist-dts-p5.js",
+      "types": "./dist/artist-dts-p5.d.ts"
+    },
+    "./artist-global-p5": {
+      "types": "./dist/artist-global-p5.d.ts"
+    },
+    "./shader-uniforms": {
+      "import": "./dist/shader-uniforms.js",
+      "types": "./dist/shader-uniforms.d.ts"
+    },
+    "./docs-api": {
+      "import": "./dist/docs-api.js",
+      "types": "./dist/docs-api.d.ts"
+    }
+  },
+  "files": [
+    "dist/*.js",
+    "dist/*.d.ts",
+    "dist/assets",
+    "!dist/**/*.map",
+    "README.md"
+  ],
+  "scripts": {
+    "prebuild": "node scripts/prebuild-clean.mjs",
+    "build": "vite build && node scripts/copy-tasks-assets.mjs && node scripts/build-artist-types.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": "vite build --watch",
+    "integration": "vite --config integration-example/vite.config.ts",
+    "test": "vitest",
+    "test:coverage": "vitest --coverage",
+    "type-check": "tsc --noEmit",
+    "lint": "eslint src --ext .ts"
+  },
+  "keywords": [
+    "viji",
+    "creative",
+    "webgl",
+    "audio-reactive",
+    "canvas",
+    "webworker"
+  ],
+  "author": "Viji Team",
+  "license": "SEE LICENSE IN LICENSE",
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/p5": "^1.7.6",
+    "@typescript-eslint/eslint-plugin": "^6.0.0",
+    "@typescript-eslint/parser": "^6.0.0",
+    "@vitest/coverage-v8": "^1.0.0",
+    "dts-bundle-generator": "^9.5.1",
+    "eslint": "^8.0.0",
+    "github-slugger": "^2.0.0",
+    "happy-dom": "^18.0.1",
+    "mdast-util-to-string": "^4.0.0",
+    "remark-parse": "^11.0.0",
+    "typescript": "^5.0.0",
+    "unified": "^11.0.5",
+    "vite": "^5.0.0",
+    "vite-plugin-dts": "^3.0.0",
+    "vitest": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@mediapipe/tasks-vision": "^0.10.20",
+    "@noble/curves": "^2.2.0",
+    "essentia.js": "^0.1.3",
+    "fft.js": "^4.0.4",
+    "sucrase": "^3.35.1"
+  }
+}