@viji-dev/core 0.8.6 → 0.8.8

package/dist/docs-api.js

@@ -1,7 +1,7 @@
 export const docsApi = {
   "version": "1.1.0",
-  "coreVersion": "0.8.5",
-  "generatedAt": "2026-06-03T09:18:41.915Z",
+  "coreVersion": "0.8.7",
+  "generatedAt": "2026-06-03T12:10:59.795Z",
   "navigation": [
     {
       "id": "getting-started",

package/dist/{essentia-wasm.web-CaXce3AA.js → essentia-wasm.web-BqymfxZb.js}

@@ -1,4 +1,4 @@
-import { g as kn } from "./index-BQtrhfjg.js";
+import { g as kn } from "./index-DSMvbzzU.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-CaXce3AA.js.map
+//# sourceMappingURL=essentia-wasm.web-BqymfxZb.js.map

package/dist/{index-BQtrhfjg.js → index-DSMvbzzU.js}

@@ -536,7 +536,7 @@ class DB {
       }
   }
 }
-const hB = "" + new URL("assets/viji.worker-CydIeq-k.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-ChptZ-zo.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;
@@ -652,7 +652,10 @@ class kB {
           R(G.data);
         }, this.controlPort.onmessage = this.onControlPortMessageBound;
       }
-      this.postMessage("set-scene-code", { sceneCode: this.sceneCode }), this.isInitialized = !0;
+      this.postMessage("set-scene-code", {
+        sceneCode: this.sceneCode,
+        ...this.init.initialParameters && { initialParameters: this.init.initialParameters }
+      }), this.isInitialized = !0;
     } catch (A) {
       throw A instanceof S && A.code === "INITIALIZATION_CANCELLED" ? A : this.isDestroyed ? new S(
         "Initialization cancelled",
@@ -1520,7 +1523,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-CaXce3AA.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-BqymfxZb.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");
@@ -6941,7 +6944,9 @@ class K {
   isInitializing = !1;
   instanceId;
   screenRefreshRate = 60;
-  // Will be detected
+  // Sensible default (most common rate); refined asynchronously after init
+  refreshRateRafId = null;
+  // Handle for the non-blocking refresh-rate measurement loop
   debugMode = !1;
   // Debug logging control
   /**
@@ -7178,6 +7183,7 @@ class K {
           allowSensors: !!this.deviceSensorManager,
           sc: this.config._sc,
           rh: this.config._rh,
+          ...this.config.initialParameters && { initialParameters: this.config.initialParameters },
           reporterConfig: oI(this.config)
         }
       ), this.setupCommunication(), await this.workerManager.createWorker(), this.isDestroyed)
@@ -7219,11 +7225,7 @@ class K {
         effectiveWidth: A.width,
         effectiveHeight: A.height,
         displayScale: this.iframeManager.getDisplayScale()
-      }), await this.detectScreenRefreshRate(), this.isDestroyed)
-        throw new S("Initialization cancelled", "INITIALIZATION_CANCELLED");
-      if (this.workerManager.postMessage("refresh-rate-update", {
-        screenRefreshRate: this.screenRefreshRate
-      }), this.config.audioStream && await this.setAudioStream(this.config.audioStream), this.isDestroyed)
+      }), this.detectScreenRefreshRate(), this.config.audioStream && await this.setAudioStream(this.config.audioStream), this.isDestroyed)
         throw new S("Initialization cancelled", "INITIALIZATION_CANCELLED");
       for (let B = 0; B < this.audioStreams.length; B++) {
         const I = K.AUDIO_ADDITIONAL_BASE + B;
@@ -8503,19 +8505,30 @@ class K {
     }), this.stats.resolution = B, this.syncFrameSourceQuality(), this.debugLog(`Resolution: ${B.width}x${B.height}`);
   }
   /**
-   * Detects the screen refresh rate
+   * Measures the screen refresh rate over 60 animation frames, off the init
+   * critical path. Runs fire-and-forget: it does NOT gate `ready`, so the host
+   * can control a visibly-rendering core immediately. On completion it pushes
+   * the refined value to the worker (refresh-rate-update) and updates host
+   * stats. Until then both sides use the 60 default. Measured once, never
+   * re-run. Cancelled on `destroy()` via `refreshRateRafId`.
    */
-  async detectScreenRefreshRate() {
-    return new Promise((A) => {
-      let B = 0;
-      const I = performance.now(), Q = () => {
-        if (B++, B === 60) {
-          const g = performance.now() - I;
-          this.screenRefreshRate = Math.round(6e4 / g), this.debugLog("Detected screen refresh rate:", this.screenRefreshRate + "Hz"), A();
-        } else B < 60 && requestAnimationFrame(Q);
-      };
-      requestAnimationFrame(Q);
-    });
+  detectScreenRefreshRate() {
+    let A = 0;
+    const B = performance.now(), I = () => {
+      if (this.isDestroyed) {
+        this.refreshRateRafId = null;
+        return;
+      }
+      if (A++, A === 60) {
+        this.refreshRateRafId = null;
+        const Q = performance.now() - B;
+        if (this.screenRefreshRate = Math.round(6e4 / Q), this.debugLog("Detected screen refresh rate:", this.screenRefreshRate + "Hz"), this.isDestroyed || !this.workerManager) return;
+        this.workerManager.postMessage("refresh-rate-update", {
+          screenRefreshRate: this.screenRefreshRate
+        }), this.stats.frameRate.screenRefreshRate = this.screenRefreshRate;
+      } else A < 60 && (this.refreshRateRafId = requestAnimationFrame(I));
+    };
+    this.refreshRateRafId = requestAnimationFrame(I);
   }
   /**
    * Updates frame rate statistics
@@ -8695,7 +8708,7 @@ class K {
    */
   async destroy() {
     if (!this.isDestroyed) {
-      this.isDestroyed = !0, this.parameterGroups.clear(), this.parameterValues.clear(), this.parameterListeners.clear(), this.parameterDefinedListeners.clear(), this.parameterErrorListeners.clear(), this.capabilitiesChangeListeners.clear(), this.stateImportErrorListeners.clear(), this.sceneRuntimeErrorListeners.clear(), this.sceneConsoleListeners.clear(), this.performanceSnapshotListeners.clear(), this.capabilityTransitionListeners.clear(), this.unlinkEventSource(), this.unlinkFrameSources();
+      this.isDestroyed = !0, this.refreshRateRafId !== null && (cancelAnimationFrame(this.refreshRateRafId), this.refreshRateRafId = null), this.parameterGroups.clear(), this.parameterValues.clear(), this.parameterListeners.clear(), this.parameterDefinedListeners.clear(), this.parameterErrorListeners.clear(), this.capabilitiesChangeListeners.clear(), this.stateImportErrorListeners.clear(), this.sceneRuntimeErrorListeners.clear(), this.sceneConsoleListeners.clear(), this.performanceSnapshotListeners.clear(), this.capabilityTransitionListeners.clear(), this.unlinkEventSource(), this.unlinkFrameSources();
       for (const [A] of this.deviceVideoCoordinators)
         await this.clearDeviceVideo(A);
       this.deviceVideoCoordinators.clear(), this.deviceVideoStreamIndices.clear(), this.deviceSensorManager && (this.deviceSensorManager.destroy(), this.deviceSensorManager = null);
@@ -8754,7 +8767,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.5";
+const hI = "0.8.7";
 export {
   yA as A,
   hI as V,
@@ -8762,4 +8775,4 @@ export {
   S as b,
   PB as g
 };
-//# sourceMappingURL=index-BQtrhfjg.js.map
+//# sourceMappingURL=index-DSMvbzzU.js.map

package/dist/index.d.ts

@@ -1273,14 +1273,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.
+     * Best-effort display refresh rate in Hz, measured once by averaging 60
+     * `requestAnimationFrame` intervals. The measurement runs asynchronously and
+     * does not block `initialize()`, so for the first few seconds after init this
+     * reads the `60` default until the measured value lands.
      *
      * **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.
+     * thresholds from this** — prefer an absolute FPS target or `effectiveRefreshRate`.
      */
     screenRefreshRate: number;
     effectiveRefreshRate: number;
@@ -2657,7 +2659,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.5";
+export declare const VERSION = "0.8.7";
 
 /**
  * Real-time video API: drawable frame, dimensions, and the source-side
@@ -3022,6 +3024,7 @@ export declare class VijiCore {
     private isInitializing;
     private instanceId;
     private screenRefreshRate;
+    private refreshRateRafId;
     private debugMode;
     /**
      * Debug logging helper
@@ -3818,7 +3821,12 @@ export declare class VijiCore {
         height: number;
     }): void;
     /**
-     * Detects the screen refresh rate
+     * Measures the screen refresh rate over 60 animation frames, off the init
+     * critical path. Runs fire-and-forget: it does NOT gate `ready`, so the host
+     * can control a visibly-rendering core immediately. On completion it pushes
+     * the refined value to the worker (refresh-rate-update) and updates host
+     * stats. Until then both sides use the 60 default. Measured once, never
+     * re-run. Cancelled on `destroy()` via `refreshRateRafId`.
      */
     private detectScreenRefreshRate;
     /**
@@ -3954,6 +3962,16 @@ export declare interface VijiCoreConfig {
     hostContainer?: HTMLElement;
     /** Artist scene code to execute */
     sceneCode: string;
+    /**
+     * Parameter values to seed before the first frame, keyed by parameter name.
+     * Applied in the worker right after the scene defines each parameter (at its
+     * default) and before the first render, so the scene paints frame 1 with these
+     * values instead of popping from defaults a round-trip later. Names the scene
+     * does not define are silently ignored; values are validated against each
+     * parameter's definition exactly like {@link VijiCore.setParameter}. File /
+     * Blob / image-bitmap parameters are not seedable (serializable values only).
+     */
+    initialParameters?: Record<string, ParameterValue>;
     /** Frame rate mode - render every frame (`'full'`), every 2nd (`'half'`), every 4th (`'quarter'`), or every 8th (`'eighth'`). */
     frameRateMode?: FrameRateMode;
     /** Resolution: scale (number) or explicit dimensions (object). Required for headless, must be object form */

package/dist/index.js

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

package/package.json

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