@nexart/ui-renderer 0.8.8 → 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/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,
+    };
+}

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

@@ -1,5 +1,6 @@
 /**
  * @nexart/ui-renderer - Preview Runtime Types
+ * Version: 0.9.0
  *
  * ╔══════════════════════════════════════════════════════════════════════════╗
  * ║  PREVIEW RUNTIME — NON-AUTHORITATIVE                                     ║
@@ -35,12 +36,42 @@ export declare const CANVAS_LIMITS: {
     /** Minimum dimension */
     readonly MIN_DIMENSION: 100;
 };
+/**
+ * Preview budget limits (v0.9.0)
+ * Enforced optionally to prevent runaway previews.
+ */
+export declare const PREVIEW_BUDGET: {
+    /** Maximum frames before budget exceeded (default: 1800) */
+    readonly MAX_FRAMES: 1800;
+    /** Maximum execution time in ms (default: 5 minutes) */
+    readonly MAX_TOTAL_TIME_MS: 300000;
+    /** Default stride when degrading (skip every N frames) */
+    readonly DEGRADE_STRIDE: 2;
+};
 /**
  * Preview mode options
  */
 export type PreviewMode = 'static' | 'loop';
 /**
- * Preview engine configuration
+ * Budget exceed reason
+ */
+export type BudgetExceedReason = 'frame_limit' | 'time_limit';
+/**
+ * Budget exceeded info (passed to callbacks)
+ */
+export interface BudgetExceededInfo {
+    reason: BudgetExceedReason;
+    framesRendered: number;
+    totalTimeMs: number;
+    stride: number;
+    scale: number;
+}
+/**
+ * Budget behavior options
+ */
+export type BudgetBehavior = 'degrade' | 'stop';
+/**
+ * Preview engine configuration (v0.9.0)
  */
 export interface PreviewEngineConfig {
     /** Canvas element to render to */
@@ -59,6 +90,34 @@ export interface PreviewEngineConfig {
     vars?: number[];
     /** Total frames for loop mode (for t calculation) */
     totalFrames?: number;
+    /** Callback when budget is exceeded */
+    onBudgetExceeded?: (info: BudgetExceededInfo) => void;
+    /** Behavior when budget exceeded: 'degrade' (skip frames) or 'stop' (halt + overlay) */
+    budgetBehavior?: BudgetBehavior;
+    /** Show overlay when budget exceeded (default: true for 'stop' behavior) */
+    showOverlay?: boolean;
+    /** Maximum frames before budget exceeded (default: 1800) */
+    maxFrames?: number;
+    /** Maximum execution time in ms (default: 300000) */
+    maxTimeMs?: number;
+}
+/**
+ * Preview stats (v0.9.0)
+ * Exposes runtime state for observability.
+ */
+export interface PreviewStats {
+    mode: 'preview';
+    scale: number;
+    semanticWidth: number;
+    semanticHeight: number;
+    bufferWidth: number;
+    bufferHeight: number;
+    frames: number;
+    stride: number;
+    totalTimeMs: number;
+    budgetExceeded?: {
+        reason: BudgetExceedReason;
+    };
 }
 /**
  * Preview render result
@@ -78,7 +137,7 @@ export interface PreviewRenderResult {
     errorMessage?: string;
 }
 /**
- * Preview renderer interface
+ * Preview renderer interface (v0.9.0)
  */
 export interface PreviewRenderer {
     /** Render a single frame (static mode) */
@@ -91,6 +150,10 @@ export interface PreviewRenderer {
     destroy: () => void;
     /** Check if currently rendering */
     isRendering: () => boolean;
+    /** Get current preview stats (v0.9.0) */
+    getPreviewStats: () => PreviewStats;
+    /** Current scale factor (v0.9.0) */
+    readonly previewScale: number;
     /** This renderer is NOT canonical */
     readonly isCanonical: false;
     /** This renderer is NOT archival */
@@ -103,4 +166,20 @@ export interface FpsThrottleState {
     /** Timestamp of last rendered frame */
     lastFrameTimeMs: number;
 }
+/**
+ * Canonical request for handoff to @nexart/codemode-sdk (v0.9.0)
+ */
+export interface CanonicalRequest {
+    seed: number;
+    vars: number[];
+    code: string;
+    settings?: {
+        width: number;
+        height: number;
+        mode: PreviewMode;
+        totalFrames?: number;
+    };
+    renderer: 'preview';
+    uiRendererVersion: string;
+}
 //# sourceMappingURL=preview-types.d.ts.map