@nexart/ui-renderer 0.8.8 → 0.9.1

package/README.md

@@ -1,403 +1,371 @@
 # @nexart/ui-renderer
 
-Version: 0.8.7
+**Version: 0.9.1**
 
-**Lightweight Preview Runtime for NexArt Protocol**
+A browser-first bounded generative renderer for safe, fast, interactive visuals.
 
 ---
 
-> **This SDK is a PREVIEW RENDERER, not an authority.**
->
-> It provides fast, lightweight previews for development and prototyping.
->
-> It is:
-> - **NOT canonical** — Does not produce archival-quality output
-> - **NOT archival** — Not for minting, export, or permanent storage
-> - **NOT protocol-enforcing** — No validation errors, no pattern checking
->
-> For canonical output, minting, or validation: use `@nexart/codemode-sdk`
+## What This SDK Does
 
----
+This SDK provides a **bounded execution environment** for running generative code safely in the browser. It renders p5-like sketches with built-in safety limits:
 
-## 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.
+- **Resolution cap** — Max 900px dimension for performance
+- **Frame/time budgets** — Prevents runaway loops
+- **Observable state** — Know exactly what the runtime is doing
+- **Safe degradation** — Controlled behavior when limits hit
+
+**Output is authoritative within bounded constraints.** What you see is what the sketch produces at preview resolution with preview budgets.
 
 ---
 
-## v0.8.3 — Animation Loop Fix
+## Standalone Use Cases
 
-Fixed critical bug where preview only rendered a single frame.
+This SDK is designed for:
 
-- **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
+- **Generative art backgrounds** — Dynamic visuals for web pages
+- **Interactive creative coding editors** — Live preview while users code
+- **Dashboard visuals** — Procedural data visualizations
+- **Mini-app visuals** — Embedded generative elements
+- **Educational demos** — Safe sandbox for teaching creative coding
+- **UI-embedded procedural patterns** — Decorative generative elements
 
-**Animation Loop Invariant (locked for v0.x):**
-```
-RAF schedules → budget checks → draw executes (or skips) → repeat
-Never: budget check → stop loop
-```
+For these use cases, ui-renderer is the complete solution. No other SDK required.
 
 ---
 
-## v0.8.2 — Runtime Dimensions Fix
+## When to Escalate to Canonical Rendering
 
-Fixed critical bug where preview scaling affected `width`/`height` inside sketches.
+Use `@nexart/codemode-sdk` when you need:
 
-- **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
+- **Minting / export / archival** — Permanent, verifiable output
+- **Reproducibility guarantees** — Exact same output every time, anywhere
+- **Full resolution parity** — 1950×2400 or higher without scaling
+- **Verification workflows** — Cryptographic digest matching
 
-**Key rule enforced:** Preview scaling is a rendering concern, not a semantic one.
+**ui-renderer → codemode-sdk is an escalation, not a requirement.**
 
----
+Most interactive, preview, and display use cases are complete with ui-renderer alone.
 
-## v0.8.1 — Canvas Scaling Fix
+---
 
-Fixed canvas zoom/cropping bug caused by resolution downscaling in v0.8.0.
+## Authority Model
 
-- **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
+```
+┌─────────────────────────────────────────────────────────┐
+│  Your Application                                       │
+│  (React, Canvas, Three.js, editor, dashboard)           │
+└────────────────────────┬────────────────────────────────┘
+                         │
+                         ▼
+┌─────────────────────────────────────────────────────────┐
+│  @nexart/ui-renderer                                    │
+│  Bounded browser runtime                                │
+│  - Resolution scaling (max 900px)                       │
+│  - Frame/time budgets                                   │
+│  - Observable stats                                     │
+│  - Controlled degradation                               │
+└────────────────────────┬────────────────────────────────┘
+                         │
+                         ▼
+┌─────────────────────────────────────────────────────────┐
+│  Output                                                 │
+│  - Pixels on canvas                                     │
+│  - Runtime stats                                        │
+│  - Budget status                                        │
+│                                                         │
+│  ↳ Optional: toCanonicalRequest() for codemode-sdk      │
+└─────────────────────────────────────────────────────────┘
+```
 
 ---
 
-## v0.8.0 — Lightweight Preview Runtime
+## For AI Coding Agents (Replit / Lovable / Claude Code)
 
-This release refactors the UI renderer into a performance-optimized preview runtime.
+### 20-Second Quickstart
 
-### Philosophy Change
+```typescript
+import { createPreviewRuntime } 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 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),
+});
 
-### Preview Budget (MANDATORY)
+runtime.startLoop();
+```
 
-The runtime enforces hard limits to prevent browser freezes:
+### Detecting Runtime Mode
 
 ```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
-};
-```
-
-If limits exceeded: rendering stops silently (no throw).
+const stats = runtime.getPreviewStats();
 
-### Canvas Scaling
+console.log('Mode:', stats.mode);           // 'preview'
+console.log('Scale:', stats.scale);         // 0.46
+console.log('Frames:', stats.frames);       // current frame count
+console.log('Budget OK:', !stats.budgetExceeded);
+```
 
-Preview renderer scales large canvases automatically:
+### Handling Budget Limits
 
 ```typescript
-CANVAS_LIMITS = {
-  MAX_DIMENSION: 900,  // Max width/height in pixels
-  MIN_DIMENSION: 100,
-};
+const stats = runtime.getPreviewStats();
+
+if (stats.budgetExceeded) {
+  console.log('Reason:', stats.budgetExceeded.reason);
+  // Options:
+  // 1. Simplify sketch (fewer iterations)
+  // 2. Increase maxFrames or maxTimeMs
+  // 3. Use budgetBehavior: 'degrade' to continue with frame skipping
+}
 ```
 
-Aspect ratio is preserved. CSS scaling for display.
+---
 
-### Runtime Mode Flag
+## Trust & Safety
 
-The preview runtime exposes a `mode` property:
+### Budgets Prevent Runaway Code
 
 ```typescript
-runtime.mode // 'preview'
+const runtime = createPreviewRuntime({
+  canvas,
+  source: sketchCode,
+  mode: 'loop',
+  width: 1950,
+  height: 2400,
+  
+  maxFrames: 1800,        // Max frames before stop (default)
+  maxTimeMs: 300000,      // Max 5 minutes (default)
+  budgetBehavior: 'stop', // 'stop' or 'degrade'
+  showOverlay: true,      // Visual indicator when stopped
+  
+  onBudgetExceeded: (info) => {
+    // No silent failures — you always know
+    console.log('Stopped:', info.reason);
+  },
+});
 ```
 
-Use this to detect preview vs canonical rendering.
+### Observable State
 
----
+```typescript
+const stats = runtime.getPreviewStats();
+// {
+//   mode: 'preview',
+//   scale: 0.46,
+//   semanticWidth: 1950,
+//   semanticHeight: 2400,
+//   bufferWidth: 897,
+//   bufferHeight: 900,
+//   frames: 150,
+//   stride: 1,
+//   totalTimeMs: 18750,
+//   budgetExceeded?: { reason: 'frame_limit' | 'time_limit' }
+// }
+```
 
-## Install
+### What Can Differ vs Canonical
 
-```bash
-npm install @nexart/ui-renderer
-```
+| Aspect | ui-renderer | codemode-sdk |
+|--------|-------------|--------------|
+| Resolution | Scaled to max 900px | Full resolution |
+| Frame budget | 1800 frames / 5 min | Unlimited |
+| Fine details | May be lost at scale | Pixel-perfect |
+| Semantics | Consistent | Authoritative |
 
-Or use directly in HTML:
-```html
-<script type="module">
-  import { createSystem, previewSystem } from 'https://unpkg.com/@nexart/ui-renderer/dist/index.js';
-</script>
-```
+**Scaling may change fine details. Budgets may skip work. Core semantics are preserved.**
 
 ---
 
-## Quick Start
+## Bounded Execution vs Canonical
+
+| Aspect | Preview (this SDK) | Canonical (@nexart/codemode-sdk) |
+|--------|-------------------|----------------------------------|
+| **Purpose** | Fast browser visuals | Authoritative rendering |
+| **Resolution** | Max 900px | Full resolution |
+| **Budget** | 1800 frames / 5 min | Unlimited |
+| **Determinism** | Consistent | Guaranteed |
+| **Use for** | Editors, dashboards, display | Minting, export, archival |
+
+---
 
-### Code Mode Preview
+## Optional: Canonical Handoff
+
+When you need to escalate to canonical rendering:
 
 ```typescript
-import { createSystem, previewSystem } from '@nexart/ui-renderer';
+import { toCanonicalRequest } from '@nexart/ui-renderer';
+
+const config = { 
+  canvas, 
+  source: sketchCode, 
+  mode: 'loop', 
+  width: 1950, 
+  height: 2400, 
+  seed: 12345 
+};
 
-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 req = toCanonicalRequest(config);
 
-const canvas = document.getElementById('canvas');
-const renderer = previewSystem(system, canvas);
-renderer.start();
+// Pass to backend with @nexart/codemode-sdk:
+// await fetch('/api/render', { body: JSON.stringify(req) });
 ```
 
-### 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));
-      }
-    }
-  `
-});
+## Install
+
+```bash
+npm install @nexart/ui-renderer
+```
 
-previewSystem(staticSystem, canvas).render();
+Or use directly:
+```html
+<script type="module">
+  import { createPreviewRuntime } from 'https://unpkg.com/@nexart/ui-renderer/dist/index.js';
+</script>
 ```
 
 ---
 
 ## API Reference
 
-### `createSystem(input)`
+### `createPreviewRuntime(config)` — Recommended
 
-Create a NexArt system for preview.
+Create a bounded preview renderer.
 
 ```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,
+  vars?: number[],             // VAR[0..9] (0-100 range)
+  totalFrames?: number,        // For loop mode (default: 120)
+  
+  // Budget options
+  onBudgetExceeded?: (info: BudgetExceededInfo) => void,
+  budgetBehavior?: 'stop' | 'degrade',
+  showOverlay?: boolean,
+  maxFrames?: number,
+  maxTimeMs?: number,
 });
-```
-
-### `previewSystem(system, canvas, options?)`
-
-Render a preview to canvas.
 
-```typescript
-const renderer = previewSystem(system, canvas, {
-  showBadge: boolean  // default: true — shows "⚠️ Preview" badge
-});
-
-renderer.render();  // Single frame
-renderer.start();   // Start loop
-renderer.stop();    // Stop loop
-renderer.destroy(); // Cleanup
+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
 ```
 
-### `validateSystem(input)`
+### `toCanonicalRequest(config)`
 
-Soft validation — warns but doesn't throw for minor issues.
+Generate a handoff object for `@nexart/codemode-sdk`:
 
 ```typescript
-const result = validateSystem(input);
-if (!result.valid) {
-  console.log(result.errors);  // Structural issues only
-}
+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
+## Troubleshooting
 
-The preview runtime includes all standard p5-like functions plus:
+### "My sketch stops animating"
 
-| Helper | Description |
-|--------|-------------|
-| `int(n)` | Convert to integer (Math.floor) |
-| `fract(n)` | Fractional part of number |
-| `sign(n)` | Sign of number |
-| `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.
+Check `getPreviewStats().budgetExceeded`:
 
 ```typescript
-{
-  type: 'background',
-  style: 'gradient',  // gradient, solid, noise, grain
-  palette: 'warm'     // warm, cool, neutral, vibrant
+const stats = runtime.getPreviewStats();
+if (stats.budgetExceeded) {
+  console.log('Stopped because:', stats.budgetExceeded.reason);
 }
 ```
 
-### `primitive`
+**Solutions:**
+1. Reduce sketch complexity
+2. Increase budget: `maxFrames: 3600` or `maxTimeMs: 600000`
+3. Use `budgetBehavior: 'degrade'` to continue with frame skipping
 
-Declarative generative components. **30 primitives available:**
+### "Canvas is too small"
 
-**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
+Preview scales to max 900px for performance:
 
 ```typescript
-{
-  type: 'primitive',
-  name: 'spirals',
-  count: 12,
-  color: '#ffffff',
-  motion: 'medium',
-  strokeWeight: 'thin',
-  opacity: 0.8
-}
+const stats = runtime.getPreviewStats();
+console.log('Buffer:', stats.bufferWidth, 'x', stats.bufferHeight);
+console.log('Semantic:', stats.semanticWidth, 'x', stats.semanticHeight);
 ```
 
-### `sketch`
+Your sketch code sees original `width`/`height`. Canvas buffer is scaled.
 
-Raw Code Mode execution.
+### "Animation looks choppy"
 
-```typescript
-{
-  type: 'sketch',
-  code: `
-    function setup() { background(0); }
-    function draw() { ellipse(width/2, height/2, 100); }
-  `,
-  normalize: true
-}
-```
+1. Check if in degraded mode (skipping frames)
+2. Reduce sketch complexity
+3. Check browser performance
 
 ---
 
-## VAR Handling (Soft)
-
-VAR[0..9] is an array of 10 protocol variables.
+## Available Helpers
 
-**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
+All standard p5-like functions included:
 
-```typescript
-// Works in preview (clamped to 100)
-vars: [150, 50, 50]  // VAR[0] becomes 100
+| Helper | Description |
+|--------|-------------|
+| `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)` | Easing functions |
 
-// 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
-```
+## Legacy API
 
-For strict validation, use `@nexart/codemode-sdk`.
+Still supported for backward compatibility:
 
----
+```typescript
+import { createSystem, previewSystem } from '@nexart/ui-renderer';
 
-## What This SDK Does NOT Do
+const system = createSystem({
+  type: 'code',
+  mode: 'loop',
+  width: 1950,
+  height: 2400,
+  source: sketchCode,
+  seed: 12345,
+});
 
-| Not Done | Explanation |
-|----------|-------------|
-| 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 resolution | Limited to 900px max dimension |
+const renderer = previewSystem(system, canvas);
+renderer.start();
+```
 
 ---
 
@@ -412,6 +380,4 @@ For strict validation, use `@nexart/codemode-sdk`.
 
 ## License
 
-MIT License
-
-Copyright (c) 2024-2026 NexArt
+MIT License — Copyright (c) 2024-2026 NexArt

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.