@viji-dev/core 0.6.2 → 0.7.4

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 {
@@ -1699,6 +1709,107 @@ export declare type Resolution = {
     height: number;
 };
 
+/**
+ * Structured scene console envelope surfaced via `VijiCore.onSceneConsole`.
+ *
+ * Only artist `console.*` calls reach this listener (the wrapper is injected
+ * as a function argument on the scene IIFE; engine code uses `globalThis.console`
+ * and is not surfaced). The wrapper calls the real `console[level](...args)`
+ * first before forwarding, so DevTools output is preserved.
+ *
+ * Arguments are pre-stringified in the worker with cycle-safe depth-bounded
+ * inspection, a per-argument byte cap (`consoleArgMaxBytes`), and an argument
+ * count cap (`consoleMaxArgsPerCall`). High-cardinality logs are rate-limited
+ * by `consoleMaxUniqueSignaturesPerSecond`.
+ */
+export declare interface SceneConsoleMessage {
+    /** Console method invoked. */
+    level: 'log' | 'info' | 'warn' | 'error';
+    /** Stringified arguments. Each entry is bounded by `consoleArgMaxBytes`. */
+    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. */
+    count: number;
+    /** Millisecond timestamp of the first occurrence of this signature in the current window. */
+    firstSeenAt: number;
+    /** Millisecond timestamp of the most recent occurrence. */
+    lastSeenAt: number;
+    /**
+     * Source location of the `console.*` call site in artist-source coordinates.
+     * Captured via `new Error().stack` inside the wrapper. Absent when stack
+     * frame parsing fails.
+     */
+    sourceLocation?: SceneSourceLocation;
+}
+
+/**
+ * Discriminator for scene runtime errors surfaced via `onSceneRuntimeError`.
+ *
+ * - `SCENE_CODE_ERROR`: thrown during `setSceneCode` parse/eval (native, P5).
+ * - `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).
+ * - `P5_INIT_ERROR`: failure during P5 mode initialization (e.g. missing `render`).
+ * - `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';
+
+/**
+ * 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.
+ *
+ * The host-side `console.error('Scene error:', data)` tee continues to fire
+ * alongside the listener (never silenced based on listener presence).
+ */
+export declare interface SceneRuntimeError {
+    /** Error message, equivalent to `Error.message`. */
+    message: string;
+    /** Raw V8 stack trace, when available. Not resolved to artist-source coordinates. */
+    stack?: string;
+    /**
+     * Attribution: `'scene'` when at least one stack frame originates in the
+     * artist's compiled scene IIFE; `'engine'` otherwise.
+     */
+    source: 'scene' | 'engine';
+    /**
+     * Lifecycle phase: `'init'` before the first successful render frame
+     * completes; `'render'` afterwards.
+     */
+    phase: 'init' | 'render';
+    /** Error code; see `SceneErrorCode`. */
+    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. */
+    count: number;
+    /** Millisecond timestamp of the first occurrence of this signature in the current window. */
+    firstSeenAt: number;
+    /** Millisecond timestamp of the most recent occurrence. */
+    lastSeenAt: number;
+    /**
+     * Source location resolved to artist-source coordinates when available.
+     * Absent when no artist stack frame is found (engine errors), when shader
+     * compile logs lack column info, or when sourcemap resolution fails.
+     */
+    sourceLocation?: SceneSourceLocation;
+}
+
+/**
+ * Resolved source location in artist-source coordinates. `line` is 1-based and
+ * matches the artist's authored TypeScript / GLSL line numbers. `column` is
+ * 1-based when present; absent when sourcemap resolution failed or the source
+ * is GLSL (which doesn't reliably emit column information in compile logs).
+ */
+export declare interface SceneSourceLocation {
+    line: number;
+    column?: number;
+}
+
 /**
  * Per-pixel person/background segmentation mask. Mask dimensions reflect the
  * ML model's output and may differ from the source video frame.
@@ -2267,7 +2378,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.5.7";
+export declare const VERSION = "0.7.4";
 
 /**
  * Real-time video API: drawable frame, dimensions, and the source-side
@@ -2376,35 +2487,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>;
@@ -2633,6 +2782,8 @@ export declare class VijiCore {
     private parameterErrorListeners;
     private capabilitiesChangeListeners;
     private stateImportErrorListeners;
+    private sceneRuntimeErrorListeners;
+    private sceneConsoleListeners;
     private stats;
     constructor(config: VijiCoreConfig);
     /**
@@ -2928,6 +3079,42 @@ export declare class VijiCore {
      */
     onStateImportError(listener: (error: StateImportError) => void): Unsubscribe;
     private fireStateImportError;
+    /**
+     * Listen for scene runtime errors surfaced by the worker. Errors caused by
+     * the artist's scene code (`SCENE_CODE_ERROR`, `RENDER_ERROR`,
+     * `SHADER_COMPILE_ERROR`, `P5_INIT_ERROR`, plus async / unhandled-rejection
+     * paths originating in the scene) are coalesced on the worker side: identical
+     * signatures within `VijiCoreConfig.errorCoalescingWindowMs` (default 1s)
+     * collapse to a single leading-edge listener call plus an optional trailing
+     * rollup with the final `count`.
+     *
+     * The legacy `console.error('Worker error:', data)` host log continues to
+     * fire alongside this listener (tee semantics, never silenced).
+     *
+     * @returns Unsubscribe function. Call to remove the listener.
+     */
+    onSceneRuntimeError(listener: (error: SceneRuntimeError) => void): Unsubscribe;
+    private fireSceneRuntimeError;
+    /**
+     * Listen for `console.*` calls made from the artist's scene code. The
+     * worker injects a wrapped `console` as an additional function-argument
+     * binding to the artist's IIFE; the wrapper calls the real `console[level]`
+     * first (preserving DevTools output) and then forwards a coalesced, bounded
+     * envelope through this listener.
+     *
+     * Coalescing window: `VijiCoreConfig.consoleCoalescingWindowMs` (default 1s).
+     * Argument bounds: `consoleArgMaxBytes` (default 512B per arg),
+     * `consoleMaxArgsPerCall` (default 8 args). Rate cap on distinct signatures:
+     * `consoleMaxUniqueSignaturesPerSecond` (default 32).
+     *
+     * Only the four forwarded levels (`log`, `info`, `warn`, `error`) reach
+     * this listener. Other console methods (`debug`, `trace`, `dir`, `group`,
+     * etc.) pass through to the real console unchanged but are not surfaced.
+     *
+     * @returns Unsubscribe function. Call to remove the listener.
+     */
+    onSceneConsole(listener: (message: SceneConsoleMessage) => void): Unsubscribe;
+    private fireSceneConsole;
     /**
      * Notify parameter change listeners
      */
@@ -3406,6 +3593,34 @@ export declare interface VijiCoreConfig {
     _rh?: number;
     /** Called when the scene is visually live (render loop running, branding applied) but before audio/video/WASM setup completes. */
     onRenderStart?: () => void;
+    /**
+     * Coalescing window in milliseconds for `onSceneRuntimeError` listener. Identical signatures
+     * within the window collapse into a single host-side message with an incremented `count`.
+     * Default: `1000`.
+     */
+    errorCoalescingWindowMs?: number;
+    /**
+     * Coalescing window in milliseconds for `onSceneConsole` listener. Identical signatures
+     * within the window collapse into a single host-side message with an incremented `count`.
+     * Default: `1000`.
+     */
+    consoleCoalescingWindowMs?: number;
+    /**
+     * Per-argument byte cap for `onSceneConsole` payloads. Arguments longer than this are
+     * truncated with a `…[truncated]` marker. Default: `512`.
+     */
+    consoleArgMaxBytes?: number;
+    /**
+     * Maximum arguments per `console.*` call forwarded through `onSceneConsole`. Excess arguments
+     * are dropped. Default: `8`.
+     */
+    consoleMaxArgsPerCall?: number;
+    /**
+     * Rate cap on distinct console signatures forwarded per second. Excess unique signatures
+     * are dropped with a single synthetic "console suppressed: high frequency" envelope per
+     * overflow window. Default: `32`.
+     */
+    consoleMaxUniqueSignaturesPerSecond?: number;
 }
 
 export declare class VijiCoreError extends Error {

package/dist/index.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viji-dev/core",
-  "version": "0.6.2",
+  "version": "0.7.4",
   "description": "Universal execution engine for Viji Creative scenes",
   "type": "module",
   "main": "./dist/index.js",
@@ -51,6 +51,7 @@
     "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",