@viji-dev/core 0.7.8 → 0.8.0

package/dist/index.d.ts

@@ -754,6 +754,25 @@ declare interface ButtonParameter {
     category: ParameterCategory;
 }
 
+/**
+ * An immediate edge in a capability's consumed-meaningfully state, delivered
+ * via `onCapabilityTransition`. Fires the instant the bit flips, independent
+ * of the ~1s performance snapshot.
+ */
+export declare interface CapabilityTransition {
+    capability: 'audio' | 'video' | 'mouse' | 'keyboard' | 'pointer' | 'touch' | 'sensors' | 'devices' | 'cv';
+    /** Present when `capability` is `'cv'`. */
+    cvType?: 'faceDetection' | 'faceMesh' | 'emotion' | 'handTracking' | 'poseDetection' | 'segmentation';
+    /** Present when `capability` is `'cv'` — which CV level transitioned. */
+    level?: 'active' | 'meaningful';
+    /** The new state. */
+    active: boolean;
+    /** Engine frame counter at the transition. */
+    frameIndex: number;
+    /** Worker `performance.now()` timestamp at the transition (same clock as {@link FramePerfSample.timestamp}). */
+    timestamp: number;
+}
+
 /**
  * Options accepted by `VijiCore.captureFrame()` for snapshotting the current
  * scene. Controls output format, encoding, and target resolution / aspect.
@@ -906,6 +925,20 @@ declare interface CoreCapabilities {
     hasGeneral: boolean;
 }
 
+/** Frames a capability was true vs false over the report period. */
+export declare interface CountPair {
+    trueCount: number;
+    falseCount: number;
+}
+
+/** Per-CV-feature live activity: `active` = model loaded + first inference completed (cost is being paid); `meaningful` = last result was non-empty. */
+export declare interface CVActivity {
+    /** Feature is running/inferring (model loaded, first inference completed). */
+    active: boolean;
+    /** The most recent inference produced a non-empty result. */
+    meaningful: boolean;
+}
+
 /**
  * Identifier for an individual computer-vision feature pipeline. Returned by
  * `VideoAPI.cv.getActiveFeatures()` and used internally to track state.
@@ -1188,6 +1221,52 @@ export declare interface FaceData {
     blendshapes: FaceBlendshapes | null;
 }
 
+/**
+ * Per-frame "consumed-meaningfully" capability state — what the scene is
+ * actually receiving and using on a given rendered frame. Connection-class
+ * capabilities (audio/video/sensors/devices) reflect `isConnected`;
+ * interaction-class (mouse/keyboard/pointer/touch) reflect active use of the
+ * specific inputs the scene reads; CV reports `{active, meaningful}` per type.
+ */
+export declare interface FrameCapabilities {
+    audio: boolean;
+    video: boolean;
+    mouse: boolean;
+    keyboard: boolean;
+    pointer: boolean;
+    touch: boolean;
+    sensors: boolean;
+    devices: boolean;
+    cv: {
+        faceDetection: CVActivity;
+        faceMesh: CVActivity;
+        emotion: CVActivity;
+        handTracking: CVActivity;
+        poseDetection: CVActivity;
+        segmentation: CVActivity;
+    };
+}
+
+/** One per-frame performance + capability record. */
+export declare interface FramePerfSample {
+    /** Engine frame counter at sample time. */
+    frameIndex: number;
+    /** Worker `performance.now()` timestamp at sample time. */
+    timestamp: number;
+    /** CPU time spent dispatching the render for this frame (ms). */
+    cpuMs: number;
+    /**
+     * GPU time for this frame in ms, or `null` when unavailable. Always `null`
+     * in steady state; populated only by `runFencedBenchmark()` (and `null`
+     * there for 2D-canvas scenes).
+     */
+    gpuMs: number | null;
+    /** Interval since the previous rendered frame (ms). Session-relative under benchmark. */
+    frameIntervalMs: number;
+    /** Consumed-meaningfully capability state for this frame. */
+    capabilities: FrameCapabilities;
+}
+
 declare interface FrameRateInfo {
     mode: FrameRateMode;
     screenRefreshRate: number;
@@ -1382,6 +1461,13 @@ export declare interface KeyboardEventData {
     metaKey: boolean;
 }
 
+/** Min/avg/max of a numeric field over the report period. */
+export declare interface MinAvgMax {
+    min: number;
+    avg: number;
+    max: number;
+}
+
 /**
  * Mouse input state for the current frame: position, individual button states,
  * per-frame movement, scroll wheel, and frame-based press / release events.
@@ -1512,6 +1598,12 @@ export declare interface OnsetSessionEndEvent {
     outcome: 'pattern' | 'cleared';
 }
 
+/**
+ * P5 main-canvas mode. Only meaningful when {@link SceneData.renderer} is
+ * `'p5'`: `'2d'` for the default 2D canvas, `'webgl'` for a WEBGL canvas.
+ */
+export declare type P5CanvasMode = '2d' | 'webgl';
+
 export declare interface ParameterAPI {
     define(groups: ParameterGroup[]): void;
     [key: string]: any;
@@ -1522,7 +1614,7 @@ export declare interface ParameterAPI {
  * is not currently available (e.g., `'audio'` controls hide when no audio
  * source is connected). `'general'` parameters are always visible.
  */
-declare type ParameterCategory = 'audio' | 'video' | 'interaction' | 'general';
+export declare type ParameterCategory = 'audio' | 'video' | 'interaction' | 'general';
 
 export declare interface ParameterConfig {
     min?: number;
@@ -1544,7 +1636,7 @@ export declare interface ParameterConfig {
 }
 
 export declare interface ParameterDefinition {
-    type: 'slider' | 'color' | 'toggle' | 'select' | 'text' | 'number' | 'image' | 'button' | 'coordinate';
+    type: ParameterType;
     defaultValue: ParameterValue;
     label?: string;
     description?: string;
@@ -1563,6 +1655,12 @@ export declare interface ParameterGroup {
     parameters: Record<string, ParameterDefinition>;
 }
 
+/**
+ * The kind of UI control a parameter renders as. Used for the per-type
+ * breakdown in {@link SceneData.parameterCounts}.
+ */
+export declare type ParameterType = 'slider' | 'color' | 'toggle' | 'select' | 'text' | 'number' | 'image' | 'button' | 'coordinate';
+
 export declare type ParameterValue = string | number | boolean | ImageBitmap | CoordinateValue | null;
 
 declare interface PatternInfo {
@@ -1572,14 +1670,9 @@ declare interface PatternInfo {
 }
 
 export declare interface PerformanceStats {
-    frameTime: number;
     resolution: Resolution;
     scale: number;
     frameRate: FrameRateInfo;
-    rendererType: RendererType;
-    memoryUsage?: number;
-    activeStreams?: number;
-    parameterCount?: number;
     cv?: {
         activeFeatures: CVFeature[];
         processingTime: number;
@@ -1587,6 +1680,57 @@ export declare interface PerformanceStats {
         actualFPS: number;
         isProcessing: boolean;
     };
+    /** Per-frame records for the last report period. */
+    frames: FramePerfSample[];
+    /** Min/avg/max of each numeric timing field over the period. */
+    timing: {
+        cpuMs: MinAvgMax;
+        frameIntervalMs: MinAvgMax;
+        gpuMs?: MinAvgMax;
+    };
+    /** Per-capability true/false frame counts over the period. */
+    capabilities: PeriodCapabilityCounts;
+}
+
+/**
+ * Per-capability frame counts over the report period. CV types report
+ * separate `active` and `meaningful` pairs.
+ */
+export declare interface PeriodCapabilityCounts {
+    audio: CountPair;
+    video: CountPair;
+    mouse: CountPair;
+    keyboard: CountPair;
+    pointer: CountPair;
+    touch: CountPair;
+    sensors: CountPair;
+    devices: CountPair;
+    cv: {
+        faceDetection: {
+            active: CountPair;
+            meaningful: CountPair;
+        };
+        faceMesh: {
+            active: CountPair;
+            meaningful: CountPair;
+        };
+        emotion: {
+            active: CountPair;
+            meaningful: CountPair;
+        };
+        handTracking: {
+            active: CountPair;
+            meaningful: CountPair;
+        };
+        poseDetection: {
+            active: CountPair;
+            meaningful: CountPair;
+        };
+        segmentation: {
+            active: CountPair;
+            meaningful: CountPair;
+        };
+    };
 }
 
 /**
@@ -1710,7 +1854,7 @@ declare interface PoseData {
     }[];
 }
 
-declare type RendererType = 'native' | 'p5' | 'shader';
+export declare type RendererType = 'native' | 'p5' | 'shader';
 
 /**
  * Discrete pixel dimensions for a canvas, frame capture, or render target.
@@ -1722,6 +1866,50 @@ export declare type Resolution = {
     height: number;
 };
 
+/**
+ * The set of engine capabilities a scene's code declares it uses, derived by
+ * static analysis of the scene source (no execution). Detection is
+ * **inclusive-biased**: a capability the scene actually uses is never hidden,
+ * but a rarely-ambiguous case may show an extra one. Shader scenes are
+ * detected from built-in uniform usage (exact); native/p5 scenes from
+ * `viji.*` usage tokens.
+ */
+export declare interface SceneCapabilities {
+    /** Scene reads audio analysis (volume, bands, beat, FFT/waveform, or audio streams). */
+    audio: boolean;
+    /** Scene reads video input (camera frame, video streams, or device cameras). */
+    video: boolean;
+    /** Scene reads mouse state. */
+    mouse: boolean;
+    /** Scene reads keyboard state. */
+    keyboard: boolean;
+    /** Scene reads the unified pointer (mouse/touch) state. */
+    pointer: boolean;
+    /** Scene reads multi-touch state. */
+    touch: boolean;
+    /** Scene declares tunable parameters. */
+    parameters: boolean;
+    /** Scene reads internal device motion/orientation sensors (`viji.device`). */
+    sensors: boolean;
+    /** Scene reads external connected devices (`viji.devices`). */
+    devices: boolean;
+    /** Per-feature computer-vision usage. */
+    cv: {
+        /** Scene uses face detection (bounding boxes). */
+        faceDetection: boolean;
+        /** Scene uses face mesh / landmarks / blendshapes. */
+        faceMesh: boolean;
+        /** Scene uses emotion / expression detection. */
+        emotion: boolean;
+        /** Scene uses hand tracking. */
+        handTracking: boolean;
+        /** Scene uses body pose detection. */
+        poseDetection: boolean;
+        /** Scene uses body segmentation. */
+        segmentation: boolean;
+    };
+}
+
 /**
  * Structured scene console envelope surfaced via `VijiCore.onSceneConsole`.
  *
@@ -1770,6 +1958,32 @@ export declare interface SceneConsoleMessage {
     sourceLocation?: SceneSourceLocation;
 }
 
+/**
+ * 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.
+ */
+export declare interface SceneData {
+    /** Detected renderer the scene targets. */
+    renderer: RendererType;
+    /** P5 canvas mode; present only when `renderer` is `'p5'`. */
+    p5CanvasMode?: P5CanvasMode;
+    /** Capabilities the scene's code declares it uses (inclusive-biased). */
+    capabilities: SceneCapabilities;
+    /** Total number of parameters the scene defines. */
+    parameterCount: number;
+    /** Parameter count broken down by control type (every key present, 0 if unused). */
+    parameterCounts: Record<ParameterType, number>;
+    /** Total number of parameter groups the scene defines. */
+    parameterGroupCount: number;
+    /** Parameter count broken down by visibility category (every key present, 0 if unused). */
+    parameterCountsByCategory: Record<ParameterCategory, number>;
+}
+
 /**
  * Discriminator for scene runtime errors surfaced via `onSceneRuntimeError`.
  *
@@ -2428,7 +2642,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.4";
+export declare const VERSION = "0.8.0";
 
 /**
  * Real-time video API: drawable frame, dimensions, and the source-side
@@ -2826,6 +3040,9 @@ export declare class VijiCore {
     private currentInteractionEnabled;
     private parameterGroups;
     private parameterValues;
+    private sceneRenderer;
+    private sceneCapabilities;
+    private sceneP5CanvasMode?;
     private parametersInitialized;
     private parameterListeners;
     private parameterDefinedListeners;
@@ -2835,6 +3052,9 @@ export declare class VijiCore {
     private sceneRuntimeErrorListeners;
     private sceneConsoleListeners;
     private stats;
+    private performanceSnapshotListeners;
+    private capabilityTransitionListeners;
+    private capabilityReportingEnabled;
     constructor(config: VijiCoreConfig);
     /**
      * Capture current scene frame
@@ -2984,6 +3204,21 @@ export declare class VijiCore {
      * Get current core capabilities (what's currently active)
      */
     getCapabilities(): CoreCapabilities;
+    /**
+     * 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
+     * registered its parameters.
+     *
+     * Distinct from {@link getCapabilities}, which reports what the *host*
+     * currently provides (connected streams, interaction). This reports what the
+     * *scene's code* declares it uses.
+     *
+     * @returns The scene's static metadata
+     */
+    getSceneData(): SceneData;
     /**
      * Inject mouse event (for headless cores or event forwarding)
      */
@@ -3165,6 +3400,34 @@ export declare class VijiCore {
      */
     onSceneConsole(listener: (message: SceneConsoleMessage) => void): Unsubscribe;
     private fireSceneConsole;
+    /**
+     * Subscribe to the ~1s performance + capability snapshot. Each call delivers
+     * the latest {@link PerformanceStats} (per-frame `frames`, `timing`
+     * aggregates, and period `capabilities` counts). Attaching a listener enables
+     * worker-side reporting; the last listener detaching disables it.
+     *
+     * @param listener - Called on each snapshot with the current stats
+     * @returns Unsubscribe function
+     */
+    onPerformanceSnapshot(listener: (stats: PerformanceStats) => void): Unsubscribe;
+    private firePerformanceSnapshot;
+    /**
+     * Subscribe to immediate consumed-meaningfully capability transitions (a
+     * capability starting/stopping providing data the scene uses). Fires the
+     * instant the edge occurs, independent of the ~1s snapshot. Attaching a
+     * listener enables worker-side reporting.
+     *
+     * @param listener - Called on each transition
+     * @returns Unsubscribe function
+     */
+    onCapabilityTransition(listener: (transition: CapabilityTransition) => void): Unsubscribe;
+    private fireCapabilityTransition;
+    /**
+     * Enable/disable worker-side capability + perf reporting based on whether any
+     * perf listener is attached. Idempotent; safe before the worker is ready
+     * (re-synced after `createWorker()` in `initialize()`).
+     */
+    private updateCapabilityReporting;
     /**
      * Notify parameter change listeners
      */
@@ -3536,6 +3799,22 @@ export declare class VijiCore {
      * Gets current performance statistics
      */
     getStats(): PerformanceStats;
+    /**
+     * Runs an on-demand fenced benchmark: the worker renders `frameCount` frames,
+     * fencing each with `gl.finish()` to capture fence-accurate CPU + GPU time
+     * per frame, and resolves with the collected samples. The scene advances
+     * normally; steady-state perf reporting is suppressed for the run.
+     *
+     * Use only on a scene NOT serving as a live compositor source/mixer —
+     * per-frame `gl.finish()` would stutter the mixer output (enforced below).
+     * In-session `frameIntervalMs` includes the fence stall (session-relative);
+     * use `cpuMs` + `gpuMs` for cost. `gpuMs` is `null` for 2D-canvas scenes.
+     * `frameCount: 1` is the generic single-frame measurement.
+     *
+     * @param frameCount - Number of frames to benchmark (>= 1)
+     * @returns The per-frame fenced samples
+     */
+    runFencedBenchmark(frameCount: number): Promise<FramePerfSample[]>;
     /**
      * Register a new external device
      * @param device Device metadata (id and name)

package/dist/index.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viji-dev/core",
-  "version": "0.7.8",
+  "version": "0.8.0",
   "description": "Universal execution engine for Viji Creative scenes",
   "type": "module",
   "main": "./dist/index.js",