@nexart/ui-renderer 0.8.8 → 0.9.0

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

@@ -1 +1 @@
-{"version":3,"file":"preview-types.d.ts","sourceRoot":"","sources":["../../src/preview/preview-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,SAAS,CAAC;AAEvC;;;GAGG;AACH,eAAO,MAAM,WAAW;IACtB,kEAAkE;;IAElE,0CAA0C;;CAElC,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,aAAa;IACxB,2CAA2C;;IAE3C,wBAAwB;;CAEhB,CAAC;AAEX;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE5C;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,kCAAkC;IAClC,MAAM,EAAE,iBAAiB,CAAC;IAC1B,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,mBAAmB;IACnB,IAAI,EAAE,WAAW,CAAC;IAClB,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,4CAA4C;IAC5C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,qDAAqD;IACrD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,+CAA+C;IAC/C,OAAO,EAAE,OAAO,CAAC;IACjB,sBAAsB;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,iCAAiC;IACjC,eAAe,EAAE,MAAM,CAAC;IACxB,2DAA2D;IAC3D,eAAe,EAAE,OAAO,CAAC;IACzB,uCAAuC;IACvC,iBAAiB,CAAC,EAAE,aAAa,GAAG,YAAY,GAAG,WAAW,GAAG,OAAO,CAAC;IACzE,0CAA0C;IAC1C,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,0CAA0C;IAC1C,YAAY,EAAE,MAAM,mBAAmB,CAAC;IACxC,2BAA2B;IAC3B,SAAS,EAAE,MAAM,IAAI,CAAC;IACtB,0BAA0B;IAC1B,QAAQ,EAAE,MAAM,IAAI,CAAC;IACrB,oCAAoC;IACpC,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,mCAAmC;IACnC,WAAW,EAAE,MAAM,OAAO,CAAC;IAC3B,qCAAqC;IACrC,QAAQ,CAAC,WAAW,EAAE,KAAK,CAAC;IAC5B,oCAAoC;IACpC,QAAQ,CAAC,UAAU,EAAE,KAAK,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,uCAAuC;IACvC,eAAe,EAAE,MAAM,CAAC;CACzB"}
+{"version":3,"file":"preview-types.d.ts","sourceRoot":"","sources":["../../src/preview/preview-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,SAAS,CAAC;AAEvC;;;GAGG;AACH,eAAO,MAAM,WAAW;IACtB,kEAAkE;;IAElE,0CAA0C;;CAElC,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,aAAa;IACxB,2CAA2C;;IAE3C,wBAAwB;;CAEhB,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,cAAc;IACzB,4DAA4D;;IAE5D,wDAAwD;;IAExD,0DAA0D;;CAElD,CAAC;AAEX;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE5C;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,aAAa,GAAG,YAAY,CAAC;AAE9D;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,kBAAkB,CAAC;IAC3B,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,MAAM,CAAC;AAEhD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,kCAAkC;IAClC,MAAM,EAAE,iBAAiB,CAAC;IAC1B,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,mBAAmB;IACnB,IAAI,EAAE,WAAW,CAAC;IAClB,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,4CAA4C;IAC5C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,qDAAqD;IACrD,WAAW,CAAC,EAAE,MAAM,CAAC;IAGrB,uCAAuC;IACvC,gBAAgB,CAAC,EAAE,CAAC,IAAI,EAAE,kBAAkB,KAAK,IAAI,CAAC;IACtD,wFAAwF;IACxF,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,4EAA4E;IAC5E,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qDAAqD;IACrD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE;QAAE,MAAM,EAAE,kBAAkB,CAAA;KAAE,CAAC;CACjD;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,+CAA+C;IAC/C,OAAO,EAAE,OAAO,CAAC;IACjB,sBAAsB;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,iCAAiC;IACjC,eAAe,EAAE,MAAM,CAAC;IACxB,2DAA2D;IAC3D,eAAe,EAAE,OAAO,CAAC;IACzB,uCAAuC;IACvC,iBAAiB,CAAC,EAAE,aAAa,GAAG,YAAY,GAAG,WAAW,GAAG,OAAO,CAAC;IACzE,0CAA0C;IAC1C,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,0CAA0C;IAC1C,YAAY,EAAE,MAAM,mBAAmB,CAAC;IACxC,2BAA2B;IAC3B,SAAS,EAAE,MAAM,IAAI,CAAC;IACtB,0BAA0B;IAC1B,QAAQ,EAAE,MAAM,IAAI,CAAC;IACrB,oCAAoC;IACpC,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,mCAAmC;IACnC,WAAW,EAAE,MAAM,OAAO,CAAC;IAC3B,yCAAyC;IACzC,eAAe,EAAE,MAAM,YAAY,CAAC;IACpC,oCAAoC;IACpC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,qCAAqC;IACrC,QAAQ,CAAC,WAAW,EAAE,KAAK,CAAC;IAC5B,oCAAoC;IACpC,QAAQ,CAAC,UAAU,EAAE,KAAK,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,uCAAuC;IACvC,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE;QACT,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,WAAW,CAAC;QAClB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,QAAQ,EAAE,SAAS,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC;CAC3B"}

package/dist/preview/preview-types.js

@@ -1,5 +1,6 @@
 /**
  * @nexart/ui-renderer - Preview Runtime Types
+ * Version: 0.9.0
  *
  * ╔══════════════════════════════════════════════════════════════════════════╗
  * ║  PREVIEW RUNTIME — NON-AUTHORITATIVE                                     ║
@@ -30,3 +31,15 @@ export const CANVAS_LIMITS = {
     /** Minimum dimension */
     MIN_DIMENSION: 100,
 };
+/**
+ * Preview budget limits (v0.9.0)
+ * Enforced optionally to prevent runaway previews.
+ */
+export const PREVIEW_BUDGET = {
+    /** Maximum frames before budget exceeded (default: 1800) */
+    MAX_FRAMES: 1800, // ~30 seconds at 60 FPS
+    /** Maximum execution time in ms (default: 5 minutes) */
+    MAX_TOTAL_TIME_MS: 300000, // 5 minutes
+    /** Default stride when degrading (skip every N frames) */
+    DEGRADE_STRIDE: 2,
+};

package/examples/basic-preview.ts

@@ -0,0 +1,92 @@
+/**
+ * @nexart/ui-renderer - Basic Preview Example
+ * 
+ * Demonstrates basic usage of createPreviewRuntime with stats logging.
+ * 
+ * Run with: npm run example:basic
+ * 
+ * Note: This example is designed for browser environments.
+ * In Node.js, it will print the expected usage pattern.
+ */
+
+console.log(`
+╔══════════════════════════════════════════════════════════════════════════╗
+║  @nexart/ui-renderer - Basic Preview Example                             ║
+╚══════════════════════════════════════════════════════════════════════════╝
+
+This example shows how to use createPreviewRuntime in a browser environment.
+
+BROWSER CODE:
+─────────────────────────────────────────────────────────────────────────────
+
+import { createPreviewRuntime } from '@nexart/ui-renderer';
+
+// Create a canvas element
+const canvas = document.getElementById('preview-canvas');
+
+// Create the preview runtime
+const runtime = createPreviewRuntime({
+  canvas,
+  source: \`
+    function setup() {
+      noFill();
+      stroke(0);
+    }
+    function draw() {
+      background(246, 245, 242);
+      var count = int(map(VAR[0], 0, 100, 5, 30));
+      for (var i = 0; i < count; i++) {
+        var x = width / 2 + cos(t * TWO_PI + i * 0.5) * 300;
+        var y = height / 2 + sin(t * TWO_PI + i * 0.3) * 200;
+        ellipse(x, y, 50);
+      }
+    }
+  \`,
+  mode: 'loop',
+  width: 1950,
+  height: 2400,
+  seed: 12345,
+  vars: [50, 75, 25],
+  totalFrames: 120,
+});
+
+// Start the animation
+runtime.startLoop();
+
+// Log stats every second
+setInterval(() => {
+  const stats = runtime.getPreviewStats();
+  console.log('Preview Stats:', {
+    mode: stats.mode,
+    scale: stats.scale.toFixed(2),
+    frames: stats.frames,
+    stride: stats.stride,
+    totalTimeMs: Math.round(stats.totalTimeMs),
+    budgetExceeded: stats.budgetExceeded ?? 'no',
+  });
+}, 1000);
+
+// Stop after 10 seconds
+setTimeout(() => {
+  runtime.stopLoop();
+  console.log('Preview stopped');
+}, 10000);
+
+─────────────────────────────────────────────────────────────────────────────
+
+KEY POINTS:
+- Use createPreviewRuntime (recommended) or createPreviewEngine
+- mode: 'loop' for animations, 'static' for single frame
+- Check getPreviewStats() to monitor budget and performance
+- Preview is NOT canonical — use @nexart/codemode-sdk for minting
+`);
+
+// Demonstrate API shape (Node.js compatible)
+import { SDK_VERSION, PREVIEW_BUDGET, CANVAS_LIMITS } from '../src/index';
+
+console.log('SDK Configuration:');
+console.log('  Version:', SDK_VERSION);
+console.log('  FPS: Native RAF (~60 FPS)');
+console.log('  Max Dimension:', CANVAS_LIMITS.MAX_DIMENSION + 'px');
+console.log('  Max Frames:', PREVIEW_BUDGET.MAX_FRAMES);
+console.log('  Max Time:', PREVIEW_BUDGET.MAX_TOTAL_TIME_MS / 1000 + 's');

package/examples/budget-demo.ts

@@ -0,0 +1,161 @@
+/**
+ * @nexart/ui-renderer - Budget Demo Example
+ * 
+ * Demonstrates budget exceed handling with callbacks and overlay.
+ * 
+ * Run with: npm run example:budget
+ * 
+ * Note: This example is designed for browser environments.
+ * In Node.js, it will print the expected usage pattern.
+ */
+
+console.log(`
+╔══════════════════════════════════════════════════════════════════════════╗
+║  @nexart/ui-renderer - Budget Demo Example                               ║
+╚══════════════════════════════════════════════════════════════════════════╝
+
+This example shows how to handle budget exceeded events.
+
+BROWSER CODE (with 'stop' behavior):
+─────────────────────────────────────────────────────────────────────────────
+
+import { createPreviewRuntime } from '@nexart/ui-renderer';
+
+const canvas = document.getElementById('preview-canvas');
+
+// Heavy sketch that will exceed budget quickly
+const heavySketch = \`
+  function draw() {
+    background(30);
+    for (var i = 0; i < 10000; i++) {
+      var x = random(width);
+      var y = random(height);
+      stroke(random(255), random(255), random(255), 50);
+      point(x, y);
+    }
+  }
+\`;
+
+const runtime = createPreviewRuntime({
+  canvas,
+  source: heavySketch,
+  mode: 'loop',
+  width: 1950,
+  height: 2400,
+  
+  // Budget configuration
+  maxFrames: 100,        // Low frame limit for demo
+  maxTimeMs: 10000,      // 10 second time limit
+  budgetBehavior: 'stop', // 'stop' or 'degrade'
+  showOverlay: true,     // Show overlay when stopped
+  
+  // Callback when budget is exceeded
+  onBudgetExceeded: (info) => {
+    console.log('⚠️ Budget exceeded!');
+    console.log('  Reason:', info.reason);
+    console.log('  Frames rendered:', info.framesRendered);
+    console.log('  Total time:', Math.round(info.totalTimeMs) + 'ms');
+    console.log('  Scale:', info.scale.toFixed(2));
+    console.log('  Stride:', info.stride);
+  },
+});
+
+runtime.startLoop();
+
+─────────────────────────────────────────────────────────────────────────────
+
+BROWSER CODE (with 'degrade' behavior):
+─────────────────────────────────────────────────────────────────────────────
+
+const runtime = createPreviewRuntime({
+  canvas,
+  source: heavySketch,
+  mode: 'loop',
+  width: 1950,
+  height: 2400,
+  
+  budgetBehavior: 'degrade',  // Continue running but skip frames
+  maxFrames: 100,
+  
+  onBudgetExceeded: (info) => {
+    console.log('Budget exceeded, now skipping every 2nd frame');
+    // Preview continues but at reduced frame rate
+  },
+});
+
+─────────────────────────────────────────────────────────────────────────────
+
+CHECKING STATS:
+─────────────────────────────────────────────────────────────────────────────
+
+const stats = runtime.getPreviewStats();
+
+if (stats.budgetExceeded) {
+  console.log('Preview was stopped due to:', stats.budgetExceeded.reason);
+  
+  // Options:
+  // 1. Reduce sketch complexity
+  // 2. Increase budget limits
+  // 3. Use @nexart/codemode-sdk for canonical execution
+}
+
+─────────────────────────────────────────────────────────────────────────────
+
+HANDOFF TO CANONICAL:
+─────────────────────────────────────────────────────────────────────────────
+
+import { toCanonicalRequest } from '@nexart/ui-renderer';
+
+const config = {
+  canvas,
+  source: sketchCode,
+  mode: 'loop',
+  width: 1950,
+  height: 2400,
+  seed: 12345,
+  vars: [50, 75, 25],
+};
+
+// Get canonical request for @nexart/codemode-sdk
+const canonicalReq = toCanonicalRequest(config);
+console.log('Canonical request:', canonicalReq);
+// {
+//   seed: 12345,
+//   vars: [50, 75, 25],
+//   code: "...",
+//   settings: { width: 1950, height: 2400, mode: 'loop' },
+//   renderer: 'preview',
+//   uiRendererVersion: '0.9.0'
+// }
+
+// Pass to backend or use @nexart/codemode-sdk directly:
+// import { createRuntime } from '@nexart/codemode-sdk';
+// const runtime = createRuntime({ seed, vars, mode });
+
+─────────────────────────────────────────────────────────────────────────────
+`);
+
+// Demonstrate API shape (Node.js compatible)
+import { SDK_VERSION, PREVIEW_BUDGET, toCanonicalRequest, type PreviewEngineConfig } from '../src/index';
+
+console.log('Budget Configuration:');
+console.log('  Max Frames:', PREVIEW_BUDGET.MAX_FRAMES);
+console.log('  Max Time:', PREVIEW_BUDGET.MAX_TOTAL_TIME_MS / 1000 + 's');
+console.log('  Degrade Stride:', PREVIEW_BUDGET.DEGRADE_STRIDE);
+
+console.log('');
+console.log('toCanonicalRequest example output:');
+
+const mockConfig = {
+  canvas: null as any,
+  source: 'function draw() { circle(100, 100, 50); }',
+  mode: 'loop' as const,
+  width: 1950,
+  height: 2400,
+  seed: 12345,
+  vars: [50, 75, 25],
+  totalFrames: 120,
+};
+
+const canonical = toCanonicalRequest(mockConfig);
+console.log(JSON.stringify(canonical, null, 2));

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nexart/ui-renderer",
-  "version": "0.8.8",
-  "description": "Lightweight Preview Runtime for NexArt Protocol. Non-canonical, native requestAnimationFrame (~60 FPS, max 900px canvas).",
+  "version": "0.9.0",
+  "description": "Lightweight Preview Runtime for NexArt Protocol. Non-canonical, browser-first, with budget callbacks and observability for AI coding agents.",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -14,14 +14,20 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "examples",
+    "README.md",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "build": "tsc",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "example:basic": "npx tsx examples/basic-preview.ts",
+    "example:budget": "npx tsx examples/budget-demo.ts",
+    "test": "npm run build && node --test dist/*.test.js 2>/dev/null || echo 'No tests yet'"
   },
   "dependencies": {
-    "@nexart/codemode-sdk": "^1.4.0"
+    "@nexart/codemode-sdk": "^1.8.0"
   },
   "devDependencies": {
     "typescript": "^5.0.0"
@@ -34,7 +40,9 @@
     "declarative",
     "protocol",
     "authoring",
-    "preview"
+    "preview",
+    "ai-agent",
+    "deterministic"
   ],
   "repository": {
     "type": "git",