@viji-dev/core 0.8.2 → 0.8.4

package/dist/{index-Cql_oWX9.js → index-DF_IFS3A.js}

@@ -536,7 +536,7 @@ class DB {
       }
   }
 }
-const hB = "" + new URL("assets/viji.worker-DA2oBrZW.js", import.meta.url).href, RB = new URL("assets/wasm/vision_wasm_internal.js", import.meta.url).href, wB = new URL("assets/wasm/vision_wasm_internal.wasm", import.meta.url).href, sB = new URL("assets/wasm/vision_wasm_nosimd_internal.js", import.meta.url).href, FB = new URL("assets/wasm/vision_wasm_nosimd_internal.wasm", import.meta.url).href;
+const hB = "" + new URL("assets/viji.worker-BQ4vNMJ0.js", import.meta.url).href, RB = new URL("assets/wasm/vision_wasm_internal.js", import.meta.url).href, wB = new URL("assets/wasm/vision_wasm_internal.wasm", import.meta.url).href, sB = new URL("assets/wasm/vision_wasm_nosimd_internal.js", import.meta.url).href, FB = new URL("assets/wasm/vision_wasm_nosimd_internal.wasm", import.meta.url).href;
 class kB {
   constructor(A, B, I) {
     this.iframeManager = A, this.sceneCode = B, this.init = I;
@@ -1520,7 +1520,7 @@ class lB {
     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-CT-b--JV.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-H69T-_AQ.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");
@@ -7051,6 +7051,8 @@ class K {
   performanceSnapshotListeners = /* @__PURE__ */ new Set();
   capabilityTransitionListeners = /* @__PURE__ */ new Set();
   capabilityReportingEnabled = !1;
+  // Render-loop pause state (host-driven; see pauseRenderLoop()).
+  renderLoopPaused = !1;
   constructor(A) {
     this.validateConfig(A), this.instanceId = `viji-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`, this.isHeadless = !A.hostContainer, this.config = {
       ...A,
@@ -7181,7 +7183,7 @@ class K {
         }
       ), this.setupCommunication(), await this.workerManager.createWorker(), this.isDestroyed)
         throw new S("Initialization cancelled", "INITIALIZATION_CANCELLED");
-      this.capabilityReportingEnabled && this.workerManager.postMessage("enable-capability-reporting", { enabled: !0 });
+      this.capabilityReportingEnabled && this.workerManager.postMessage("enable-capability-reporting", { enabled: !0 }), this.renderLoopPaused && this.workerManager.postMessage("set-render-loop-paused", { paused: !0 });
       try {
         this.config.onRenderStart?.();
       } catch (B) {
@@ -8532,16 +8534,53 @@ class K {
       throw new S("IFrame manager not available", "MANAGER_NOT_READY");
     return this.stats;
   }
+  /**
+   * Pauses the scene render loop — stops the worker from rendering. Intended to
+   * be driven from the host on `document.hidden`, so a hidden tab doesn't keep
+   * rasterizing a heavy scene (which otherwise pegs the GPU and causes a freeze
+   * on return).
+   *
+   * Only the rendering stops. The scene clock keeps running on real wall-clock,
+   * and audio analysis, video/audio streams, CV, parameters and all scene state
+   * keep running too — so audio you can still hear is still analyzed. On
+   * {@link resumeRenderLoop}, `viji.time` reflects the **real** elapsed time
+   * (including the hidden duration) and the first frame's `viji.deltaTime` is the
+   * **real** time-away gap. (That gap can be large; the scene sees true time, not
+   * a frozen clock.) Idempotent.
+   *
+   * For a live compositor *source* feeding a visible mixer, do NOT pause it
+   * while its own tab is hidden — it must keep rendering. Pause is per-core and
+   * host-controlled.
+   */
+  pauseRenderLoop() {
+    this.renderLoopPaused || (this.renderLoopPaused = !0, this.workerManager?.postMessage("set-render-loop-paused", { paused: !0 }));
+  }
+  /**
+   * Resumes the scene render loop after {@link pauseRenderLoop} (e.g. on the tab
+   * becoming visible). The scene resumes on real wall-clock time, so the first
+   * frame's `viji.deltaTime` is the elapsed time-away gap. Idempotent.
+   */
+  resumeRenderLoop() {
+    this.renderLoopPaused && (this.renderLoopPaused = !1, this.workerManager?.postMessage("set-render-loop-paused", { paused: !1 }));
+  }
+  /** Whether the render loop is currently paused (see {@link pauseRenderLoop}). */
+  isRenderLoopPaused() {
+    return this.renderLoopPaused;
+  }
   /**
    * 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)
@@ -8713,7 +8752,7 @@ function DI(h) {
     expectedVersion: 1
   } : typeof A.senderTime != "number" ? { code: "invalid-field", details: "senderTime must be a number", field: "senderTime" } : null;
 }
-const hI = "0.8.0";
+const hI = "0.8.3";
 export {
   yA as A,
   hI as V,
@@ -8721,4 +8760,4 @@ export {
   S as b,
   PB as g
 };
-//# sourceMappingURL=index-Cql_oWX9.js.map
+//# sourceMappingURL=index-DF_IFS3A.js.map

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.3";
 
 /**
  * Real-time video API: drawable frame, dimensions, and the source-side
@@ -3055,6 +3067,7 @@ export declare class VijiCore {
     private performanceSnapshotListeners;
     private capabilityTransitionListeners;
     private capabilityReportingEnabled;
+    private renderLoopPaused;
     constructor(config: VijiCoreConfig);
     /**
      * Capture current scene frame
@@ -3799,16 +3812,47 @@ export declare class VijiCore {
      * Gets current performance statistics
      */
     getStats(): PerformanceStats;
+    /**
+     * Pauses the scene render loop — stops the worker from rendering. Intended to
+     * be driven from the host on `document.hidden`, so a hidden tab doesn't keep
+     * rasterizing a heavy scene (which otherwise pegs the GPU and causes a freeze
+     * on return).
+     *
+     * Only the rendering stops. The scene clock keeps running on real wall-clock,
+     * and audio analysis, video/audio streams, CV, parameters and all scene state
+     * keep running too — so audio you can still hear is still analyzed. On
+     * {@link resumeRenderLoop}, `viji.time` reflects the **real** elapsed time
+     * (including the hidden duration) and the first frame's `viji.deltaTime` is the
+     * **real** time-away gap. (That gap can be large; the scene sees true time, not
+     * a frozen clock.) Idempotent.
+     *
+     * For a live compositor *source* feeding a visible mixer, do NOT pause it
+     * while its own tab is hidden — it must keep rendering. Pause is per-core and
+     * host-controlled.
+     */
+    pauseRenderLoop(): void;
+    /**
+     * Resumes the scene render loop after {@link pauseRenderLoop} (e.g. on the tab
+     * becoming visible). The scene resumes on real wall-clock time, so the first
+     * frame's `viji.deltaTime` is the elapsed time-away gap. Idempotent.
+     */
+    resumeRenderLoop(): void;
+    /** Whether the render loop is currently paused (see {@link pauseRenderLoop}). */
+    isRenderLoopPaused(): boolean;
     /**
      * 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-Cql_oWX9.js";
+import { A as a, V as i, a as s, b as e } from "./index-DF_IFS3A.js";
 export {
   a as AudioSystem,
   i as VERSION,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viji-dev/core",
-  "version": "0.8.2",
+  "version": "0.8.4",
   "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",