@nexart/ui-renderer 0.7.0 → 0.8.1

package/dist/preview/frame-budget.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @nexart/ui-renderer - Frame Budget Manager
+ *
+ * Enforces hard execution limits to prevent browser freezes.
+ *
+ * ╔══════════════════════════════════════════════════════════════════════════╗
+ * ║  EXECUTION BUDGET — MANDATORY LIMITS                                     ║
+ * ║                                                                          ║
+ * ║  Max frames: 30                                                          ║
+ * ║  Max total time: 500ms                                                   ║
+ * ║  Target frame time: ~16ms                                                ║
+ * ║                                                                          ║
+ * ║  If limits exceeded: stop immediately, do NOT throw.                     ║
+ * ╚══════════════════════════════════════════════════════════════════════════╝
+ */
+import { type FrameBudgetState } from './preview-types';
+/**
+ * Create a new frame budget tracker
+ */
+export declare function createFrameBudget(): FrameBudgetState;
+/**
+ * Check if budget allows another frame.
+ * Returns true if we can render, false if budget is exhausted.
+ */
+export declare function canRenderFrame(budget: FrameBudgetState): boolean;
+/**
+ * Record that a frame was rendered
+ */
+export declare function recordFrame(budget: FrameBudgetState): void;
+/**
+ * Get elapsed time in milliseconds
+ */
+export declare function getElapsedMs(budget: FrameBudgetState): number;
+/**
+ * Reset the frame budget for a new render cycle
+ */
+export declare function resetBudget(budget: FrameBudgetState): void;
+/**
+ * Check if we should skip this frame for performance.
+ * Uses frame stride to reduce rendering load while keeping animation smooth.
+ */
+export declare function shouldSkipFrame(frameCount: number): boolean;
+//# sourceMappingURL=frame-budget.d.ts.map

package/dist/preview/frame-budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame-budget.d.ts","sourceRoot":"","sources":["../../src/preview/frame-budget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAkB,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAExE;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,gBAAgB,CAOpD;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAqBhE;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAE1D;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAE7D;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAK1D;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAE3D"}

package/dist/preview/frame-budget.js

@@ -0,0 +1,78 @@
+/**
+ * @nexart/ui-renderer - Frame Budget Manager
+ *
+ * Enforces hard execution limits to prevent browser freezes.
+ *
+ * ╔══════════════════════════════════════════════════════════════════════════╗
+ * ║  EXECUTION BUDGET — MANDATORY LIMITS                                     ║
+ * ║                                                                          ║
+ * ║  Max frames: 30                                                          ║
+ * ║  Max total time: 500ms                                                   ║
+ * ║  Target frame time: ~16ms                                                ║
+ * ║                                                                          ║
+ * ║  If limits exceeded: stop immediately, do NOT throw.                     ║
+ * ╚══════════════════════════════════════════════════════════════════════════╝
+ */
+import { PREVIEW_BUDGET } from './preview-types';
+/**
+ * Create a new frame budget tracker
+ */
+export function createFrameBudget() {
+    return {
+        framesRendered: 0,
+        startTimeMs: performance.now(),
+        exhausted: false,
+        exhaustionReason: undefined,
+    };
+}
+/**
+ * Check if budget allows another frame.
+ * Returns true if we can render, false if budget is exhausted.
+ */
+export function canRenderFrame(budget) {
+    if (budget.exhausted) {
+        return false;
+    }
+    // Check frame limit
+    if (budget.framesRendered >= PREVIEW_BUDGET.MAX_FRAMES) {
+        budget.exhausted = true;
+        budget.exhaustionReason = 'frame_limit';
+        return false;
+    }
+    // Check time limit
+    const elapsedMs = performance.now() - budget.startTimeMs;
+    if (elapsedMs >= PREVIEW_BUDGET.MAX_TOTAL_TIME_MS) {
+        budget.exhausted = true;
+        budget.exhaustionReason = 'time_limit';
+        return false;
+    }
+    return true;
+}
+/**
+ * Record that a frame was rendered
+ */
+export function recordFrame(budget) {
+    budget.framesRendered++;
+}
+/**
+ * Get elapsed time in milliseconds
+ */
+export function getElapsedMs(budget) {
+    return performance.now() - budget.startTimeMs;
+}
+/**
+ * Reset the frame budget for a new render cycle
+ */
+export function resetBudget(budget) {
+    budget.framesRendered = 0;
+    budget.startTimeMs = performance.now();
+    budget.exhausted = false;
+    budget.exhaustionReason = undefined;
+}
+/**
+ * Check if we should skip this frame for performance.
+ * Uses frame stride to reduce rendering load while keeping animation smooth.
+ */
+export function shouldSkipFrame(frameCount) {
+    return frameCount % PREVIEW_BUDGET.FRAME_STRIDE !== 0;
+}

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

@@ -0,0 +1,42 @@
+/**
+ * @nexart/ui-renderer - Preview Engine
+ *
+ * Lightweight, non-authoritative preview executor.
+ * Safe, interruptible, and performant.
+ *
+ * ╔══════════════════════════════════════════════════════════════════════════╗
+ * ║  PREVIEW ENGINE — NON-CANONICAL                                          ║
+ * ║                                                                          ║
+ * ║  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                                               ║
+ * ║                                                                          ║
+ * ║  NOT for:                                                                ║
+ * ║  - Minting / export                                                      ║
+ * ║  - ByX                                                                   ║
+ * ║  - Protocol validation                                                   ║
+ * ║                                                                          ║
+ * ║  For canonical output: use @nexart/codemode-sdk                          ║
+ * ╚══════════════════════════════════════════════════════════════════════════╝
+ */
+import { type PreviewEngineConfig, type PreviewRenderResult, type PreviewRenderer } from './preview-types';
+/**
+ * Create a preview renderer for the given configuration.
+ *
+ * This is the main entry point for preview rendering.
+ */
+export declare function createPreviewEngine(config: PreviewEngineConfig): PreviewRenderer;
+/**
+ * Render a static preview (single frame).
+ */
+export declare function renderStaticPreview(config: PreviewEngineConfig): PreviewRenderResult;
+/**
+ * Stop any active preview renderer.
+ */
+export declare function stopActivePreview(): void;
+//# sourceMappingURL=preview-engine.d.ts.map

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

@@ -0,0 +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;AAwMzB;;;;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

@@ -0,0 +1,204 @@
+/**
+ * @nexart/ui-renderer - Preview Engine
+ *
+ * Lightweight, non-authoritative preview executor.
+ * Safe, interruptible, and performant.
+ *
+ * ╔══════════════════════════════════════════════════════════════════════════╗
+ * ║  PREVIEW ENGINE — NON-CANONICAL                                          ║
+ * ║                                                                          ║
+ * ║  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                                               ║
+ * ║                                                                          ║
+ * ║  NOT for:                                                                ║
+ * ║  - Minting / export                                                      ║
+ * ║  - ByX                                                                   ║
+ * ║  - Protocol validation                                                   ║
+ * ║                                                                          ║
+ * ║  For canonical output: use @nexart/codemode-sdk                          ║
+ * ╚══════════════════════════════════════════════════════════════════════════╝
+ */
+import { createFrameBudget, canRenderFrame, recordFrame, getElapsedMs, resetBudget, shouldSkipFrame, } from './frame-budget';
+import { calculateScaledDimensions, applyScaledDimensions, reapplyContextScale, } from './canvas-scaler';
+import { createPreviewRuntime } from './preview-runtime';
+let activePreviewRenderer = null;
+class PreviewEngine {
+    constructor(config) {
+        this.runtime = null;
+        this.setupFn = null;
+        this.drawFn = null;
+        this.animationFrameId = null;
+        this.budget = createFrameBudget();
+        this.running = false;
+        this.internalFrameCount = 0;
+        this.isCanonical = false;
+        this.isArchival = false;
+        this.config = config;
+        this.canvas = config.canvas;
+        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);
+        this.runtime = createPreviewRuntime(this.canvas, scaled.renderWidth, scaled.renderHeight, this.config.seed ?? 12345, this.config.vars ?? []);
+        const totalFrames = this.config.totalFrames ?? 120;
+        this.runtime.totalFrames = totalFrames;
+        try {
+            const fn = this.compileSource(this.config.source);
+            fn();
+        }
+        catch (error) {
+            console.warn('[PreviewEngine] Error compiling source:', error);
+        }
+    }
+    compileSource(source) {
+        const runtime = this.runtime;
+        const self = this;
+        const globalVars = Object.keys(runtime);
+        const globalValues = Object.values(runtime);
+        globalVars.push('setup', 'draw');
+        const wrappedSource = `
+      ${source}
+      if (typeof setup === 'function') __registerSetup(setup);
+      if (typeof draw === 'function') __registerDraw(draw);
+    `;
+        const registerSetup = (fn) => { self.setupFn = fn; };
+        const registerDraw = (fn) => { self.drawFn = fn; };
+        globalValues.push(registerSetup, registerDraw);
+        globalVars.push('__registerSetup', '__registerDraw');
+        const fn = new Function(...globalVars, wrappedSource);
+        return () => fn(...globalValues);
+    }
+    renderStatic() {
+        resetBudget(this.budget);
+        try {
+            if (this.setupFn) {
+                this.setupFn();
+            }
+            recordFrame(this.budget);
+            return {
+                success: true,
+                framesRendered: 1,
+                executionTimeMs: getElapsedMs(this.budget),
+                terminatedEarly: false,
+            };
+        }
+        catch (error) {
+            console.warn('[PreviewEngine] Static render error:', error);
+            return {
+                success: false,
+                framesRendered: 0,
+                executionTimeMs: getElapsedMs(this.budget),
+                terminatedEarly: true,
+                terminationReason: 'error',
+                errorMessage: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    startLoop() {
+        if (this.running)
+            return;
+        if (activePreviewRenderer && activePreviewRenderer !== this) {
+            activePreviewRenderer.stopLoop();
+        }
+        activePreviewRenderer = this;
+        this.running = true;
+        resetBudget(this.budget);
+        this.internalFrameCount = 0;
+        try {
+            if (this.setupFn) {
+                this.setupFn();
+            }
+        }
+        catch (error) {
+            console.warn('[PreviewEngine] Setup error:', error);
+        }
+        this.scheduleNextFrame();
+    }
+    scheduleNextFrame() {
+        if (!this.running)
+            return;
+        this.animationFrameId = requestAnimationFrame(() => {
+            if (!this.running)
+                return;
+            if (!canRenderFrame(this.budget)) {
+                this.running = false;
+                return;
+            }
+            this.internalFrameCount++;
+            if (!shouldSkipFrame(this.internalFrameCount)) {
+                try {
+                    if (this.runtime) {
+                        this.runtime.frameCount = this.internalFrameCount;
+                        const totalFrames = this.config.totalFrames ?? 120;
+                        this.runtime.t = this.internalFrameCount / totalFrames;
+                        this.runtime.time = this.runtime.t;
+                        this.runtime.tGlobal = this.runtime.t;
+                    }
+                    if (this.drawFn) {
+                        this.drawFn();
+                    }
+                    recordFrame(this.budget);
+                }
+                catch (error) {
+                    console.warn('[PreviewEngine] Draw error:', error);
+                }
+            }
+            this.scheduleNextFrame();
+        });
+    }
+    stopLoop() {
+        this.running = false;
+        if (this.animationFrameId !== null) {
+            cancelAnimationFrame(this.animationFrameId);
+            this.animationFrameId = null;
+        }
+        if (activePreviewRenderer === this) {
+            activePreviewRenderer = null;
+        }
+    }
+    isRendering() {
+        return this.running;
+    }
+    destroy() {
+        this.stopLoop();
+        this.runtime = null;
+        this.setupFn = null;
+        this.drawFn = null;
+    }
+}
+/**
+ * Create a preview renderer for the given configuration.
+ *
+ * This is the main entry point for preview rendering.
+ */
+export function createPreviewEngine(config) {
+    return new PreviewEngine(config);
+}
+/**
+ * Render a static preview (single frame).
+ */
+export function renderStaticPreview(config) {
+    const engine = new PreviewEngine(config);
+    const result = engine.renderStatic();
+    engine.destroy();
+    return result;
+}
+/**
+ * Stop any active preview renderer.
+ */
+export function stopActivePreview() {
+    if (activePreviewRenderer) {
+        activePreviewRenderer.stopLoop();
+        activePreviewRenderer = null;
+    }
+}

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

@@ -0,0 +1,28 @@
+/**
+ * @nexart/ui-renderer - Preview Runtime
+ *
+ * Simplified p5-like runtime for preview rendering.
+ * Same API surface as Code Mode, but optimized for performance.
+ *
+ * ╔══════════════════════════════════════════════════════════════════════════╗
+ * ║  PREVIEW RUNTIME — SAME API, SIMPLIFIED INTERNALS                        ║
+ * ║                                                                          ║
+ * ║  This runtime:                                                           ║
+ * ║  - Uses same function names as Code Mode                                 ║
+ * ║  - Is NOT deterministic (performance > fidelity)                         ║
+ * ║  - May have simplified implementations                                   ║
+ * ║  - Pixel operations may be capped                                        ║
+ * ║                                                                          ║
+ * ║  For canonical output: use @nexart/codemode-sdk                          ║
+ * ╚══════════════════════════════════════════════════════════════════════════╝
+ */
+export interface PreviewP5Runtime {
+    [key: string]: any;
+    mode: 'preview';
+    width: number;
+    height: number;
+    frameCount: number;
+    VAR: readonly number[];
+}
+export declare function createPreviewRuntime(canvas: HTMLCanvasElement, width: number, height: number, seed?: number, vars?: number[]): PreviewP5Runtime;
+//# sourceMappingURL=preview-runtime.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"preview-runtime.d.ts","sourceRoot":"","sources":["../../src/preview/preview-runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;IACnB,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,SAAS,MAAM,EAAE,CAAC;CACxB;AAiED,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,iBAAiB,EACzB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,MAAc,EACpB,IAAI,GAAE,MAAM,EAAO,GAClB,gBAAgB,CA4YlB"}