@viji-dev/core 0.8.1 → 0.8.3

package/dist/index.d.ts

@@ -1256,9 +1256,11 @@ export declare interface FramePerfSample {
     /** 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).
+     * Fence-accurate downstream frame time in ms, or `null` when unavailable.
+     * Always `null` in steady state. Populated only by `runFencedBenchmark()`:
+     * WebGL scenes via `gl.finish()` (GPU drain), 2D-canvas scenes via
+     * `getImageData()` (raster flush). `null` only when there is no drawable
+     * context or readback fails.
      */
     gpuMs: number | null;
     /** Interval since the previous rendered frame (ms). Session-relative under benchmark. */
@@ -1269,6 +1271,16 @@ export declare interface FramePerfSample {
 
 declare interface FrameRateInfo {
     mode: FrameRateMode;
+    /**
+     * Best-effort display refresh rate in Hz, detected once at init by averaging
+     * 60 `requestAnimationFrame` intervals.
+     *
+     * **Not reliable under load** — if the page is already GPU-stressed during
+     * initialization, throttled rAFs inflate the interval and deflate the value
+     * (e.g. 10 Hz on a 60 Hz monitor), and it is never re-measured. rAF cadence
+     * cannot recover the true refresh post-load. **Do not derive performance
+     * thresholds from this** — prefer an absolute FPS target.
+     */
     screenRefreshRate: number;
     effectiveRefreshRate: number;
 }
@@ -2642,7 +2654,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.8.0";
+export declare const VERSION = "0.8.2";
 
 /**
  * Real-time video API: drawable frame, dimensions, and the source-side
@@ -3801,14 +3813,18 @@ export declare class VijiCore {
     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.
+     * fencing each 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.
+     *
+     * The per-frame fence is WebGL `gl.finish()` for shader/WebGL scenes and
+     * `getImageData()` (raster flush) for 2D-canvas scenes, so `gpuMs` is
+     * populated for both (`null` only with no drawable context).
      *
      * Use only on a scene NOT serving as a live compositor source/mixer —
-     * per-frame `gl.finish()` would stutter the mixer output (enforced below).
+     * the per-frame fence 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.
+     * use `cpuMs` + `gpuMs` for cost.
      * `frameCount: 1` is the generic single-frame measurement.
      *
      * @param frameCount - Number of frames to benchmark (>= 1)

package/dist/index.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viji-dev/core",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "description": "Universal execution engine for Viji Creative scenes",
   "type": "module",
   "main": "./dist/index.js",
@@ -48,11 +48,11 @@
     "README.md"
   ],
   "scripts": {
-    "prebuild": "node scripts/prebuild-clean.mjs",
+    "prebuild": "node scripts/prebuild-clean.mjs && node scripts/sync-version.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",
+    "dev": "node scripts/sync-version.mjs && vite build --watch",
     "integration": "vite --config integration-example/vite.config.ts",
     "test": "vitest",
     "test:coverage": "vitest --coverage",