@nexart/ui-renderer 0.8.7 → 0.9.0

package/README.md

@@ -1,6 +1,6 @@
 # @nexart/ui-renderer
 
-Version: 0.8.7
+Version: 0.9.0
 
 **Lightweight Preview Runtime for NexArt Protocol**
 
@@ -19,124 +19,191 @@ Version: 0.8.7
 
 ---
 
-## v0.8.7 — Live Runtime Binding Fix
-
-Fixed critical bug where time-varying properties were frozen in loop mode.
-
-- **Live binding**: `frameCount`, `t`, `time`, `tGlobal`, `totalFrames` now update every frame
-- **Proxy + with pattern**: Uses a Proxy scope with `with()` for live property access
-- **Animations work**: Sketches see correct values on every frame
-
-**Animation Semantics:**
-In loop mode, all time variables update every frame:
-- `frameCount`: Increments each frame
-- `t`: Normalized time `(frameCount % totalFrames) / totalFrames` (range [0,1))
-- `time`: Alias for `t`
-- `tGlobal`: Alias for `t`
-- `totalFrames`: Total frames in the loop (default 120)
-
-**Test Sketch:**
-```javascript
-function draw() {
-  background(0);
-  fill(255);
-  circle(
-    width / 2 + sin(frameCount * 0.1) * 300,
-    height / 2,
-    120
-  );
-}
-```
-Expected: Circle moves horizontally, motion is continuous.
+## For AI Coding Agents (Replit / Lovable / Claude Code)
 
----
+### 20-Second Quickstart
+
+```typescript
+import { createPreviewRuntime } from '@nexart/ui-renderer';
+
+const runtime = createPreviewRuntime({
+  canvas: document.getElementById('canvas'),
+  source: `
+    function draw() {
+      background(30);
+      circle(width/2 + sin(t * TWO_PI) * 200, height/2, 100);
+    }
+  `,
+  mode: 'loop',
+  width: 1950,
+  height: 2400,
+  seed: 12345,
+  vars: [50, 75, 25],
+  totalFrames: 120,
+  onBudgetExceeded: (info) => console.warn('Budget exceeded:', info),
+});
+
+runtime.startLoop();
+```
 
-## v0.8.3 — Animation Loop Fix
+Preview mode may visually differ due to scaling/budgets. For canonical output and verification, run the same code with `@nexart/codemode-sdk`.
 
-Fixed critical bug where preview only rendered a single frame.
+### Detecting Preview Mode
 
-- **RAF unconditionally scheduled**: `requestAnimationFrame(loop)` is now called on every tick
-- **Budget gates draw only**: Frame budget controls whether `draw()` runs, not whether the loop continues
-- **Continuous animation**: Loop runs forever until explicitly stopped
+```typescript
+const stats = runtime.getPreviewStats();
 
-**Animation Loop Invariant (locked for v0.x):**
+if (stats.mode === 'preview') {
+  console.log('Running in preview mode');
+  console.log('Scale:', stats.scale);
+  console.log('Frames:', stats.frames);
+}
 ```
-RAF schedules → budget checks → draw executes (or skips) → repeat
-Never: budget check → stop loop
+
+### Handling Budget Exceeded
+
+```typescript
+const stats = runtime.getPreviewStats();
+
+if (stats.budgetExceeded) {
+  console.log('Exceeded:', stats.budgetExceeded.reason);
+  // Options:
+  // 1. Reduce sketch complexity (fewer iterations, simpler shapes)
+  // 2. Increase maxFrames or maxTimeMs in config
+  // 3. Use @nexart/codemode-sdk for canonical execution
+}
 ```
 
 ---
 
-## v0.8.2 — Runtime Dimensions Fix
+## Preview vs Canonical
 
-Fixed critical bug where preview scaling affected `width`/`height` inside sketches.
+| Aspect | Preview (@nexart/ui-renderer) | Canonical (@nexart/codemode-sdk) |
+|--------|-------------------------------|----------------------------------|
+| **Purpose** | Fast browser previews | Authoritative rendering |
+| **Determinism** | Approximate | Guaranteed |
+| **Resolution** | Max 900px | Full resolution (1950×2400) |
+| **FPS** | Native RAF (~60 FPS) | Full frame rate |
+| **Budget** | 1800 frames / 5 min | Unlimited |
+| **Use for** | Editor, dashboard, prototyping | Minting, export, archival |
 
-- **Runtime uses original dimensions**: `width` and `height` now match Code Mode exactly
-- **Canvas buffer still scaled for performance**: Rendering is fast, semantics are correct
-- **Loop animations work correctly**: Geometry math and timing no longer break
-
-**Key rule enforced:** Preview scaling is a rendering concern, not a semantic one.
+**Rule of thumb:**
+- Use **ui-renderer** for quick visual feedback during development
+- Use **codemode-sdk** for final output, minting, or any permanent storage
 
 ---
 
-## v0.8.1 — Canvas Scaling Fix
+## v0.9.0 — Budget Callbacks + Observability
 
-Fixed canvas zoom/cropping bug caused by resolution downscaling in v0.8.0.
+### New Features
 
-- **Scale Transform Reapplied**: Context scale is now properly restored after canvas resize
-- **Transform-Safe Clear**: `clearRect` now ignores active transforms for correct full-canvas clearing
-- **No API Changes**: All fixes are internal
+1. **No more silent stops** — Budget exceeded now triggers callbacks and optional overlay
+2. **getPreviewStats()** — Full observability into runtime state
+3. **createPreviewRuntime()** — Recommended entrypoint for agents
+4. **toCanonicalRequest()** — Handoff helper for @nexart/codemode-sdk
 
----
+### Budget Configuration
+
+```typescript
+const runtime = createPreviewRuntime({
+  canvas,
+  source: sketchCode,
+  mode: 'loop',
+  width: 1950,
+  height: 2400,
+  
+  // Budget options (all optional)
+  maxFrames: 1800,        // Max frames before budget exceeded
+  maxTimeMs: 300000,      // Max time (5 min default)
+  budgetBehavior: 'stop', // 'stop' (with overlay) or 'degrade' (skip frames)
+  showOverlay: true,      // Show overlay when stopped
+  
+  onBudgetExceeded: (info) => {
+    console.log('Budget exceeded:', info.reason);
+    console.log('Frames:', info.framesRendered);
+    console.log('Time:', info.totalTimeMs);
+  },
+});
+```
+
+### Preview Stats
 
-## v0.8.0 — Lightweight Preview Runtime
+```typescript
+const stats = runtime.getPreviewStats();
+// {
+//   mode: 'preview',
+//   scale: 0.46,              // Canvas scale factor
+//   semanticWidth: 1950,      // Original width (for sketch math)
+//   semanticHeight: 2400,     // Original height
+//   bufferWidth: 897,         // Actual canvas width
+//   bufferHeight: 900,        // Actual canvas height
+//   frames: 150,              // Frames rendered
+//   stride: 1,                // Current stride (1 = every frame)
+//   totalTimeMs: 18750,       // Total time
+//   budgetExceeded?: { reason: 'frame_limit' | 'time_limit' }
+// }
+```
 
-This release refactors the UI renderer into a performance-optimized preview runtime.
+### Canonical Handoff
 
-### Philosophy Change
+```typescript
+import { toCanonicalRequest } from '@nexart/ui-renderer';
 
-**The UI renderer is explicitly preview-only:**
-- No protocol errors thrown
-- No forbidden pattern checking
-- Soft warnings instead of hard failures
-- Permissive — clamping instead of rejecting
+const config = { canvas, source, mode: 'loop', width: 1950, height: 2400, seed: 12345 };
+const req = toCanonicalRequest(config);
+
+// Pass to backend for canonical rendering:
+// await fetch('/api/render', { body: JSON.stringify(req) });
+```
+
+---
 
-### Preview Budget (MANDATORY)
+## Troubleshooting
 
-The runtime enforces hard limits to prevent browser freezes:
+### "My sketch stops animating"
+
+Check `getPreviewStats().budgetExceeded`:
 
 ```typescript
-PREVIEW_BUDGET = {
-  MAX_FRAMES: 30,           // Maximum frames before auto-stop
-  MAX_TOTAL_TIME_MS: 500,   // Maximum execution time
-  FRAME_STRIDE: 3,          // Render every 3rd frame
-};
+const stats = runtime.getPreviewStats();
+if (stats.budgetExceeded) {
+  console.log('Stopped because:', stats.budgetExceeded.reason);
+}
 ```
 
-If limits exceeded: rendering stops silently (no throw).
+**Solutions:**
+1. Reduce sketch complexity (fewer loop iterations, simpler shapes)
+2. Increase budget: `maxFrames: 3600` or `maxTimeMs: 600000`
+3. Use `budgetBehavior: 'degrade'` to continue at reduced frame rate
+4. For long-running animations, use `@nexart/codemode-sdk`
 
-### Canvas Scaling
+### "Canvas is too small"
 
-Preview renderer scales large canvases automatically:
+Preview scales canvases to max 900px for performance:
 
 ```typescript
-CANVAS_LIMITS = {
-  MAX_DIMENSION: 900,  // Max width/height in pixels
-  MIN_DIMENSION: 100,
-};
+const stats = runtime.getPreviewStats();
+console.log('Buffer size:', stats.bufferWidth, 'x', stats.bufferHeight);
+console.log('Semantic size:', stats.semanticWidth, 'x', stats.semanticHeight);
 ```
 
-Aspect ratio is preserved. CSS scaling for display.
+Your sketch code sees `width` and `height` as the original values (1950×2400).
+The canvas buffer is scaled down, but your geometry math stays correct.
 
-### Runtime Mode Flag
+### "Animation looks choppy"
 
-The preview runtime exposes a `mode` property:
+Preview runs at native RAF cadence (~60 FPS). If animations appear choppy:
 
+1. Check if budget exceeded (degrade mode skips frames):
 ```typescript
-runtime.mode // 'preview'
+const stats = runtime.getPreviewStats();
+if (stats.budgetExceeded && stats.stride > 1) {
+  console.log('Running in degraded mode, skipping frames');
+}
 ```
 
-Use this to detect preview vs canonical rendering.
+2. Reduce sketch complexity (heavy draw() calls)
+3. Check browser performance (GPU acceleration, tab throttling)
 
 ---
 
@@ -149,243 +216,103 @@ npm install @nexart/ui-renderer
 Or use directly in HTML:
 ```html
 <script type="module">
-  import { createSystem, previewSystem } from 'https://unpkg.com/@nexart/ui-renderer/dist/index.js';
+  import { createPreviewRuntime } from 'https://unpkg.com/@nexart/ui-renderer/dist/index.js';
 </script>
 ```
 
 ---
 
-## Quick Start
-
-### Code Mode Preview
-
-```typescript
-import { createSystem, previewSystem } from '@nexart/ui-renderer';
-
-const system = createSystem({
-  type: 'code',
-  mode: 'loop',
-  width: 1950,
-  height: 2400,
-  totalFrames: 120,
-  seed: 12345,
-  vars: [50, 75, 25],  // VAR[0..9] — values 0-100, padded with zeros
-  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) * map(VAR[1], 0, 100, 50, 400);
-        var y = height / 2 + sin(t * TWO_PI + i * 0.3) * 200;
-        ellipse(x, y, 50);
-      }
-    }
-  `
-});
-
-const canvas = document.getElementById('canvas');
-const renderer = previewSystem(system, canvas);
-renderer.start();
-```
-
-### Static Mode (single frame)
-
-```typescript
-const staticSystem = createSystem({
-  type: 'code',
-  mode: 'static',
-  width: 1950,
-  height: 2400,
-  seed: 12345,
-  vars: [50, 50, 50],
-  source: `
-    function setup() {
-      background(246, 245, 242);
-      fill(0);
-      var count = int(map(VAR[0], 0, 100, 10, 200));
-      for (var i = 0; i < count; i++) {
-        ellipse(random(width), random(height), random(10, 50));
-      }
-    }
-  `
-});
-
-previewSystem(staticSystem, canvas).render();
-```
-
----
-
 ## API Reference
 
-### `createSystem(input)`
+### `createPreviewRuntime(config)` ⭐ Recommended
 
-Create a NexArt system for preview.
+Create a preview renderer. This is the recommended entrypoint.
 
 ```typescript
-const system = createSystem({
-  type: 'code',
+const runtime = createPreviewRuntime({
+  canvas: HTMLCanvasElement,
+  source: string,              // p5-like sketch code
   mode: 'static' | 'loop',
   width: number,
   height: number,
-  source: string,           // Raw p5-like sketch code
-  seed?: number,            // PRNG seed
-  totalFrames?: number,     // Required for loop mode
-  vars?: number[]           // VAR[0..9] (0-10 values, 0-100 range, clamped)
+  seed?: number,               // PRNG seed
+  vars?: number[],             // VAR[0..9] (0-100 range)
+  totalFrames?: number,        // For loop mode (default: 120)
+  
+  // v0.9.0 budget options
+  onBudgetExceeded?: (info: BudgetExceededInfo) => void,
+  budgetBehavior?: 'stop' | 'degrade',
+  showOverlay?: boolean,
+  maxFrames?: number,
+  maxTimeMs?: number,
 });
+
+runtime.startLoop();           // Start animation
+runtime.stopLoop();            // Stop animation
+runtime.renderStatic();        // Render single frame
+runtime.getPreviewStats();     // Get current stats
+runtime.previewScale;          // Canvas scale factor
+runtime.destroy();             // Clean up
 ```
 
-### `previewSystem(system, canvas, options?)`
+### `createSystem(input)` + `previewSystem(system, canvas)`
 
-Render a preview to canvas.
+Legacy API for declarative systems. Still supported:
 
 ```typescript
-const renderer = previewSystem(system, canvas, {
-  showBadge: boolean  // default: true — shows "⚠️ Preview" badge
+import { createSystem, previewSystem } from '@nexart/ui-renderer';
+
+const system = createSystem({
+  type: 'code',
+  mode: 'loop',
+  width: 1950,
+  height: 2400,
+  source: sketchCode,
+  seed: 12345,
+  vars: [50, 75, 25],
 });
 
-renderer.render();  // Single frame
-renderer.start();   // Start loop
-renderer.stop();    // Stop loop
-renderer.destroy(); // Cleanup
+const renderer = previewSystem(system, canvas);
+renderer.start();
 ```
 
-### `validateSystem(input)`
+### `toCanonicalRequest(config)`
 
-Soft validation — warns but doesn't throw for minor issues.
+Generate a request object for handoff to `@nexart/codemode-sdk`:
 
 ```typescript
-const result = validateSystem(input);
-if (!result.valid) {
-  console.log(result.errors);  // Structural issues only
-}
+import { toCanonicalRequest } from '@nexart/ui-renderer';
+
+const req = toCanonicalRequest(config);
+// { seed, vars, code, settings, renderer: 'preview', uiRendererVersion }
 ```
 
 ### `getCapabilities()`
 
-Discover SDK capabilities for AI and tooling.
+Discover SDK capabilities:
 
 ```typescript
 import { getCapabilities } from '@nexart/ui-renderer';
 
 const caps = getCapabilities();
-// {
-//   version: '0.8.7',
-//   isCanonical: false,
-//   isArchival: false,
-//   previewBudget: { MAX_FRAMES: 30, MAX_TOTAL_TIME_MS: 500, FRAME_STRIDE: 3 },
-//   canvasLimits: { MAX_DIMENSION: 900 },
-//   ...
-// }
+// { version, isCanonical, previewBudget, canvasLimits, ... }
 ```
 
 ---
 
 ## Available Helpers
 
-The preview runtime includes all standard p5-like functions plus:
+The preview runtime includes all standard p5-like functions:
 
 | Helper | Description |
 |--------|-------------|
-| `int(n)` | Convert to integer (Math.floor) |
-| `fract(n)` | Fractional part of number |
-| `sign(n)` | Sign of number |
+| `int(n)` | Convert to integer |
+| `fract(n)` | Fractional part |
 | `vec(x, y)` | Create 2D vector |
 | `polygon(x, y, r, n)` | Draw n-sided polygon |
 | `star(x, y, r1, r2, n)` | Draw n-pointed star |
 | `fbm(x, y, z, octaves)` | Fractal Brownian motion |
-| `easeIn(t)`, `easeOut(t)`, etc. | Easing functions |
-
-### Control Functions
-
-| Function | Preview Behavior |
-|----------|------------------|
-| `noLoop()` | Stops preview loop (soft control) |
-| `loop()` | No-op in preview |
-
----
-
-## Supported Element Types
-
-### `background`
-
-Opinionated presets with guardrails.
-
-```typescript
-{
-  type: 'background',
-  style: 'gradient',  // gradient, solid, noise, grain
-  palette: 'warm'     // warm, cool, neutral, vibrant
-}
-```
-
-### `primitive`
-
-Declarative generative components. **30 primitives available:**
-
-**Categories:**
-- `basic` — dots, lines, waves, stripes, circles, grid
-- `geometric` — polygons, diamonds, hexgrid, stars, concentricSquares
-- `radial` — spirals, rays, orbits, rings, arcs, radialLines, petals
-- `flow` — flow, particles, bubbles
-- `patterns` — crosshatch, chevrons, zigzag, weave, moire
-- `organic` — curves, noise, mesh, branches
-
-```typescript
-{
-  type: 'primitive',
-  name: 'spirals',
-  count: 12,
-  color: '#ffffff',
-  motion: 'medium',
-  strokeWeight: 'thin',
-  opacity: 0.8
-}
-```
-
-### `sketch`
-
-Raw Code Mode execution.
-
-```typescript
-{
-  type: 'sketch',
-  code: `
-    function setup() { background(0); }
-    function draw() { ellipse(width/2, height/2, 100); }
-  `,
-  normalize: true
-}
-```
-
----
-
-## VAR Handling (Soft)
-
-VAR[0..9] is an array of 10 protocol variables.
-
-**Preview behavior (permissive):**
-- Input: 0-10 elements accepted (extras ignored with warning)
-- Values: Clamped to 0-100 (not rejected)
-- Invalid types: Replaced with 0 (not rejected)
-- Runtime: Always 10 elements (padded with zeros)
-- Access: Read-only
-
-```typescript
-// Works in preview (clamped to 100)
-vars: [150, 50, 50]  // VAR[0] becomes 100
-
-// Works in preview (non-numbers become 0)  
-vars: ['bad', 50, 50]  // VAR[0] becomes 0
-
-// Works in preview (extras ignored)
-vars: [1,2,3,4,5,6,7,8,9,10,11,12]  // Uses first 10
-```
-
-For strict validation, use `@nexart/codemode-sdk`.
+| `easeIn(t)`, `easeOut(t)` | Easing functions |
 
 ---
 
@@ -396,7 +323,7 @@ For strict validation, use `@nexart/codemode-sdk`.
 | Protocol enforcement | No pattern checking or validation errors |
 | Canonical output | Use @nexart/codemode-sdk for minting |
 | Determinism guarantee | Preview may vary slightly |
-| Full frame count | Limited to 30 frames max |
+| Full frame count | Limited by budget (default 1800 frames) |
 | Full resolution | Limited to 900px max dimension |
 
 ---

package/dist/capabilities.d.ts

@@ -1,5 +1,5 @@
 /**
- * @nexart/ui-renderer v0.8.0 - Capabilities Discovery
+ * @nexart/ui-renderer v0.9.0 - Capabilities Discovery
  *
  * Exposes SDK capabilities for AI tools and builders.
  * Lightweight preview runtime — no protocol enforcement.

package/dist/capabilities.js

@@ -1,5 +1,5 @@
 /**
- * @nexart/ui-renderer v0.8.0 - Capabilities Discovery
+ * @nexart/ui-renderer v0.9.0 - Capabilities Discovery
  *
  * Exposes SDK capabilities for AI tools and builders.
  * Lightweight preview runtime — no protocol enforcement.
@@ -58,7 +58,7 @@ function createPrimitive(name, category, description) {
 }
 export function getCapabilities() {
     return {
-        version: '0.8.0',
+        version: '0.9.0',
         isCanonical: false,
         isArchival: false,
         renderer: '@nexart/ui-renderer',