@nexart/ui-renderer 0.8.7 → 0.9.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 /**
  * @nexart/ui-renderer
- * Version: 0.8.6
+ * Version: 0.9.0
  *
  * Lightweight Preview Runtime for NexArt Protocol
  *
@@ -11,21 +11,15 @@
  * ║  It does not guarantee determinism or protocol compliance.               ║
  * ║                                                                          ║
  * ║  Performance Limits:                                                     ║
- * ║  - Max frames: 30                                                        ║
- * ║  - Max total time: 500ms                                                 ║
+ * ║  - FPS: Native RAF (~60 FPS)                                             ║
  * ║  - Max canvas dimension: 900px                                           ║
- * ║  - Frame stride: render every 3rd frame                                  ║
+ * ║  - Budget: 1800 frames / 5 minutes (configurable)                        ║
  * ║                                                                          ║
- * ║  Use Cases:                                                              ║
- * ║  - Editor live preview                                                   ║
- * ║  - Builder dashboards                                                    ║
- * ║  - Background generative art                                             ║
- * ║  - Static or loop previews                                               ║
- * ║                                                                          ║
- * ║  NOT For:                                                                ║
- * ║  - Minting / export                                                      ║
- * ║  - ByX                                                                   ║
- * ║  - Protocol validation                                                   ║
+ * ║  v0.9.0 Features:                                                        ║
+ * ║  - Budget exceed callbacks + overlay                                     ║
+ * ║  - getPreviewStats() for observability                                   ║
+ * ║  - createPreviewRuntime() as recommended entrypoint                      ║
+ * ║  - toCanonicalRequest() for handoff to @nexart/codemode-sdk              ║
  * ║                                                                          ║
  * ║  For canonical output: use @nexart/codemode-sdk                          ║
  * ╚══════════════════════════════════════════════════════════════════════════╝
@@ -39,16 +33,40 @@ export { compileBackgroundPreset, getPaletteColors } from './presets/backgrounds
 export { compilePrimitive } from './presets/primitives';
 export { wrapSketch, validateSketchSafety } from './presets/sketch-wrapper';
 export { getCapabilities, getPrimitiveTypes, getPrimitivesByCategory, getPrimitiveInfo, isPrimitiveValid, getMotionSources, getBackgroundTextures, } from './capabilities';
-export { createPreviewEngine, renderStaticPreview, stopActivePreview, } from './preview/preview-engine';
-export { PREVIEW_FPS, CANVAS_LIMITS, type RuntimeProfile, type PreviewMode, type PreviewEngineConfig, type PreviewRenderResult, type PreviewRenderer, type FpsThrottleState, } from './preview/preview-types';
+export { createPreviewEngine, renderStaticPreview, stopActivePreview, toCanonicalRequest, } from './preview/preview-engine';
+export { PREVIEW_FPS, PREVIEW_BUDGET, CANVAS_LIMITS, type RuntimeProfile, type PreviewMode, type PreviewEngineConfig, type PreviewRenderResult, type PreviewRenderer, type PreviewStats, type BudgetExceededInfo, type BudgetExceedReason, type BudgetBehavior, type CanonicalRequest, type FpsThrottleState, } from './preview/preview-types';
 export { type FrameBudgetState } from './preview/frame-budget';
 export { createFpsThrottle, shouldRenderFrame, recordFrame, resetThrottle, createFrameBudget, canRenderFrame, resetBudget, shouldSkipFrame, getElapsedMs, } from './preview/frame-budget';
 export { calculateScaledDimensions, applyScaledDimensions, type ScaledDimensions, } from './preview/canvas-scaler';
 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.6";
-export declare const PROTOCOL_VERSION = "0.8";
+/**
+ * createPreviewRuntime - Recommended entrypoint for AI coding agents.
+ *
+ * This is an alias for createPreviewEngine with sensible defaults.
+ * Use this as the primary way to create previews.
+ *
+ * @example
+ * ```typescript
+ * import { createPreviewRuntime } from '@nexart/ui-renderer';
+ *
+ * const runtime = createPreviewRuntime({
+ *   canvas: document.getElementById('canvas'),
+ *   source: 'function draw() { circle(width/2, height/2, 100); }',
+ *   mode: 'loop',
+ *   width: 1950,
+ *   height: 2400,
+ *   onBudgetExceeded: (info) => console.log('Budget exceeded:', info),
+ * });
+ *
+ * runtime.startLoop();
+ * console.log(runtime.getPreviewStats());
+ * ```
+ */
+export { createPreviewEngine as createPreviewRuntime } from './preview/preview-engine';
+export declare const SDK_VERSION = "0.9.0";
+export declare const PROTOCOL_VERSION = "0.9";
 export declare const IS_CANONICAL = false;
 export declare const IS_ARCHIVAL = false;
 export declare const RENDERER = "@nexart/ui-renderer";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AACpH,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAClF,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAC5E,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,uBAAuB,EACvB,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EACL,WAAW,EACX,aAAa,EACb,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,KAAK,gBAAgB,GACtB,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/D,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,WAAW,EACX,aAAa,EAEb,iBAAiB,EACjB,cAAc,EACd,WAAW,EACX,eAAe,EACf,YAAY,GACb,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,yBAAyB,EACzB,qBAAqB,EACrB,KAAK,gBAAgB,GACtB,MAAM,yBAAyB,CAAC;AAEjC,YAAY,EACV,iBAAiB,EACjB,YAAY,EACZ,sBAAsB,EACtB,iBAAiB,EACjB,UAAU,EACV,gBAAgB,EAChB,kBAAkB,EAClB,aAAa,EACb,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACb,gBAAgB,EAChB,aAAa,EACb,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,UAAU,EACV,kBAAkB,EAClB,aAAa,EACb,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,aAAa,EACb,gBAAgB,EAChB,YAAY,EACZ,cAAc,EACd,gBAAgB,GACjB,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,kBAAkB,EAAE,WAAW,IAAI,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAE9E,YAAY,EACV,YAAY,EACZ,mBAAmB,EACnB,aAAa,GACd,MAAM,gBAAgB,CAAC;AAExB,eAAO,MAAM,WAAW,UAAU,CAAC;AACnC,eAAO,MAAM,gBAAgB,QAAQ,CAAC;AACtC,eAAO,MAAM,YAAY,QAAQ,CAAC;AAClC,eAAO,MAAM,WAAW,QAAQ,CAAC;AACjC,eAAO,MAAM,QAAQ,wBAAwB,CAAC;AAC9C,eAAO,MAAM,wBAAwB,QAAQ,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AACpH,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAClF,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAC5E,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,uBAAuB,EACvB,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EACL,WAAW,EACX,cAAc,EACd,aAAa,EACb,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,GACtB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/D,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,WAAW,EACX,aAAa,EACb,iBAAiB,EACjB,cAAc,EACd,WAAW,EACX,eAAe,EACf,YAAY,GACb,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,yBAAyB,EACzB,qBAAqB,EACrB,KAAK,gBAAgB,GACtB,MAAM,yBAAyB,CAAC;AAEjC,YAAY,EACV,iBAAiB,EACjB,YAAY,EACZ,sBAAsB,EACtB,iBAAiB,EACjB,UAAU,EACV,gBAAgB,EAChB,kBAAkB,EAClB,aAAa,EACb,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACb,gBAAgB,EAChB,aAAa,EACb,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,UAAU,EACV,kBAAkB,EAClB,aAAa,EACb,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,aAAa,EACb,gBAAgB,EAChB,YAAY,EACZ,cAAc,EACd,gBAAgB,GACjB,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,kBAAkB,EAAE,WAAW,IAAI,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAE9E,YAAY,EACV,YAAY,EACZ,mBAAmB,EACnB,aAAa,GACd,MAAM,gBAAgB,CAAC;AAMxB;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,EAAE,mBAAmB,IAAI,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAEvF,eAAO,MAAM,WAAW,UAAU,CAAC;AACnC,eAAO,MAAM,gBAAgB,QAAQ,CAAC;AACtC,eAAO,MAAM,YAAY,QAAQ,CAAC;AAClC,eAAO,MAAM,WAAW,QAAQ,CAAC;AACjC,eAAO,MAAM,QAAQ,wBAAwB,CAAC;AAC9C,eAAO,MAAM,wBAAwB,QAAQ,CAAC"}

package/dist/index.js

@@ -1,6 +1,6 @@
 /**
  * @nexart/ui-renderer
- * Version: 0.8.6
+ * Version: 0.9.0
  *
  * Lightweight Preview Runtime for NexArt Protocol
  *
@@ -11,21 +11,15 @@
  * ║  It does not guarantee determinism or protocol compliance.               ║
  * ║                                                                          ║
  * ║  Performance Limits:                                                     ║
- * ║  - Max frames: 30                                                        ║
- * ║  - Max total time: 500ms                                                 ║
+ * ║  - FPS: Native RAF (~60 FPS)                                             ║
  * ║  - Max canvas dimension: 900px                                           ║
- * ║  - Frame stride: render every 3rd frame                                  ║
+ * ║  - Budget: 1800 frames / 5 minutes (configurable)                        ║
  * ║                                                                          ║
- * ║  Use Cases:                                                              ║
- * ║  - Editor live preview                                                   ║
- * ║  - Builder dashboards                                                    ║
- * ║  - Background generative art                                             ║
- * ║  - Static or loop previews                                               ║
- * ║                                                                          ║
- * ║  NOT For:                                                                ║
- * ║  - Minting / export                                                      ║
- * ║  - ByX                                                                   ║
- * ║  - Protocol validation                                                   ║
+ * ║  v0.9.0 Features:                                                        ║
+ * ║  - Budget exceed callbacks + overlay                                     ║
+ * ║  - getPreviewStats() for observability                                   ║
+ * ║  - createPreviewRuntime() as recommended entrypoint                      ║
+ * ║  - toCanonicalRequest() for handoff to @nexart/codemode-sdk              ║
  * ║                                                                          ║
  * ║  For canonical output: use @nexart/codemode-sdk                          ║
  * ╚══════════════════════════════════════════════════════════════════════════╝
@@ -39,15 +33,40 @@ export { compileBackgroundPreset, getPaletteColors } from './presets/backgrounds
 export { compilePrimitive } from './presets/primitives';
 export { wrapSketch, validateSketchSafety } from './presets/sketch-wrapper';
 export { getCapabilities, getPrimitiveTypes, getPrimitivesByCategory, getPrimitiveInfo, isPrimitiveValid, getMotionSources, getBackgroundTextures, } from './capabilities';
-export { createPreviewEngine, renderStaticPreview, stopActivePreview, } from './preview/preview-engine';
-export { PREVIEW_FPS, CANVAS_LIMITS, } from './preview/preview-types';
-export { createFpsThrottle, shouldRenderFrame, recordFrame, resetThrottle, 
-// Deprecated exports for backward compatibility (will be removed in v0.9.0)
-createFrameBudget, canRenderFrame, resetBudget, shouldSkipFrame, getElapsedMs, } from './preview/frame-budget';
+export { createPreviewEngine, renderStaticPreview, stopActivePreview, toCanonicalRequest, } from './preview/preview-engine';
+export { PREVIEW_FPS, PREVIEW_BUDGET, CANVAS_LIMITS, } from './preview/preview-types';
+export { createFpsThrottle, shouldRenderFrame, recordFrame, resetThrottle, createFrameBudget, canRenderFrame, resetBudget, shouldSkipFrame, getElapsedMs, } 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.6';
-export const PROTOCOL_VERSION = '0.8';
+// ============================================================================
+// v0.9.0 RECOMMENDED ENTRYPOINT
+// ============================================================================
+/**
+ * createPreviewRuntime - Recommended entrypoint for AI coding agents.
+ *
+ * This is an alias for createPreviewEngine with sensible defaults.
+ * Use this as the primary way to create previews.
+ *
+ * @example
+ * ```typescript
+ * import { createPreviewRuntime } from '@nexart/ui-renderer';
+ *
+ * const runtime = createPreviewRuntime({
+ *   canvas: document.getElementById('canvas'),
+ *   source: 'function draw() { circle(width/2, height/2, 100); }',
+ *   mode: 'loop',
+ *   width: 1950,
+ *   height: 2400,
+ *   onBudgetExceeded: (info) => console.log('Budget exceeded:', info),
+ * });
+ *
+ * runtime.startLoop();
+ * console.log(runtime.getPreviewStats());
+ * ```
+ */
+export { createPreviewEngine as createPreviewRuntime } from './preview/preview-engine';
+export const SDK_VERSION = '0.9.0';
+export const PROTOCOL_VERSION = '0.9';
 export const IS_CANONICAL = false;
 export const IS_ARCHIVAL = false;
 export const RENDERER = '@nexart/ui-renderer';

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

@@ -1,5 +1,5 @@
 /**
- * @nexart/ui-renderer v0.8.7 - Code Mode Renderer
+ * @nexart/ui-renderer v0.8.8 - Code Mode Renderer
  *
  * ╔══════════════════════════════════════════════════════════════════════════╗
  * ║  PREVIEW RENDERER — LIGHTWEIGHT, NON-AUTHORITATIVE                       ║
@@ -7,7 +7,7 @@
  * ║  This renderer is a preview-only runtime.                                ║
  * ║  It does not guarantee determinism or protocol compliance.               ║
  * ║                                                                          ║
- * ║  Performance: FPS-capped at 8 FPS, canvas max 900px                      ║
+ * ║  Performance: Native requestAnimationFrame (~60 FPS), canvas max 900px   ║
  * ║  Animation: Runs continuously until stop() is called                     ║
  * ║                                                                          ║
  * ║  For minting, export, or validation: use @nexart/codemode-sdk            ║

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;;;;;;;;;;;;;;GAcG;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,CAoTd"}
+{"version":3,"file":"code-renderer.d.ts","sourceRoot":"","sources":["../../src/preview/code-renderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAiBjE,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,CA4Sd"}

package/dist/preview/code-renderer.js

@@ -1,5 +1,5 @@
 /**
- * @nexart/ui-renderer v0.8.7 - Code Mode Renderer
+ * @nexart/ui-renderer v0.8.8 - Code Mode Renderer
  *
  * ╔══════════════════════════════════════════════════════════════════════════╗
  * ║  PREVIEW RENDERER — LIGHTWEIGHT, NON-AUTHORITATIVE                       ║
@@ -7,14 +7,13 @@
  * ║  This renderer is a preview-only runtime.                                ║
  * ║  It does not guarantee determinism or protocol compliance.               ║
  * ║                                                                          ║
- * ║  Performance: FPS-capped at 8 FPS, canvas max 900px                      ║
+ * ║  Performance: Native requestAnimationFrame (~60 FPS), canvas max 900px   ║
  * ║  Animation: Runs continuously until stop() is called                     ║
  * ║                                                                          ║
  * ║  For minting, export, or validation: use @nexart/codemode-sdk            ║
  * ╚══════════════════════════════════════════════════════════════════════════╝
  */
-import { PREVIEW_FPS, CANVAS_LIMITS, } from './preview-types';
-import { createFpsThrottle, shouldRenderFrame, recordFrame, resetThrottle, } from './frame-budget';
+import { CANVAS_LIMITS, } from './preview-types';
 import { calculateScaledDimensions, applyScaledDimensions, reapplyContextScale, clearCanvasIgnoringTransform, } from './canvas-scaler';
 import { createPreviewRuntime } from './preview-runtime';
 const PROTOCOL_VERSION = '1.2.0';
@@ -42,8 +41,8 @@ function normalizeVars(vars) {
     return result;
 }
 export function renderCodeModeSystem(system, canvas, options = {}) {
-    console.log('[UIRenderer] Preview mode → FPS-capped continuous animation');
-    console.log(`[UIRenderer] Target: ${PREVIEW_FPS.TARGET_FPS} FPS, canvas max ${CANVAS_LIMITS.MAX_DIMENSION}px`);
+    console.log('[UIRenderer] Preview mode → native requestAnimationFrame (~60 FPS)');
+    console.log(`[UIRenderer] Canvas max ${CANVAS_LIMITS.MAX_DIMENSION}px`);
     if (activeRendererInstance) {
         activeRendererInstance.destroy();
         activeRendererInstance = null;
@@ -61,7 +60,6 @@ export function renderCodeModeSystem(system, canvas, options = {}) {
     let animationId = null;
     let isRunning = false;
     let isDestroyed = false;
-    const throttle = createFpsThrottle();
     const normalizedVars = normalizeVars(system.vars);
     let runtime = null;
     let setupFn = null;
@@ -217,15 +215,14 @@ export function renderCodeModeSystem(system, canvas, options = {}) {
             if (setupFn) {
                 setupFn();
             }
-            resetThrottle(throttle);
             isRunning = true;
             // ╔═══════════════════════════════════════════════════════════════════════╗
-            // ║  ANIMATION LOOP — CONTINUOUS FPS-CAPPED RENDERING                     ║
+            // ║  ANIMATION LOOP — NATIVE requestAnimationFrame (~60 FPS)              ║
             // ║                                                                       ║
-            // ║  requestAnimationFrame runs continuously until stop() is called.      ║
-            // ║  FPS throttle (8 FPS) prevents excessive CPU usage.                   ║
+            // ║  v0.8.8: Removed FPS throttle for smooth rendering matching NexArt.   ║
+            // ║  Browser handles frame pacing naturally via requestAnimationFrame.    ║
             // ║  Looping uses modulo math: t = (frame % total) / total                ║
-            // ║  Canvas cleared before each draw; skipped frames preserve pixels.     ║
+            // ║  Canvas cleared before each draw() call.                              ║
             // ╚═══════════════════════════════════════════════════════════════════════╝
             const loop = () => {
                 // Schedule next frame first — loop runs until stop()
@@ -233,10 +230,6 @@ export function renderCodeModeSystem(system, canvas, options = {}) {
                 // Exit if stopped or destroyed
                 if (!isRunning || isDestroyed)
                     return;
-                // FPS throttle — skip if not enough time has passed
-                if (!shouldRenderFrame(throttle)) {
-                    return; // Preserve current canvas
-                }
                 frameCount++;
                 // Update runtime timing using modulo for natural looping
                 if (runtime) {
@@ -251,7 +244,6 @@ export function renderCodeModeSystem(system, canvas, options = {}) {
                     if (drawFn)
                         drawFn();
                     drawBadge();
-                    recordFrame(throttle);
                 }
                 catch (error) {
                     console.warn('[UIRenderer] Draw error:', error);

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

@@ -1,5 +1,6 @@
 /**
  * @nexart/ui-renderer - Preview Engine
+ * Version: 0.9.0
  *
  * Lightweight, non-authoritative preview executor.
  * Safe, interruptible, and performant.
@@ -10,21 +11,18 @@
  * ║  This engine is a preview-only runtime.                                  ║
  * ║  It does not guarantee determinism or protocol compliance.               ║
  * ║                                                                          ║
- * ║  Usage:                                                                  ║
- * ║  - Editor live preview                                                   ║
- * ║  - Builder dashboards                                                    ║
- * ║  - Background generative art                                             ║
- * ║  - Static or loop previews                                               ║
+ * ║  v0.9.0 Features:                                                        ║
+ * ║  - Budget exceed callbacks + overlay                                     ║
+ * ║  - getPreviewStats() for observability                                   ║
+ * ║  - toCanonicalRequest() for handoff to @nexart/codemode-sdk              ║
  * ║                                                                          ║
- * ║  NOT for:                                                                ║
- * ║  - Minting / export                                                      ║
- * ║  - ByX                                                                   ║
- * ║  - Protocol validation                                                   ║
+ * ║  Animation runs at native RAF cadence (~60 FPS) per v0.8.8.              ║
+ * ║  Budget system uses frame count + time limits (not FPS throttling).      ║
  * ║                                                                          ║
  * ║  For canonical output: use @nexart/codemode-sdk                          ║
  * ╚══════════════════════════════════════════════════════════════════════════╝
  */
-import { type PreviewEngineConfig, type PreviewRenderResult, type PreviewRenderer } from './preview-types';
+import { type PreviewEngineConfig, type PreviewRenderResult, type PreviewRenderer, type CanonicalRequest } from './preview-types';
 /**
  * Create a preview renderer for the given configuration.
  *
@@ -39,4 +37,9 @@ export declare function renderStaticPreview(config: PreviewEngineConfig): Previe
  * Stop any active preview renderer.
  */
 export declare function stopActivePreview(): void;
+/**
+ * Create a canonical request from preview config.
+ * For handoff to @nexart/codemode-sdk.
+ */
+export declare function toCanonicalRequest(config: PreviewEngineConfig): CanonicalRequest;
 //# sourceMappingURL=preview-engine.d.ts.map

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;AAiNzB;;;;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;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EACxB,KAAK,eAAe,EAIpB,KAAK,gBAAgB,EAEtB,MAAM,iBAAiB,CAAC;AAyVzB;;;;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;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,mBAAmB,GAAG,gBAAgB,CAchF"}

package/dist/preview/preview-engine.js

@@ -1,5 +1,6 @@
 /**
  * @nexart/ui-renderer - Preview Engine
+ * Version: 0.9.0
  *
  * Lightweight, non-authoritative preview executor.
  * Safe, interruptible, and performant.
@@ -10,33 +11,38 @@
  * ║  This engine is a preview-only runtime.                                  ║
  * ║  It does not guarantee determinism or protocol compliance.               ║
  * ║                                                                          ║
- * ║  Usage:                                                                  ║
- * ║  - Editor live preview                                                   ║
- * ║  - Builder dashboards                                                    ║
- * ║  - Background generative art                                             ║
- * ║  - Static or loop previews                                               ║
+ * ║  v0.9.0 Features:                                                        ║
+ * ║  - Budget exceed callbacks + overlay                                     ║
+ * ║  - getPreviewStats() for observability                                   ║
+ * ║  - toCanonicalRequest() for handoff to @nexart/codemode-sdk              ║
  * ║                                                                          ║
- * ║  NOT for:                                                                ║
- * ║  - Minting / export                                                      ║
- * ║  - ByX                                                                   ║
- * ║  - Protocol validation                                                   ║
+ * ║  Animation runs at native RAF cadence (~60 FPS) per v0.8.8.              ║
+ * ║  Budget system uses frame count + time limits (not FPS throttling).      ║
  * ║                                                                          ║
  * ║  For canonical output: use @nexart/codemode-sdk                          ║
  * ╚══════════════════════════════════════════════════════════════════════════╝
  */
-import { createFpsThrottle, shouldRenderFrame, recordFrame, resetThrottle, } from './frame-budget';
+import { PREVIEW_BUDGET, } from './preview-types';
 import { calculateScaledDimensions, applyScaledDimensions, reapplyContextScale, } from './canvas-scaler';
 import { createPreviewRuntime } from './preview-runtime';
+const SDK_VERSION = '0.9.0';
 let activePreviewRenderer = null;
 class PreviewEngine {
+    get previewScale() {
+        return this.scaled?.scaleFactor ?? 1;
+    }
     constructor(config) {
         this.runtime = null;
         this.setupFn = null;
         this.drawFn = null;
         this.animationFrameId = null;
-        this.throttle = createFpsThrottle();
         this.running = false;
         this.internalFrameCount = 0;
+        this.startTimeMs = 0;
+        this.scaled = null;
+        this.currentStride = 1;
+        this.budgetExceededReason = null;
+        this.overlayElement = null;
         this.isCanonical = false;
         this.isArchival = false;
         this.config = config;
@@ -44,20 +50,10 @@ class PreviewEngine {
         this.initialize();
     }
     initialize() {
-        const scaled = calculateScaledDimensions(this.config.width, this.config.height);
-        applyScaledDimensions(this.canvas, scaled);
-        // 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 ?? []);
+        this.scaled = calculateScaledDimensions(this.config.width, this.config.height);
+        applyScaledDimensions(this.canvas, this.scaled);
+        reapplyContextScale(this.canvas, this.scaled);
+        this.runtime = createPreviewRuntime(this.canvas, this.scaled.originalWidth, this.scaled.originalHeight, this.config.seed ?? 12345, this.config.vars ?? []);
         const totalFrames = this.config.totalFrames ?? 120;
         this.runtime.totalFrames = totalFrames;
         try {
@@ -86,8 +82,123 @@ class PreviewEngine {
         const fn = new Function(...globalVars, wrappedSource);
         return () => fn(...globalValues);
     }
+    getPreviewStats() {
+        const elapsed = this.startTimeMs > 0 ? performance.now() - this.startTimeMs : 0;
+        return {
+            mode: 'preview',
+            scale: this.previewScale,
+            semanticWidth: this.scaled?.originalWidth ?? this.config.width,
+            semanticHeight: this.scaled?.originalHeight ?? this.config.height,
+            bufferWidth: this.scaled?.renderWidth ?? this.config.width,
+            bufferHeight: this.scaled?.renderHeight ?? this.config.height,
+            frames: this.internalFrameCount,
+            stride: this.currentStride,
+            totalTimeMs: elapsed,
+            ...(this.budgetExceededReason ? { budgetExceeded: { reason: this.budgetExceededReason } } : {}),
+        };
+    }
+    toCanonicalRequest() {
+        return {
+            seed: this.config.seed ?? 12345,
+            vars: this.config.vars ?? [],
+            code: this.config.source,
+            settings: {
+                width: this.config.width,
+                height: this.config.height,
+                mode: this.config.mode,
+                totalFrames: this.config.totalFrames,
+            },
+            renderer: 'preview',
+            uiRendererVersion: SDK_VERSION,
+        };
+    }
+    showBudgetOverlay(reason) {
+        if (this.overlayElement)
+            return;
+        const showOverlay = this.config.showOverlay ?? (this.config.budgetBehavior === 'stop');
+        if (!showOverlay)
+            return;
+        const overlay = document.createElement('div');
+        overlay.style.cssText = `
+      position: absolute;
+      top: 0;
+      left: 0;
+      right: 0;
+      bottom: 0;
+      background: rgba(0, 0, 0, 0.85);
+      display: flex;
+      flex-direction: column;
+      align-items: center;
+      justify-content: center;
+      color: white;
+      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+      z-index: 1000;
+      pointer-events: none;
+    `;
+        const reasonText = reason === 'frame_limit'
+            ? `Frame limit reached (${this.internalFrameCount} frames)`
+            : `Time limit reached (${Math.round((performance.now() - this.startTimeMs) / 1000)}s)`;
+        overlay.innerHTML = `
+      <div style="font-size: 24px; margin-bottom: 8px;">⚠️ Preview Budget Exceeded</div>
+      <div style="font-size: 14px; opacity: 0.8; margin-bottom: 16px;">${reasonText}</div>
+      <div style="font-size: 12px; opacity: 0.6; max-width: 280px; text-align: center;">
+        Reduce sketch complexity or use @nexart/codemode-sdk for canonical execution.
+      </div>
+    `;
+        const parent = this.canvas.parentElement;
+        if (parent) {
+            parent.style.position = 'relative';
+            parent.appendChild(overlay);
+            this.overlayElement = overlay;
+        }
+    }
+    removeOverlay() {
+        if (this.overlayElement && this.overlayElement.parentElement) {
+            this.overlayElement.parentElement.removeChild(this.overlayElement);
+            this.overlayElement = null;
+        }
+    }
+    handleBudgetExceeded(reason) {
+        if (this.budgetExceededReason)
+            return; // Already exceeded — fire callback only once
+        this.budgetExceededReason = reason;
+        const behavior = this.config.budgetBehavior ?? 'stop';
+        const info = {
+            reason,
+            framesRendered: this.internalFrameCount,
+            totalTimeMs: performance.now() - this.startTimeMs,
+            stride: this.currentStride,
+            scale: this.previewScale,
+        };
+        console.warn(`[PreviewEngine] Budget exceeded: ${reason}`, info);
+        if (this.config.onBudgetExceeded) {
+            this.config.onBudgetExceeded(info);
+        }
+        if (behavior === 'stop') {
+            this.showBudgetOverlay(reason);
+            this.stopLoop();
+        }
+        else if (behavior === 'degrade') {
+            this.currentStride = PREVIEW_BUDGET.DEGRADE_STRIDE;
+        }
+    }
+    checkBudget() {
+        const maxFrames = this.config.maxFrames ?? PREVIEW_BUDGET.MAX_FRAMES;
+        const maxTimeMs = this.config.maxTimeMs ?? PREVIEW_BUDGET.MAX_TOTAL_TIME_MS;
+        const elapsed = performance.now() - this.startTimeMs;
+        if (this.internalFrameCount >= maxFrames) {
+            this.handleBudgetExceeded('frame_limit');
+            return false;
+        }
+        if (elapsed >= maxTimeMs) {
+            this.handleBudgetExceeded('time_limit');
+            return false;
+        }
+        return true;
+    }
     renderStatic() {
         const startTime = performance.now();
+        this.startTimeMs = startTime;
         try {
             if (this.setupFn) {
                 this.setupFn();
@@ -119,8 +230,11 @@ class PreviewEngine {
         }
         activePreviewRenderer = this;
         this.running = true;
-        resetThrottle(this.throttle);
+        this.startTimeMs = performance.now();
         this.internalFrameCount = 0;
+        this.currentStride = 1;
+        this.budgetExceededReason = null;
+        this.removeOverlay();
         try {
             if (this.setupFn) {
                 this.setupFn();
@@ -131,25 +245,31 @@ class PreviewEngine {
         }
         this.scheduleNextFrame();
     }
-    // ╔═══════════════════════════════════════════════════════════════════════╗
-    // ║  ANIMATION LOOP — CONTINUOUS FPS-CAPPED RENDERING                     ║
-    // ║                                                                       ║
-    // ║  requestAnimationFrame runs continuously until stop() is called.      ║
-    // ║  FPS throttle (8 FPS) prevents excessive CPU usage.                   ║
-    // ║  Looping uses modulo math: t = (frame % total) / total                ║
-    // ╚═══════════════════════════════════════════════════════════════════════╝
+    /**
+     * Animation loop — runs at native RAF cadence (~60 FPS).
+     * No FPS throttle per v0.8.8 decision.
+     * Budget system uses frame count and time limits only.
+     */
     scheduleNextFrame() {
-        // Schedule next frame — loop runs until stopLoop()
         this.animationFrameId = requestAnimationFrame(() => {
+            // Always schedule next frame first (RAF continues until stop)
             this.scheduleNextFrame();
             // Exit if stopped
             if (!this.running)
                 return;
-            // FPS throttle — skip if not enough time has passed
-            if (!shouldRenderFrame(this.throttle)) {
-                return; // Preserve current canvas
-            }
             this.internalFrameCount++;
+            // Check budget — fires callback once when exceeded
+            if (!this.checkBudget()) {
+                // If behavior is 'stop', loop already halted by handleBudgetExceeded
+                // If behavior is 'degrade', continue with stride skipping below
+                if (this.config.budgetBehavior !== 'degrade') {
+                    return;
+                }
+            }
+            // Stride skip in degrade mode (render every Nth frame)
+            if (this.currentStride > 1 && this.internalFrameCount % this.currentStride !== 0) {
+                return;
+            }
             // Update runtime timing using modulo for natural looping
             try {
                 if (this.runtime) {
@@ -162,7 +282,6 @@ class PreviewEngine {
                 if (this.drawFn) {
                     this.drawFn();
                 }
-                recordFrame(this.throttle);
             }
             catch (error) {
                 console.warn('[PreviewEngine] Draw error:', error);
@@ -184,6 +303,7 @@ class PreviewEngine {
     }
     destroy() {
         this.stopLoop();
+        this.removeOverlay();
         this.runtime = null;
         this.setupFn = null;
         this.drawFn = null;
@@ -215,3 +335,22 @@ export function stopActivePreview() {
         activePreviewRenderer = null;
     }
 }
+/**
+ * Create a canonical request from preview config.
+ * For handoff to @nexart/codemode-sdk.
+ */
+export function toCanonicalRequest(config) {
+    return {
+        seed: config.seed ?? 12345,
+        vars: config.vars ?? [],
+        code: config.source,
+        settings: {
+            width: config.width,
+            height: config.height,
+            mode: config.mode,
+            totalFrames: config.totalFrames,
+        },
+        renderer: 'preview',
+        uiRendererVersion: SDK_VERSION,
+    };
+}