@viji-dev/core 0.8.4 → 0.8.5

package/dist/docs-api.js

@@ -1,7 +1,7 @@
 export const docsApi = {
   "version": "1.1.0",
-  "coreVersion": "0.8.3",
-  "generatedAt": "2026-05-31T14:08:20.861Z",
+  "coreVersion": "0.8.4",
+  "generatedAt": "2026-06-02T11:07:17.944Z",
   "navigation": [
     {
       "id": "getting-started",
@@ -1875,7 +1875,7 @@ export const docsApi = {
         },
         {
           "type": "text",
-          "markdown": "## When to Use `viji.time` vs `viji.deltaTime`\n\n| Use Case | Property | Why |\n|----------|----------|-----|\n| Oscillation at **constant** speed | `viji.time` | Depends on absolute position in time |\n| Hue cycling at constant rate | `viji.time` | Needs a continuous, monotonic input |\n| Oscillation at **parameter-driven** speed | `viji.deltaTime` (accumulator) | Avoids phase jumps when the slider changes |\n| Position accumulation | `viji.deltaTime` | Must advance the same amount per second, regardless of FPS |\n| Physics / velocity | `viji.deltaTime` | Distance = speed × time elapsed |\n| Fading / easing | `viji.deltaTime` | Progress should be per-second, not per-frame |\n| Periodic events | `viji.time` | Trigger at fixed time intervals |\n\n**Rule of thumb:** if the speed multiplier is a **constant**, `viji.time * constant` is fine. If the speed comes from a **parameter** (slider, etc.), accumulate with `viji.deltaTime` to prevent jumps.\n\n### Accumulator Pattern\n\nWhen animation speed is driven by a user parameter, multiplying `viji.time * speed.value` recalculates the entire phase history every frame: changing the slider causes a visible jump. Instead, accumulate the phase incrementally:\n\n```javascript\nconst speed = viji.slider(1, { min: 0.1, max: 5, label: 'Speed' });\nlet phase = 0;\n\nfunction render(viji) {\n  phase += speed.value * viji.deltaTime;\n  const x = Math.cos(phase) * radius;\n}\n```\n\nThe slider now only affects future frames: past phase is preserved, so the animation transitions smoothly.\n\n> [!NOTE]\n> For shaders, use [`@viji-accumulator`](/shader/parameters/accumulator) instead: it performs the same integration (`speed × deltaTime`) on the host side and provides the accumulated value as a uniform.\n\n## `viji.frameCount`\n\nAn integer that starts at 0 and increments by 1 every frame. Useful for alternating patterns, sampling every N frames, or seeding frame-unique randomness:\n\n```javascript\nif (viji.frameCount % 60 === 0) {\n  // runs once per ~60 frames\n}\n```\n\n## `viji.fps`: Target Frame Rate\n\n`viji.fps` is the **target** frame rate based on the host's frame rate mode and screen refresh rate: it is **not** a measured FPS value:\n\n- `frameRateMode: 'full'` → `viji.fps` equals the screen refresh rate (typically 60 or 120)\n- `frameRateMode: 'half'` → `viji.fps` equals half the screen refresh rate (typically 30 or 60)\n\nThis value is stable and does not fluctuate frame-to-frame. It's useful for informational display or calculations that need the intended rate, but **not** for driving animation: use `viji.time` or `viji.deltaTime` instead.\n\n## Frame-Rate Independence\n\n> [!NOTE]\n> Always use `viji.width` and `viji.height` for positioning and sizing, and `viji.deltaTime` for frame-rate-independent animation. Never hardcode pixel values or assume a specific frame rate.\n\nA scene running at 30 FPS should look the same as one running at 120 FPS. The only way to achieve this is to scale all per-frame accumulation by `viji.deltaTime`:\n\n```javascript\n// Bad: moves faster at higher frame rates\nposition += 5;\n\n// Good: moves at 5 units per second regardless of frame rate\nposition += 5 * viji.deltaTime;\n```\n\n## Next Steps\n\n- [Canvas & Context](/native/canvas-context): [`viji.canvas`](/native/canvas-context), [`viji.useContext()`](/native/canvas-context), dimensions\n- [Parameters](/native/parameters): sliders, colors, toggles\n- [P5 Timing](/p5/timing): timing in the P5 renderer\n- [Shader Timing](/shader/timing): `u_time`, `u_deltaTime`, `u_frame`, `u_fps`\n- [API Reference](/native/api-reference): full list of everything available"
+          "markdown": "## When to Use `viji.time` vs `viji.deltaTime`\n\n| Use Case | Property | Why |\n|----------|----------|-----|\n| Oscillation at **constant** speed | `viji.time` | Depends on absolute position in time |\n| Hue cycling at constant rate | `viji.time` | Needs a continuous, monotonic input |\n| Oscillation at **parameter-driven** speed | `viji.deltaTime` (accumulator) | Avoids phase jumps when the slider changes |\n| Position accumulation | `viji.deltaTime` | Must advance the same amount per second, regardless of FPS |\n| Physics / velocity | `viji.deltaTime` | Distance = speed × time elapsed |\n| Fading / easing | `viji.deltaTime` | Progress should be per-second, not per-frame |\n| Periodic events | `viji.time` | Trigger at fixed time intervals |\n\n**Rule of thumb:** if the speed multiplier is a **constant**, `viji.time * constant` is fine. If the speed comes from a **parameter** (slider, etc.), accumulate with `viji.deltaTime` to prevent jumps.\n\n### Accumulator Pattern\n\nWhen animation speed is driven by a user parameter, multiplying `viji.time * speed.value` recalculates the entire phase history every frame: changing the slider causes a visible jump. Instead, accumulate the phase incrementally:\n\n```javascript\nconst speed = viji.slider(1, { min: 0.1, max: 5, label: 'Speed' });\nlet phase = 0;\n\nfunction render(viji) {\n  phase += speed.value * viji.deltaTime;\n  const x = Math.cos(phase) * radius;\n}\n```\n\nThe slider now only affects future frames: past phase is preserved, so the animation transitions smoothly.\n\n> [!NOTE]\n> For shaders, use [`@viji-accumulator`](/shader/parameters/accumulator) instead: it performs the same integration (`speed × deltaTime`) on the host side and provides the accumulated value as a uniform.\n\n## `viji.frameCount`\n\nAn integer that starts at 0 and increments by 1 every frame. Useful for alternating patterns, sampling every N frames, or seeding frame-unique randomness:\n\n```javascript\nif (viji.frameCount % 60 === 0) {\n  // runs once per ~60 frames\n}\n```\n\n## `viji.fps`: Target Frame Rate\n\n`viji.fps` is the **target** frame rate based on the host's frame rate mode and screen refresh rate: it is **not** a measured FPS value:\n\n- `frameRateMode: 'full'` → `viji.fps` equals the screen refresh rate (typically 60 or 120)\n- `frameRateMode: 'half'` → `viji.fps` equals half the screen refresh rate (typically 30 or 60)\n- `frameRateMode: 'quarter'` → `viji.fps` equals a quarter of the screen refresh rate (typically 15 or 30)\n- `frameRateMode: 'eighth'` → `viji.fps` equals an eighth of the screen refresh rate (typically 7.5 or 15)\n\nThis value is stable and does not fluctuate frame-to-frame. It's useful for informational display or calculations that need the intended rate, but **not** for driving animation: use `viji.time` or `viji.deltaTime` instead.\n\n## Frame-Rate Independence\n\n> [!NOTE]\n> Always use `viji.width` and `viji.height` for positioning and sizing, and `viji.deltaTime` for frame-rate-independent animation. Never hardcode pixel values or assume a specific frame rate.\n\nA scene running at 30 FPS should look the same as one running at 120 FPS. The only way to achieve this is to scale all per-frame accumulation by `viji.deltaTime`:\n\n```javascript\n// Bad: moves faster at higher frame rates\nposition += 5;\n\n// Good: moves at 5 units per second regardless of frame rate\nposition += 5 * viji.deltaTime;\n```\n\n## Next Steps\n\n- [Canvas & Context](/native/canvas-context): [`viji.canvas`](/native/canvas-context), [`viji.useContext()`](/native/canvas-context), dimensions\n- [Parameters](/native/parameters): sliders, colors, toggles\n- [P5 Timing](/p5/timing): timing in the P5 renderer\n- [Shader Timing](/shader/timing): `u_time`, `u_deltaTime`, `u_frame`, `u_fps`\n- [API Reference](/native/api-reference): full list of everything available"
         }
       ]
     },
@@ -4708,7 +4708,7 @@ export const docsApi = {
         },
         {
           "type": "text",
-          "markdown": "## When to Use `viji.time` vs `viji.deltaTime`\n\n| Use Case | Property | Why |\n|----------|----------|-----|\n| `p5.sin()` / `p5.cos()` at **constant** speed | `viji.time` | Periodic functions need absolute time |\n| Hue cycling at constant rate | `viji.time` | Continuous monotonic input |\n| Oscillation at **parameter-driven** speed | `viji.deltaTime` (accumulator) | Avoids phase jumps when the slider changes |\n| Position += velocity | `viji.deltaTime` | Distance = speed × elapsed time |\n| Rotation += angular speed | `viji.deltaTime` | Angle increments must be per-second |\n| Opacity fading | `viji.deltaTime` | Fade rate is per-second |\n\n### Accumulator Pattern: Parameter-Driven Speed\n\nWhen animation speed is controlled by a user parameter, do **not** use `viji.time * speed.value`: changing the slider recalculates the full phase history and causes a visible jump. Instead, accumulate incrementally:\n\n```javascript\n// @renderer p5\nconst speed = viji.slider(1, { min: 0.1, max: 5, label: 'Speed' });\nlet phase = 0;\n\nfunction render(viji, p5) {\n  phase += speed.value * viji.deltaTime;\n  p5.rotate(phase);\n}\n```\n\n> [!TIP]\n> `viji.time * constant` is fine when the multiplier never changes at runtime. The accumulator is only needed when speed is a **user-controlled parameter**. See [Best Practices](/getting-started/best-practices) for the full explanation.\n\n## `viji.frameCount` vs `p5.frameCount`\n\nBoth exist but have different origins:\n\n| Property | Source | Starts At |\n|----------|--------|-----------|\n| `viji.frameCount` | Viji runtime | 0 |\n| `p5.frameCount` | P5 internal | 1 |\n\n`viji.frameCount` is the canonical frame counter across all renderers. It increments by 1 every frame and is consistent whether you're in a native, P5, or shader scene. `p5.frameCount` is maintained by P5 internally and may differ by 1. Use `viji.frameCount` for consistency.\n\n## `viji.fps`: Target Frame Rate\n\n`viji.fps` is the **target** frame rate based on the host's configuration, not a measured value:\n\n- `frameRateMode: 'full'` → screen refresh rate (typically 60 or 120)\n- `frameRateMode: 'half'` → half the screen refresh rate (typically 30 or 60)\n\nThis value is stable and does not fluctuate. Don't use it for animation timing: use `viji.time` or `viji.deltaTime` instead.\n\n> [!NOTE]\n> P5's `frameRate()` function is not available in Viji: the host controls the render loop.\n\n## Frame-Rate Independence\n\n> [!NOTE]\n> Always use `viji.width` and `viji.height` for positioning and sizing, and `viji.deltaTime` for frame-rate-independent animation. Never hardcode pixel values or assume a specific frame rate.\n\n```javascript\n// Bad: speed depends on frame rate\nangle += 0.02;\n\n// Good: same visual speed at any frame rate\nangle += 1.2 * viji.deltaTime; // 1.2 radians per second\n```\n\n## Next Steps\n\n- [Canvas & Resolution](/p5/canvas-resolution): [`viji.width`](/p5/canvas-resolution), [`viji.height`](/p5/canvas-resolution), responsive layouts\n- [Scene Structure](/p5/scene-structure): `setup()`, `render()`, lifecycle\n- [Parameters](/p5/parameters): sliders, colors, toggles\n- [Native Timing](/native/timing): timing in the native renderer\n- [Shader Timing](/shader/timing): `u_time`, `u_deltaTime`, `u_frame`, `u_fps`\n- [API Reference](/p5/api-reference): full list of everything available"
+          "markdown": "## When to Use `viji.time` vs `viji.deltaTime`\n\n| Use Case | Property | Why |\n|----------|----------|-----|\n| `p5.sin()` / `p5.cos()` at **constant** speed | `viji.time` | Periodic functions need absolute time |\n| Hue cycling at constant rate | `viji.time` | Continuous monotonic input |\n| Oscillation at **parameter-driven** speed | `viji.deltaTime` (accumulator) | Avoids phase jumps when the slider changes |\n| Position += velocity | `viji.deltaTime` | Distance = speed × elapsed time |\n| Rotation += angular speed | `viji.deltaTime` | Angle increments must be per-second |\n| Opacity fading | `viji.deltaTime` | Fade rate is per-second |\n\n### Accumulator Pattern: Parameter-Driven Speed\n\nWhen animation speed is controlled by a user parameter, do **not** use `viji.time * speed.value`: changing the slider recalculates the full phase history and causes a visible jump. Instead, accumulate incrementally:\n\n```javascript\n// @renderer p5\nconst speed = viji.slider(1, { min: 0.1, max: 5, label: 'Speed' });\nlet phase = 0;\n\nfunction render(viji, p5) {\n  phase += speed.value * viji.deltaTime;\n  p5.rotate(phase);\n}\n```\n\n> [!TIP]\n> `viji.time * constant` is fine when the multiplier never changes at runtime. The accumulator is only needed when speed is a **user-controlled parameter**. See [Best Practices](/getting-started/best-practices) for the full explanation.\n\n## `viji.frameCount` vs `p5.frameCount`\n\nBoth exist but have different origins:\n\n| Property | Source | Starts At |\n|----------|--------|-----------|\n| `viji.frameCount` | Viji runtime | 0 |\n| `p5.frameCount` | P5 internal | 1 |\n\n`viji.frameCount` is the canonical frame counter across all renderers. It increments by 1 every frame and is consistent whether you're in a native, P5, or shader scene. `p5.frameCount` is maintained by P5 internally and may differ by 1. Use `viji.frameCount` for consistency.\n\n## `viji.fps`: Target Frame Rate\n\n`viji.fps` is the **target** frame rate based on the host's configuration, not a measured value:\n\n- `frameRateMode: 'full'` → screen refresh rate (typically 60 or 120)\n- `frameRateMode: 'half'` → half the screen refresh rate (typically 30 or 60)\n- `frameRateMode: 'quarter'` → a quarter of the screen refresh rate (typically 15 or 30)\n- `frameRateMode: 'eighth'` → an eighth of the screen refresh rate (typically 7.5 or 15)\n\nThis value is stable and does not fluctuate. Don't use it for animation timing: use `viji.time` or `viji.deltaTime` instead.\n\n> [!NOTE]\n> P5's `frameRate()` function is not available in Viji: the host controls the render loop.\n\n## Frame-Rate Independence\n\n> [!NOTE]\n> Always use `viji.width` and `viji.height` for positioning and sizing, and `viji.deltaTime` for frame-rate-independent animation. Never hardcode pixel values or assume a specific frame rate.\n\n```javascript\n// Bad: speed depends on frame rate\nangle += 0.02;\n\n// Good: same visual speed at any frame rate\nangle += 1.2 * viji.deltaTime; // 1.2 radians per second\n```\n\n## Next Steps\n\n- [Canvas & Resolution](/p5/canvas-resolution): [`viji.width`](/p5/canvas-resolution), [`viji.height`](/p5/canvas-resolution), responsive layouts\n- [Scene Structure](/p5/scene-structure): `setup()`, `render()`, lifecycle\n- [Parameters](/p5/parameters): sliders, colors, toggles\n- [Native Timing](/native/timing): timing in the native renderer\n- [Shader Timing](/shader/timing): `u_time`, `u_deltaTime`, `u_frame`, `u_fps`\n- [API Reference](/p5/api-reference): full list of everything available"
         }
       ]
     },
@@ -7422,7 +7422,7 @@ export const docsApi = {
         },
         {
           "type": "text",
-          "markdown": "## `u_deltaTime`: Frame Delta\n\n`u_deltaTime` is the time between the current and previous frame. In shaders, it's primarily useful for:\n\n- Display purposes (showing timing info)\n- Custom accumulation in combination with the `backbuffer`\n- Understanding frame rate behavior\n\nFor most shader animation, `u_time` is the right choice because GLSL is stateless: each pixel is computed independently every frame with no per-pixel accumulation.\n\n## `u_frame`: Frame Counter\n\nAn integer that increments by 1 each frame. Useful for:\n\n- Alternating patterns: `mod(float(u_frame), 2.0)`\n- Noise seeding that changes per frame\n- Periodic events: `mod(float(u_frame), 60.0) < 1.0`\n\n## `u_fps`: Target Frame Rate\n\n`u_fps` is the **target** frame rate based on the host configuration, not a measured value:\n\n- `frameRateMode: 'full'` → screen refresh rate (typically 60.0 or 120.0)\n- `frameRateMode: 'half'` → half the screen refresh rate (typically 30.0 or 60.0)\n\nThis value is stable and does not fluctuate. Use it for informational display, not for animation timing.\n\n## Animation Patterns\n\n### Oscillation\n\n```glsl\nfloat pulse = sin(u_time * 3.14159) * 0.5 + 0.5; // 0..1 pulse, period ~2s\nfloat blink = step(0.5, fract(u_time * 2.0));     // on/off blink, 2 Hz\n```\n\n### Smooth Cycling\n\n```glsl\nfloat t = fract(u_time * 0.25);  // 0..1 over 4 seconds, then repeats\nvec3 color = mix(colorA, colorB, t);\n```\n\n### Rotation\n\n```glsl\nfloat angle = u_time * 1.5;\nmat2 rot = mat2(cos(angle), -sin(angle), sin(angle), cos(angle));\nvec2 rotated = rot * uv;\n```\n\n### Speed-Controlled Animation: The Accumulator\n\nWhen you write `u_time * speed`, changing the `speed` slider causes a visible jump because the entire phase is recalculated. The [`@viji-accumulator`](/shader/parameters/accumulator) directive solves this:\n\n```glsl\n// @viji-slider:speed label:\"Speed\" default:1.0 min:0.1 max:5.0\n// @viji-accumulator:phase rate:speed\n\nvoid main() {\n  // Use `phase` instead of `u_time * speed`\n  float wave = sin(phase * 6.28);\n  // ...\n}\n```\n\nThe accumulator adds `speed × deltaTime` to `phase` each frame on the CPU side. Changing `speed` only affects future growth: no backward jumps."
+          "markdown": "## `u_deltaTime`: Frame Delta\n\n`u_deltaTime` is the time between the current and previous frame. In shaders, it's primarily useful for:\n\n- Display purposes (showing timing info)\n- Custom accumulation in combination with the `backbuffer`\n- Understanding frame rate behavior\n\nFor most shader animation, `u_time` is the right choice because GLSL is stateless: each pixel is computed independently every frame with no per-pixel accumulation.\n\n## `u_frame`: Frame Counter\n\nAn integer that increments by 1 each frame. Useful for:\n\n- Alternating patterns: `mod(float(u_frame), 2.0)`\n- Noise seeding that changes per frame\n- Periodic events: `mod(float(u_frame), 60.0) < 1.0`\n\n## `u_fps`: Target Frame Rate\n\n`u_fps` is the **target** frame rate based on the host configuration, not a measured value:\n\n- `frameRateMode: 'full'` → screen refresh rate (typically 60.0 or 120.0)\n- `frameRateMode: 'half'` → half the screen refresh rate (typically 30.0 or 60.0)\n- `frameRateMode: 'quarter'` → a quarter of the screen refresh rate (typically 15.0 or 30.0)\n- `frameRateMode: 'eighth'` → an eighth of the screen refresh rate (typically 7.5 or 15.0)\n\nThis value is stable and does not fluctuate. Use it for informational display, not for animation timing.\n\n## Animation Patterns\n\n### Oscillation\n\n```glsl\nfloat pulse = sin(u_time * 3.14159) * 0.5 + 0.5; // 0..1 pulse, period ~2s\nfloat blink = step(0.5, fract(u_time * 2.0));     // on/off blink, 2 Hz\n```\n\n### Smooth Cycling\n\n```glsl\nfloat t = fract(u_time * 0.25);  // 0..1 over 4 seconds, then repeats\nvec3 color = mix(colorA, colorB, t);\n```\n\n### Rotation\n\n```glsl\nfloat angle = u_time * 1.5;\nmat2 rot = mat2(cos(angle), -sin(angle), sin(angle), cos(angle));\nvec2 rotated = rot * uv;\n```\n\n### Speed-Controlled Animation: The Accumulator\n\nWhen you write `u_time * speed`, changing the `speed` slider causes a visible jump because the entire phase is recalculated. The [`@viji-accumulator`](/shader/parameters/accumulator) directive solves this:\n\n```glsl\n// @viji-slider:speed label:\"Speed\" default:1.0 min:0.1 max:5.0\n// @viji-accumulator:phase rate:speed\n\nvoid main() {\n  // Use `phase` instead of `u_time * speed`\n  float wave = sin(phase * 6.28);\n  // ...\n}\n```\n\nThe accumulator adds `speed × deltaTime` to `phase` each frame on the CPU side. Changing `speed` only affects future growth: no backward jumps."
         },
         {
           "type": "live-example",

package/dist/{essentia-wasm.web-H69T-_AQ.js → essentia-wasm.web-DwSQMYtc.js}

@@ -1,4 +1,4 @@
-import { g as kn } from "./index-DF_IFS3A.js";
+import { g as kn } from "./index-DbnjzNSY.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-H69T-_AQ.js.map
+//# sourceMappingURL=essentia-wasm.web-DwSQMYtc.js.map

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

@@ -536,7 +536,7 @@ class DB {
       }
   }
 }
-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;
+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;
 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-H69T-_AQ.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-DwSQMYtc.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");
@@ -8019,7 +8019,7 @@ class K {
   }
   /**
    * Sets the scene frame rate mode
-   * @param mode - 'full' for every animation frame, 'half' for every second frame
+   * @param mode - render every animation frame (`'full'`), every 2nd (`'half'`), every 4th (`'quarter'`), or every 8th (`'eighth'`)
    */
   async setFrameRate(A) {
     this.validateReady(), this.config.frameRateMode = A, this.workerManager && this.workerManager.postMessage("frame-rate-update", { mode: A }), this.updateFrameRateStats(), this.debugLog(`Scene frame rate set to ${A} (${this.instanceId})`);
@@ -8727,8 +8727,8 @@ class K {
       );
     if (!A.sceneCode || typeof A.sceneCode != "string")
       throw new S("sceneCode must be a non-empty string", "INVALID_CONFIG");
-    if (A.frameRateMode !== void 0 && A.frameRateMode !== "full" && A.frameRateMode !== "half")
-      throw new S('frameRateMode must be either "full" or "half"', "INVALID_CONFIG");
+    if (A.frameRateMode !== void 0 && !["full", "half", "quarter", "eighth"].includes(A.frameRateMode))
+      throw new S('frameRateMode must be one of "full", "half", "quarter", or "eighth"', "INVALID_CONFIG");
   }
   /**
    * Cleans up all resources
@@ -8752,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.3";
+const hI = "0.8.4";
 export {
   yA as A,
   hI as V,
@@ -8760,4 +8760,4 @@ export {
   S as b,
   PB as g
 };
-//# sourceMappingURL=index-DF_IFS3A.js.map
+//# sourceMappingURL=index-DbnjzNSY.js.map

package/dist/index.d.ts

@@ -946,9 +946,10 @@ export declare interface CVActivity {
 declare type CVFeature = 'faceDetection' | 'faceMesh' | 'handTracking' | 'poseDetection' | 'bodySegmentation' | 'emotionDetection';
 
 /**
- * Computer-vision processing rate relative to the scene's render rate.
- * `'full'` runs CV every frame, `'half'` every other frame, `'quarter'` every
- * fourth, `'eighth'` every eighth. Lower rates reduce CPU/GPU cost.
+ * Computer-vision processing rate relative to the input video stream rate.
+ * `'full'` runs CV on every delivered video frame, `'half'` every other frame,
+ * `'quarter'` every fourth, `'eighth'` every eighth. Lower rates reduce CPU/GPU
+ * cost. (Throttles the camera/stream frame cadence, independent of scene FPS.)
  */
 declare type CVFrameRateMode = 'full' | 'half' | 'quarter' | 'eighth';
 
@@ -1286,11 +1287,13 @@ declare interface FrameRateInfo {
 }
 
 /**
- * Render-loop pacing mode. `'full'` runs `render()` on every animation frame
- * (~60 FPS). `'half'` runs every second frame (~30 FPS), saving CPU/GPU on
- * lower-cost scenes.
+ * Render-loop pacing mode. `'full'` runs `render()` on every animation frame,
+ * `'half'` every 2nd frame, `'quarter'` every 4th, `'eighth'` every 8th. Lower
+ * rates save CPU/GPU on lower-cost scenes. The resulting FPS is the screen
+ * refresh rate divided by the mode divisor (1/2/4/8), so on a 60 Hz display:
+ * `'full'` ~60, `'half'` ~30, `'quarter'` ~15, `'eighth'` ~7.5.
  */
-declare type FrameRateMode = 'full' | 'half';
+declare type FrameRateMode = 'full' | 'half' | 'quarter' | 'eighth';
 
 /**
  * One named frequency band reported by the audio analyzer
@@ -2654,7 +2657,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.3";
+export declare const VERSION = "0.8.4";
 
 /**
  * Real-time video API: drawable frame, dimensions, and the source-side
@@ -2870,7 +2873,7 @@ export declare interface VijiAPI {
     deltaTime: number;
     /** Integer frame counter starting at `0` and incrementing by `1` each frame. */
     frameCount: number;
-    /** Target frames-per-second for the host's current frame-rate mode (`60` for `'full'`, `30` for `'half'`). */
+    /** Target frames-per-second for the host's current frame-rate mode (screen refresh rate divided by the mode divisor 1/2/4/8). */
     fps: number;
     /** Real-time analysis of the main audio stream: volume, frequency bands, beat detection, spectral features. Fields are zeroed when no audio source is connected. */
     audio: AudioAPI;
@@ -3447,7 +3450,7 @@ export declare class VijiCore {
     private notifyParameterListeners;
     /**
      * Sets the scene frame rate mode
-     * @param mode - 'full' for every animation frame, 'half' for every second frame
+     * @param mode - render every animation frame (`'full'`), every 2nd (`'half'`), every 4th (`'quarter'`), or every 8th (`'eighth'`)
      */
     setFrameRate(mode: FrameRateMode): Promise<void>;
     /**
@@ -3937,7 +3940,7 @@ export declare interface VijiCoreConfig {
     hostContainer?: HTMLElement;
     /** Artist scene code to execute */
     sceneCode: string;
-    /** Frame rate mode - 'full' for every animation frame, 'half' for every second frame */
+    /** 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 */
     resolution?: number | {

package/dist/index.js

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

package/package.json

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