@nexart/ui-renderer 0.8.2 → 0.8.3

package/README.md

@@ -1,6 +1,6 @@
 # @nexart/ui-renderer
 
-Version: 0.8.2
+Version: 0.8.3
 
 **Lightweight Preview Runtime for NexArt Protocol**
 
@@ -19,6 +19,22 @@ Version: 0.8.2
 
 ---
 
+## v0.8.3 — Animation Loop Fix
+
+Fixed critical bug where preview only rendered a single frame.
+
+- **RAF unconditionally scheduled**: `requestAnimationFrame(loop)` is now called on every tick
+- **Budget gates draw only**: Frame budget controls whether `draw()` runs, not whether the loop continues
+- **Continuous animation**: Loop runs forever until explicitly stopped
+
+**Animation Loop Invariant (locked for v0.x):**
+```
+RAF schedules → budget checks → draw executes (or skips) → repeat
+Never: budget check → stop loop
+```
+
+---
+
 ## v0.8.2 — Runtime Dimensions Fix
 
 Fixed critical bug where preview scaling affected `width`/`height` inside sketches.
@@ -225,7 +241,7 @@ import { getCapabilities } from '@nexart/ui-renderer';
 
 const caps = getCapabilities();
 // {
-//   version: '0.8.2',
+//   version: '0.8.3',
 //   isCanonical: false,
 //   isArchival: false,
 //   previewBudget: { MAX_FRAMES: 30, MAX_TOTAL_TIME_MS: 500, FRAME_STRIDE: 3 },

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 /**
  * @nexart/ui-renderer
- * Version: 0.8.2
+ * Version: 0.8.3
  *
  * Lightweight Preview Runtime for NexArt Protocol
  *
@@ -46,7 +46,7 @@ export { calculateScaledDimensions, applyScaledDimensions, type ScaledDimensions
 export type { NexArtSystemInput, NexArtSystem, DeclarativeSystemInput, DeclarativeSystem, CodeSystem, NexArtCodeSystem, UnifiedSystemInput, UnifiedSystem, UnifiedElement, BackgroundElement, PrimitiveElement, SketchElement, BackgroundPreset, PrimitiveName, ColorPalette, MotionSpeed, StrokeWeightAuto, LoopConfig, DeclarativeElement, SystemElement, DotsElement, LinesElement, WavesElement, GridElement, FlowFieldElement, OrbitsElement, BackgroundConfig, MotionConfig, PreviewOptions, ValidationResult, } from './types';
 export { AESTHETIC_DEFAULTS, SDK_VERSION as TYPE_SDK_VERSION } from './types';
 export type { Capabilities, PrimitiveCapability, ParameterSpec, } from './capabilities';
-export declare const SDK_VERSION = "0.8.2";
+export declare const SDK_VERSION = "0.8.3";
 export declare const PROTOCOL_VERSION = "0.8";
 export declare const IS_CANONICAL = false;
 export declare const IS_ARCHIVAL = false;

package/dist/index.js

@@ -1,6 +1,6 @@
 /**
  * @nexart/ui-renderer
- * Version: 0.8.2
+ * Version: 0.8.3
  *
  * Lightweight Preview Runtime for NexArt Protocol
  *
@@ -44,7 +44,7 @@ export { PREVIEW_BUDGET, CANVAS_LIMITS, } from './preview/preview-types';
 export { createFrameBudget, canRenderFrame, recordFrame, resetBudget, shouldSkipFrame, } from './preview/frame-budget';
 export { calculateScaledDimensions, applyScaledDimensions, } from './preview/canvas-scaler';
 export { AESTHETIC_DEFAULTS, SDK_VERSION as TYPE_SDK_VERSION } from './types';
-export const SDK_VERSION = '0.8.2';
+export const SDK_VERSION = '0.8.3';
 export const PROTOCOL_VERSION = '0.8';
 export const IS_CANONICAL = false;
 export const IS_ARCHIVAL = false;

package/dist/preview/code-renderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"code-renderer.d.ts","sourceRoot":"","sources":["../../src/preview/code-renderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AA0BjE,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,WAAW,EAAE,KAAK,CAAC;IACnB,UAAU,EAAE,KAAK,CAAC;CACnB;AAwBD,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE,iBAAiB,EACzB,OAAO,GAAE,cAAmB,GAC3B,YAAY,CA0Pd"}
+{"version":3,"file":"code-renderer.d.ts","sourceRoot":"","sources":["../../src/preview/code-renderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AA0BjE,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,WAAW,EAAE,KAAK,CAAC;IACnB,UAAU,EAAE,KAAK,CAAC;CACnB;AAwBD,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE,iBAAiB,EACzB,OAAO,GAAE,cAAmB,GAC3B,YAAY,CAkQd"}

package/dist/preview/code-renderer.js

@@ -173,13 +173,22 @@ export function renderCodeModeSystem(system, canvas, options = {}) {
             }
             resetBudget(budget);
             isRunning = true;
+            // ╔═══════════════════════════════════════════════════════════════════════╗
+            // ║  ANIMATION LOOP INVARIANT — DO NOT CHANGE                             ║
+            // ║                                                                       ║
+            // ║  requestAnimationFrame(loop) MUST be called on EVERY tick.            ║
+            // ║  Budget gates ONLY whether draw() executes, NOT whether loop runs.    ║
+            // ║  Never return before scheduling RAF. Never conditionally schedule.    ║
+            // ╚═══════════════════════════════════════════════════════════════════════╝
             const loop = () => {
+                // ALWAYS schedule next frame first — loop never terminates on its own
+                animationId = requestAnimationFrame(loop);
+                // Early exit checks (after RAF is scheduled)
                 if (!isRunning || isDestroyed)
                     return;
+                // Budget check — skip draw but keep loop alive
                 if (!canRenderFrame(budget)) {
-                    console.log(`[UIRenderer] Budget exhausted: ${budget.exhaustionReason}`);
-                    isRunning = false;
-                    return;
+                    return; // Loop continues, just don't draw
                 }
                 frameCount++;
                 if (!shouldSkipFrame(frameCount)) {
@@ -200,7 +209,6 @@ export function renderCodeModeSystem(system, canvas, options = {}) {
                         console.warn('[UIRenderer] Draw error:', error);
                     }
                 }
-                animationId = requestAnimationFrame(loop);
             };
             animationId = requestAnimationFrame(loop);
         }

package/dist/preview/preview-engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"preview-engine.d.ts","sourceRoot":"","sources":["../../src/preview/preview-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EACxB,KAAK,eAAe,EAErB,MAAM,iBAAiB,CAAC;AA8MzB;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,mBAAmB,GAAG,eAAe,CAEhF;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,mBAAmB,GAAG,mBAAmB,CAKpF;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAKxC"}
+{"version":3,"file":"preview-engine.d.ts","sourceRoot":"","sources":["../../src/preview/preview-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EACxB,KAAK,eAAe,EAErB,MAAM,iBAAiB,CAAC;AAqNzB;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,mBAAmB,GAAG,eAAe,CAEhF;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,mBAAmB,GAAG,mBAAmB,CAKpF;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAKxC"}

package/dist/preview/preview-engine.js

@@ -132,15 +132,23 @@ class PreviewEngine {
         }
         this.scheduleNextFrame();
     }
+    // ╔═══════════════════════════════════════════════════════════════════════╗
+    // ║  ANIMATION LOOP INVARIANT — DO NOT CHANGE                             ║
+    // ║                                                                       ║
+    // ║  requestAnimationFrame MUST be called on EVERY tick.                  ║
+    // ║  Budget gates ONLY whether draw() executes, NOT whether loop runs.    ║
+    // ║  Never return before scheduling RAF. Never conditionally schedule.    ║
+    // ╚═══════════════════════════════════════════════════════════════════════╝
     scheduleNextFrame() {
-        if (!this.running)
-            return;
+        // ALWAYS schedule next frame first — loop never terminates on its own
         this.animationFrameId = requestAnimationFrame(() => {
+            this.scheduleNextFrame();
+            // Early exit checks (after RAF is scheduled)
             if (!this.running)
                 return;
+            // Budget check — skip draw but keep loop alive
             if (!canRenderFrame(this.budget)) {
-                this.running = false;
-                return;
+                return; // Loop continues, just don't draw
             }
             this.internalFrameCount++;
             if (!shouldSkipFrame(this.internalFrameCount)) {
@@ -161,7 +169,6 @@ class PreviewEngine {
                     console.warn('[PreviewEngine] Draw error:', error);
                 }
             }
-            this.scheduleNextFrame();
         });
     }
     stopLoop() {

package/dist/preview/unified-renderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"unified-renderer.d.ts","sourceRoot":"","sources":["../../src/preview/unified-renderer.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAkB,cAAc,EAAoE,MAAM,UAAU,CAAC;AAmBhJ,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,WAAW,EAAE,KAAK,CAAC;IACnB,UAAU,EAAE,KAAK,CAAC;CACnB;AA6ED,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,aAAa,EACrB,MAAM,EAAE,iBAAiB,EACzB,OAAO,GAAE,cAAmB,GAC3B,eAAe,CAqQjB"}
+{"version":3,"file":"unified-renderer.d.ts","sourceRoot":"","sources":["../../src/preview/unified-renderer.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAkB,cAAc,EAAoE,MAAM,UAAU,CAAC;AAmBhJ,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,WAAW,EAAE,KAAK,CAAC;IACnB,UAAU,EAAE,KAAK,CAAC;CACnB;AA6ED,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,aAAa,EACrB,MAAM,EAAE,iBAAiB,EACzB,OAAO,GAAE,cAAmB,GAC3B,eAAe,CA6QjB"}

package/dist/preview/unified-renderer.js

@@ -237,13 +237,22 @@ export function renderUnifiedSystem(system, canvas, options = {}) {
             runSetup(p);
             resetBudget(budget);
             isRunning = true;
+            // ╔═══════════════════════════════════════════════════════════════════════╗
+            // ║  ANIMATION LOOP INVARIANT — DO NOT CHANGE                             ║
+            // ║                                                                       ║
+            // ║  requestAnimationFrame(loop) MUST be called on EVERY tick.            ║
+            // ║  Budget gates ONLY whether draw() executes, NOT whether loop runs.    ║
+            // ║  Never return before scheduling RAF. Never conditionally schedule.    ║
+            // ╚═══════════════════════════════════════════════════════════════════════╝
             const loop = () => {
+                // ALWAYS schedule next frame first — loop never terminates on its own
+                animationId = requestAnimationFrame(loop);
+                // Early exit checks (after RAF is scheduled)
                 if (!isRunning || isDestroyed)
                     return;
+                // Budget check — skip draw but keep loop alive
                 if (!canRenderFrame(budget)) {
-                    console.log(`[UIRenderer] Budget exhausted: ${budget.exhaustionReason}`);
-                    isRunning = false;
-                    return;
+                    return; // Loop continues, just don't draw
                 }
                 frameCount++;
                 if (!shouldSkipFrame(frameCount)) {
@@ -259,7 +268,6 @@ export function renderUnifiedSystem(system, canvas, options = {}) {
                         console.warn('[UIRenderer] Draw error:', error);
                     }
                 }
-                animationId = requestAnimationFrame(loop);
             };
             animationId = requestAnimationFrame(loop);
         }

package/dist/types.d.ts

@@ -1,5 +1,5 @@
 /**
- * @nexart/ui-renderer v0.8.2 - Type Definitions
+ * @nexart/ui-renderer v0.8.3 - Type Definitions
  *
  * Lightweight Preview Runtime for NexArt Protocol.
  * This SDK is non-canonical and for preview only.
@@ -9,7 +9,7 @@
  * - Max total time: 500ms
  * - Max canvas dimension: 900px
  */
-export declare const SDK_VERSION = "0.8.2";
+export declare const SDK_VERSION = "0.8.3";
 export declare const AESTHETIC_DEFAULTS: {
     readonly background: {
         readonly r: 246;

package/dist/types.js

@@ -1,5 +1,5 @@
 /**
- * @nexart/ui-renderer v0.8.2 - Type Definitions
+ * @nexart/ui-renderer v0.8.3 - Type Definitions
  *
  * Lightweight Preview Runtime for NexArt Protocol.
  * This SDK is non-canonical and for preview only.
@@ -9,7 +9,7 @@
  * - Max total time: 500ms
  * - Max canvas dimension: 900px
  */
-export const SDK_VERSION = '0.8.2';
+export const SDK_VERSION = '0.8.3';
 export const AESTHETIC_DEFAULTS = {
     background: { r: 246, g: 245, b: 242 },
     foreground: { r: 45, g: 45, b: 45 },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nexart/ui-renderer",
-  "version": "0.8.2",
+  "version": "0.8.3",
   "description": "Lightweight Preview Runtime for NexArt Protocol. Non-canonical, performance-optimized with budget limits (max 30 frames, 500ms, 900px canvas).",
   "license": "MIT",
   "type": "module",