@nexart/ui-renderer 0.8.0 → 0.8.2

package/README.md

@@ -1,6 +1,6 @@
 # @nexart/ui-renderer
 
-Version: 0.8.0
+Version: 0.8.2
 
 **Lightweight Preview Runtime for NexArt Protocol**
 
@@ -19,6 +19,28 @@ Version: 0.8.0
 
 ---
 
+## v0.8.2 — Runtime Dimensions Fix
+
+Fixed critical bug where preview scaling affected `width`/`height` inside sketches.
+
+- **Runtime uses original dimensions**: `width` and `height` now match Code Mode exactly
+- **Canvas buffer still scaled for performance**: Rendering is fast, semantics are correct
+- **Loop animations work correctly**: Geometry math and timing no longer break
+
+**Key rule enforced:** Preview scaling is a rendering concern, not a semantic one.
+
+---
+
+## v0.8.1 — Canvas Scaling Fix
+
+Fixed canvas zoom/cropping bug caused by resolution downscaling in v0.8.0.
+
+- **Scale Transform Reapplied**: Context scale is now properly restored after canvas resize
+- **Transform-Safe Clear**: `clearRect` now ignores active transforms for correct full-canvas clearing
+- **No API Changes**: All fixes are internal
+
+---
+
 ## v0.8.0 — Lightweight Preview Runtime
 
 This release refactors the UI renderer into a performance-optimized preview runtime.
@@ -203,7 +225,7 @@ import { getCapabilities } from '@nexart/ui-renderer';
 
 const caps = getCapabilities();
 // {
-//   version: '0.8.0',
+//   version: '0.8.2',
 //   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.0
+ * Version: 0.8.2
  *
  * 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.0";
+export declare const SDK_VERSION = "0.8.2";
 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.0
+ * Version: 0.8.2
  *
  * 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.0';
+export const SDK_VERSION = '0.8.2';
 export const PROTOCOL_VERSION = '0.8';
 export const IS_CANONICAL = false;
 export const IS_ARCHIVAL = false;

package/dist/preview/canvas-scaler.d.ts

@@ -10,6 +10,16 @@
  * ║  Max dimension: 900px                                                    ║
  * ║  Preserves aspect ratio                                                  ║
  * ║  Uses CSS scaling for display                                            ║
+ * ╠══════════════════════════════════════════════════════════════════════════╣
+ * ║  ARCHITECTURAL INVARIANT (v0.8.2+):                                      ║
+ * ║                                                                          ║
+ * ║  Scaling is a RENDERING concern, NOT a SEMANTIC one.                     ║
+ * ║                                                                          ║
+ * ║  - Canvas buffer: scaled (renderWidth × renderHeight)                    ║
+ * ║  - Runtime width/height: ALWAYS original protocol dimensions             ║
+ * ║  - Context transform: ctx.scale() maps original → render space           ║
+ * ║                                                                          ║
+ * ║  This ensures sketch math works identically in preview and Code Mode.    ║
  * ╚══════════════════════════════════════════════════════════════════════════╝
  */
 export interface ScaledDimensions {
@@ -46,4 +56,25 @@ export declare function scaleCoordinate(value: number, scaleFactor: number): num
  * This allows sketches to use original coordinates while rendering at scaled resolution.
  */
 export declare function applyScaleTransform(ctx: CanvasRenderingContext2D, scaleFactor: number): void;
+/**
+ * Reapply context scale after canvas resize.
+ *
+ * NOTE:
+ * Canvas resizing resets the 2D context transform.
+ * The UI renderer downsamples the canvas for performance,
+ * so we must reapply the internal scale factor once after resize.
+ * This runtime is preview-only and intentionally non-deterministic.
+ *
+ * @param canvas - The canvas element
+ * @param dimensions - The scaled dimensions object
+ */
+export declare function reapplyContextScale(canvas: HTMLCanvasElement, dimensions: ScaledDimensions): void;
+/**
+ * Clear the canvas ignoring any active transforms.
+ * Ensures full canvas is cleared even when scaled.
+ *
+ * @param ctx - The 2D rendering context
+ * @param canvas - The canvas element (for dimensions)
+ */
+export declare function clearCanvasIgnoringTransform(ctx: CanvasRenderingContext2D, canvas: HTMLCanvasElement): void;
 //# sourceMappingURL=canvas-scaler.d.ts.map

package/dist/preview/canvas-scaler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"canvas-scaler.d.ts","sourceRoot":"","sources":["../../src/preview/canvas-scaler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,MAAM,WAAW,gBAAgB;IAC/B,iCAAiC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,kCAAkC;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,qBAAqB;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,sBAAsB;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,2BAA2B;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,kCAAkC;IAClC,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACb,gBAAgB,CA0BlB;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,iBAAiB,EACzB,UAAU,EAAE,gBAAgB,GAC3B,IAAI,CAWN;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,GAClB,MAAM,CAER;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,wBAAwB,EAC7B,WAAW,EAAE,MAAM,GAClB,IAAI,CAIN"}
+{"version":3,"file":"canvas-scaler.d.ts","sourceRoot":"","sources":["../../src/preview/canvas-scaler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH,MAAM,WAAW,gBAAgB;IAC/B,iCAAiC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,kCAAkC;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,qBAAqB;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,sBAAsB;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,2BAA2B;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,kCAAkC;IAClC,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACb,gBAAgB,CA0BlB;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,iBAAiB,EACzB,UAAU,EAAE,gBAAgB,GAC3B,IAAI,CAWN;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,GAClB,MAAM,CAER;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,wBAAwB,EAC7B,WAAW,EAAE,MAAM,GAClB,IAAI,CAIN;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,iBAAiB,EACzB,UAAU,EAAE,gBAAgB,GAC3B,IAAI,CAaN;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAC1C,GAAG,EAAE,wBAAwB,EAC7B,MAAM,EAAE,iBAAiB,GACxB,IAAI,CAKN"}

package/dist/preview/canvas-scaler.js

@@ -10,6 +10,16 @@
  * ║  Max dimension: 900px                                                    ║
  * ║  Preserves aspect ratio                                                  ║
  * ║  Uses CSS scaling for display                                            ║
+ * ╠══════════════════════════════════════════════════════════════════════════╣
+ * ║  ARCHITECTURAL INVARIANT (v0.8.2+):                                      ║
+ * ║                                                                          ║
+ * ║  Scaling is a RENDERING concern, NOT a SEMANTIC one.                     ║
+ * ║                                                                          ║
+ * ║  - Canvas buffer: scaled (renderWidth × renderHeight)                    ║
+ * ║  - Runtime width/height: ALWAYS original protocol dimensions             ║
+ * ║  - Context transform: ctx.scale() maps original → render space           ║
+ * ║                                                                          ║
+ * ║  This ensures sketch math works identically in preview and Code Mode.    ║
  * ╚══════════════════════════════════════════════════════════════════════════╝
  */
 import { CANVAS_LIMITS } from './preview-types';
@@ -72,3 +82,41 @@ export function applyScaleTransform(ctx, scaleFactor) {
         ctx.scale(scaleFactor, scaleFactor);
     }
 }
+/**
+ * Reapply context scale after canvas resize.
+ *
+ * NOTE:
+ * Canvas resizing resets the 2D context transform.
+ * The UI renderer downsamples the canvas for performance,
+ * so we must reapply the internal scale factor once after resize.
+ * This runtime is preview-only and intentionally non-deterministic.
+ *
+ * @param canvas - The canvas element
+ * @param dimensions - The scaled dimensions object
+ */
+export function reapplyContextScale(canvas, dimensions) {
+    if (!dimensions.wasScaled)
+        return;
+    const ctx = canvas.getContext('2d');
+    if (!ctx)
+        return;
+    // Canvas resize resets transform — must restore it
+    ctx.setTransform(1, 0, 0, 1, 0, 0);
+    // Reapply internal renderer scale (NOT clientWidth-based)
+    // This is calculated from render dimensions, not DOM size
+    const scaleFactor = dimensions.renderWidth / dimensions.originalWidth;
+    ctx.scale(scaleFactor, scaleFactor);
+}
+/**
+ * Clear the canvas ignoring any active transforms.
+ * Ensures full canvas is cleared even when scaled.
+ *
+ * @param ctx - The 2D rendering context
+ * @param canvas - The canvas element (for dimensions)
+ */
+export function clearCanvasIgnoringTransform(ctx, canvas) {
+    ctx.save();
+    ctx.setTransform(1, 0, 0, 1, 0, 0);
+    ctx.clearRect(0, 0, canvas.width, canvas.height);
+    ctx.restore();
+}

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;AAwBjE,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,CA0Od"}
+{"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"}

package/dist/preview/code-renderer.js

@@ -18,7 +18,7 @@
  */
 import { PREVIEW_BUDGET, } from './preview-types';
 import { createFrameBudget, canRenderFrame, recordFrame, resetBudget, shouldSkipFrame, } from './frame-budget';
-import { calculateScaledDimensions, applyScaledDimensions, } from './canvas-scaler';
+import { calculateScaledDimensions, applyScaledDimensions, reapplyContextScale, clearCanvasIgnoringTransform, } from './canvas-scaler';
 import { createPreviewRuntime } from './preview-runtime';
 const PROTOCOL_VERSION = '1.2.0';
 let activeRendererInstance = null;
@@ -57,6 +57,9 @@ export function renderCodeModeSystem(system, canvas, options = {}) {
         console.log(`[UIRenderer] Canvas scaled: ${system.width}x${system.height} → ${scaled.renderWidth}x${scaled.renderHeight}`);
     }
     applyScaledDimensions(canvas, scaled);
+    // NOTE: Canvas resizing resets the 2D context transform.
+    // Reapply scale factor once after resize for correct rendering.
+    reapplyContextScale(canvas, scaled);
     const ctx = canvas.getContext('2d');
     let animationId = null;
     let isRunning = false;
@@ -67,7 +70,21 @@ export function renderCodeModeSystem(system, canvas, options = {}) {
     let setupFn = null;
     let drawFn = null;
     const compileSource = () => {
-        runtime = createPreviewRuntime(canvas, scaled.renderWidth, scaled.renderHeight, system.seed ?? 12345, normalizedVars);
+        // ╔═══════════════════════════════════════════════════════════════════════╗
+        // ║  ARCHITECTURAL INVARIANT — DO NOT CHANGE                              ║
+        // ║                                                                       ║
+        // ║  Runtime width/height MUST always equal protocol dimensions.          ║
+        // ║  DO NOT pass scaled values (renderWidth/renderHeight) here.           ║
+        // ║                                                                       ║
+        // ║  Scaling is a RENDERING concern handled by ctx.scale().               ║
+        // ║  width/height are SEMANTIC values used by sketch math.                ║
+        // ║                                                                       ║
+        // ║  Passing scaled dimensions breaks loop animations and geometry.       ║
+        // ║  This invariant is locked for v0.x — see CHANGELOG v0.8.2.            ║
+        // ╚═══════════════════════════════════════════════════════════════════════╝
+        runtime = createPreviewRuntime(canvas, scaled.originalWidth, // ← Protocol dimension (e.g. 1950)
+        scaled.originalHeight, // ← Protocol dimension (e.g. 2400)
+        system.seed ?? 12345, normalizedVars);
         const totalFrames = system.totalFrames ?? 120;
         runtime.totalFrames = totalFrames;
         try {
@@ -173,7 +190,7 @@ export function renderCodeModeSystem(system, canvas, options = {}) {
                         runtime.tGlobal = runtime.t;
                     }
                     try {
-                        ctx.clearRect(0, 0, scaled.renderWidth, scaled.renderHeight);
+                        clearCanvasIgnoringTransform(ctx, canvas);
                         if (drawFn)
                             drawFn();
                         drawBadge();
@@ -225,7 +242,7 @@ export function renderCodeModeSystem(system, canvas, options = {}) {
     const destroy = () => {
         isDestroyed = true;
         stop();
-        ctx.clearRect(0, 0, scaled.renderWidth, scaled.renderHeight);
+        clearCanvasIgnoringTransform(ctx, canvas);
         runtime = null;
         setupFn = null;
         drawFn = null;

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;AAmMzB;;;;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;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"}

package/dist/preview/preview-engine.js

@@ -25,7 +25,7 @@
  * ╚══════════════════════════════════════════════════════════════════════════╝
  */
 import { createFrameBudget, canRenderFrame, recordFrame, getElapsedMs, resetBudget, shouldSkipFrame, } from './frame-budget';
-import { calculateScaledDimensions, applyScaledDimensions, } from './canvas-scaler';
+import { calculateScaledDimensions, applyScaledDimensions, reapplyContextScale, } from './canvas-scaler';
 import { createPreviewRuntime } from './preview-runtime';
 let activePreviewRenderer = null;
 class PreviewEngine {
@@ -46,7 +46,18 @@ class PreviewEngine {
     initialize() {
         const scaled = calculateScaledDimensions(this.config.width, this.config.height);
         applyScaledDimensions(this.canvas, scaled);
-        this.runtime = createPreviewRuntime(this.canvas, scaled.renderWidth, scaled.renderHeight, this.config.seed ?? 12345, this.config.vars ?? []);
+        // NOTE: Canvas resizing resets the 2D context transform.
+        // Reapply scale factor once after resize for correct rendering.
+        reapplyContextScale(this.canvas, scaled);
+        // ╔═══════════════════════════════════════════════════════════════════════╗
+        // ║  ARCHITECTURAL INVARIANT — DO NOT CHANGE                              ║
+        // ║  Runtime width/height MUST equal protocol dimensions.                 ║
+        // ║  DO NOT pass renderWidth/renderHeight — breaks loop animations.       ║
+        // ║  Scaling is handled by ctx.scale(), not by changing width/height.     ║
+        // ╚═══════════════════════════════════════════════════════════════════════╝
+        this.runtime = createPreviewRuntime(this.canvas, scaled.originalWidth, // ← Protocol dimension
+        scaled.originalHeight, // ← Protocol dimension
+        this.config.seed ?? 12345, this.config.vars ?? []);
         const totalFrames = this.config.totalFrames ?? 120;
         this.runtime.totalFrames = totalFrames;
         try {

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,CAsPjB"}
+{"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"}

package/dist/preview/unified-renderer.js

@@ -7,7 +7,7 @@ import { compileBackgroundPreset, getPaletteColors } from '../presets/background
 import { compilePrimitive } from '../presets/primitives';
 import { wrapSketch, validateSketchSafety } from '../presets/sketch-wrapper';
 import { createPreviewRuntime } from './preview-runtime';
-import { calculateScaledDimensions, applyScaledDimensions } from './canvas-scaler';
+import { calculateScaledDimensions, applyScaledDimensions, reapplyContextScale, clearCanvasIgnoringTransform } from './canvas-scaler';
 import { createFrameBudget, canRenderFrame, recordFrame, resetBudget, shouldSkipFrame } from './frame-budget';
 import { PREVIEW_BUDGET } from './preview-types';
 function validateSketchElement(element) {
@@ -89,6 +89,9 @@ export function renderUnifiedSystem(system, canvas, options = {}) {
         console.log(`[UIRenderer] Canvas scaled: ${system.width}x${system.height} → ${scaled.renderWidth}x${scaled.renderHeight}`);
     }
     applyScaledDimensions(canvas, scaled);
+    // NOTE: Canvas resizing resets the 2D context transform.
+    // Reapply scale factor once after resize for correct rendering.
+    reapplyContextScale(canvas, scaled);
     const ctx = canvas.getContext('2d');
     let animationId = null;
     let isRunning = false;
@@ -222,7 +225,15 @@ export function renderUnifiedSystem(system, canvas, options = {}) {
             return;
         try {
             let frameCount = 0;
-            const p = createPreviewRuntime(canvas, scaled.renderWidth, scaled.renderHeight, system.seed);
+            // ╔═══════════════════════════════════════════════════════════════════════╗
+            // ║  ARCHITECTURAL INVARIANT — DO NOT CHANGE                              ║
+            // ║  Runtime width/height MUST equal protocol dimensions.                 ║
+            // ║  DO NOT pass renderWidth/renderHeight — breaks loop animations.       ║
+            // ║  Scaling is handled by ctx.scale(), not by changing width/height.     ║
+            // ╚═══════════════════════════════════════════════════════════════════════╝
+            const p = createPreviewRuntime(canvas, scaled.originalWidth, // ← Protocol dimension
+            scaled.originalHeight, // ← Protocol dimension
+            system.seed);
             runSetup(p);
             resetBudget(budget);
             isRunning = true;
@@ -279,7 +290,7 @@ export function renderUnifiedSystem(system, canvas, options = {}) {
     const destroy = () => {
         isDestroyed = true;
         stop();
-        ctx.clearRect(0, 0, scaled.renderWidth, scaled.renderHeight);
+        clearCanvasIgnoringTransform(ctx, canvas);
     };
     const renderer = {
         render,

package/dist/types.d.ts

@@ -1,5 +1,5 @@
 /**
- * @nexart/ui-renderer v0.8.0 - Type Definitions
+ * @nexart/ui-renderer v0.8.2 - 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.0";
+export declare const SDK_VERSION = "0.8.2";
 export declare const AESTHETIC_DEFAULTS: {
     readonly background: {
         readonly r: 246;

package/dist/types.js

@@ -1,5 +1,5 @@
 /**
- * @nexart/ui-renderer v0.8.0 - Type Definitions
+ * @nexart/ui-renderer v0.8.2 - 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.0';
+export const SDK_VERSION = '0.8.2';
 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.0",
+  "version": "0.8.2",
   "description": "Lightweight Preview Runtime for NexArt Protocol. Non-canonical, performance-optimized with budget limits (max 30 frames, 500ms, 900px canvas).",
   "license": "MIT",
   "type": "module",