@nexart/ui-renderer 0.8.2 → 0.8.5

package/README.md

@@ -1,6 +1,6 @@
 # @nexart/ui-renderer
 
-Version: 0.8.2
+Version: 0.8.5
 
 **Lightweight Preview Runtime for NexArt Protocol**
 
@@ -19,6 +19,50 @@ Version: 0.8.2
 
 ---
 
+## v0.8.5 — Correct Animation Loop Semantics
+
+Fixed animation loop to use proper soft-gating without resets.
+
+- **No resets inside loop**: Budget and frameCount are never reset mid-animation
+- **Soft budget gating**: Budget exhaustion skips draw(), preserving last frame
+- **Modulo-based looping**: `t = (frameCount % totalFrames) / totalFrames` for natural animation cycles
+- **Canvas preservation**: Skipped frames keep current pixels, no black flashes
+
+**Correct Pattern:**
+```javascript
+function loop() {
+  requestAnimationFrame(loop);
+  
+  if (!budget.canRenderFrame()) return;  // Preserve pixels
+  
+  runtime.draw();  // Only changes canvas here
+  budget.recordFrame();
+}
+```
+
+**Behavior:**
+- Renders up to 30 frames (budget limit)
+- After budget exhausted: RAF continues, draw() skipped, last frame stays visible
+- Restart via `stop()` → `start()` to reset and continue
+
+---
+
+## 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 +269,7 @@ import { getCapabilities } from '@nexart/ui-renderer';
 
 const caps = getCapabilities();
 // {
-//   version: '0.8.2',
+//   version: '0.8.5',
 //   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.5
  *
  * 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.5";
 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.5
  *
  * 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.5';
 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,CAyQd"}

package/dist/preview/code-renderer.js

@@ -173,34 +173,48 @@ 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 loop continuation.    ║
+            // ║  Never reset frameCount or budget inside the loop.                    ║
+            // ║  Canvas only changes when draw() runs — skipped frames keep pixels.   ║
+            // ║  Looping uses modulo math (t = frame % total), not counter resets.    ║
+            // ╚═══════════════════════════════════════════════════════════════════════╝
             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 — if exhausted, skip draw but keep last frame visible
                 if (!canRenderFrame(budget)) {
-                    console.log(`[UIRenderer] Budget exhausted: ${budget.exhaustionReason}`);
-                    isRunning = false;
-                    return;
+                    return; // Preserve current canvas, no clear, no reset
                 }
                 frameCount++;
-                if (!shouldSkipFrame(frameCount)) {
-                    if (runtime) {
-                        runtime.frameCount = frameCount;
-                        runtime.t = (frameCount % totalFrames) / totalFrames;
-                        runtime.time = runtime.t;
-                        runtime.tGlobal = runtime.t;
-                    }
-                    try {
-                        clearCanvasIgnoringTransform(ctx, canvas);
-                        if (drawFn)
-                            drawFn();
-                        drawBadge();
-                        recordFrame(budget);
-                    }
-                    catch (error) {
-                        console.warn('[UIRenderer] Draw error:', error);
-                    }
+                // Frame stride check — skip some frames for performance
+                if (shouldSkipFrame(frameCount)) {
+                    return; // Skip but don't clear — preserve last drawn frame
+                }
+                // Update runtime timing using modulo for natural looping
+                if (runtime) {
+                    runtime.frameCount = frameCount;
+                    runtime.t = (frameCount % totalFrames) / totalFrames;
+                    runtime.time = runtime.t;
+                    runtime.tGlobal = runtime.t;
+                }
+                try {
+                    // Clear canvas and draw (only when actually rendering)
+                    clearCanvasIgnoringTransform(ctx, canvas);
+                    if (drawFn)
+                        drawFn();
+                    drawBadge();
+                    recordFrame(budget);
+                }
+                catch (error) {
+                    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;AA2NzB;;;;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,36 +132,48 @@ class PreviewEngine {
         }
         this.scheduleNextFrame();
     }
+    // ╔═══════════════════════════════════════════════════════════════════════╗
+    // ║  ANIMATION LOOP INVARIANT — DO NOT CHANGE                             ║
+    // ║                                                                       ║
+    // ║  requestAnimationFrame MUST be called on EVERY tick.                  ║
+    // ║  Budget gates ONLY whether draw() executes, NOT loop continuation.    ║
+    // ║  Never reset frameCount or budget inside the loop.                    ║
+    // ║  Canvas only changes when draw() runs — skipped frames keep pixels.   ║
+    // ║  Looping uses modulo math (t = frame % total), not counter resets.    ║
+    // ╚═══════════════════════════════════════════════════════════════════════╝
     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 — if exhausted, skip draw but keep last frame visible
             if (!canRenderFrame(this.budget)) {
-                this.running = false;
-                return;
+                return; // Preserve current canvas, no clear, no reset
             }
             this.internalFrameCount++;
-            if (!shouldSkipFrame(this.internalFrameCount)) {
-                try {
-                    if (this.runtime) {
-                        this.runtime.frameCount = this.internalFrameCount;
-                        const totalFrames = this.config.totalFrames ?? 120;
-                        this.runtime.t = this.internalFrameCount / totalFrames;
-                        this.runtime.time = this.runtime.t;
-                        this.runtime.tGlobal = this.runtime.t;
-                    }
-                    if (this.drawFn) {
-                        this.drawFn();
-                    }
-                    recordFrame(this.budget);
+            // Frame stride check — skip some frames for performance
+            if (shouldSkipFrame(this.internalFrameCount)) {
+                return; // Skip but don't clear — preserve last drawn frame
+            }
+            // Update runtime timing using modulo for natural looping
+            try {
+                if (this.runtime) {
+                    this.runtime.frameCount = this.internalFrameCount;
+                    const totalFrames = this.config.totalFrames ?? 120;
+                    this.runtime.t = (this.internalFrameCount % totalFrames) / totalFrames;
+                    this.runtime.time = this.runtime.t;
+                    this.runtime.tGlobal = this.runtime.t;
                 }
-                catch (error) {
-                    console.warn('[PreviewEngine] Draw error:', error);
+                if (this.drawFn) {
+                    this.drawFn();
                 }
+                recordFrame(this.budget);
+            }
+            catch (error) {
+                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,CAmRjB"}

package/dist/preview/unified-renderer.js

@@ -237,29 +237,42 @@ 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 loop continuation.    ║
+            // ║  Never reset frameCount or budget inside the loop.                    ║
+            // ║  Canvas only changes when draw() runs — skipped frames keep pixels.   ║
+            // ║  Looping uses modulo math (t = frame % total), not counter resets.    ║
+            // ╚═══════════════════════════════════════════════════════════════════════╝
             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 — if exhausted, skip draw but keep last frame visible
                 if (!canRenderFrame(budget)) {
-                    console.log(`[UIRenderer] Budget exhausted: ${budget.exhaustionReason}`);
-                    isRunning = false;
-                    return;
+                    return; // Preserve current canvas, no clear, no reset
                 }
                 frameCount++;
-                if (!shouldSkipFrame(frameCount)) {
-                    const t = (frameCount % totalFrames) / totalFrames;
-                    p.randomSeed(system.seed);
-                    p.noiseSeed(system.seed);
-                    try {
-                        runDraw(p, frameCount, t);
-                        drawBadge();
-                        recordFrame(budget);
-                    }
-                    catch (error) {
-                        console.warn('[UIRenderer] Draw error:', error);
-                    }
+                // Frame stride check — skip some frames for performance
+                if (shouldSkipFrame(frameCount)) {
+                    return; // Skip but don't clear — preserve last drawn frame
+                }
+                // Calculate t using modulo for natural looping
+                const t = (frameCount % totalFrames) / totalFrames;
+                p.randomSeed(system.seed);
+                p.noiseSeed(system.seed);
+                try {
+                    runDraw(p, frameCount, t);
+                    drawBadge();
+                    recordFrame(budget);
+                }
+                catch (error) {
+                    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.5 - 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.5";
 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.5 - 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.5';
 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.5",
   "description": "Lightweight Preview Runtime for NexArt Protocol. Non-canonical, performance-optimized with budget limits (max 30 frames, 500ms, 900px canvas).",
   "license": "MIT",
   "type": "module",