@nexart/ui-renderer 0.9.0 → 0.9.1

package/CHANGELOG.md

@@ -4,6 +4,38 @@ All notable changes to @nexart/ui-renderer will be documented in this file.
 
 ---
 
+## [0.9.1] — 2026-01-24
+
+### Changed — Documentation & Positioning
+
+**Non-Breaking, Metadata-Only Release**
+
+This release repositions ui-renderer as a standalone, browser-first generative renderer — not merely a companion to codemode-sdk.
+
+#### Documentation Reframed
+- **Standalone positioning** — SDK is now described as "browser-first bounded generative renderer"
+- **Removed "non-canonical" framing** — Replaced with "authoritative within bounded constraints"
+- **Added "Standalone use cases"** — Backgrounds, editors, dashboards, mini-apps, education
+- **Added "When to escalate"** — Minting, export, archival, verification
+- **Added "Authority model" diagram** — Clear visual of where this SDK fits
+- **Added "Trust & safety"** — Budgets, observability, what can differ
+- **Moved codemode-sdk references** — Now in escalation section, not primary framing
+
+#### Metadata Updates
+- **Description**: "Browser-first bounded generative renderer for safe, fast, interactive visuals"
+- **Keywords**: generative, renderer, canvas, creative-coding, preview, sandbox, bounded, runtime, miniapp
+- **Homepage**: Added to package.json
+
+### Unchanged
+
+- No changes to runtime behavior
+- No changes to APIs or exports
+- No changes to budget defaults
+- No changes to canvas scaling
+- Full backward compatibility with v0.9.0 and v0.8.x
+
+---
+
 ## [0.9.0] — 2026-01-24
 
 ### Added

package/README.md

@@ -1,21 +1,82 @@
 # @nexart/ui-renderer
 
-Version: 0.9.0
+**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:
+
+- **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.
+
+---
+
+## Standalone Use Cases
+
+This SDK is designed for:
+
+- **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
+
+For these use cases, ui-renderer is the complete solution. No other SDK required.
+
+---
+
+## When to Escalate to Canonical Rendering
+
+Use `@nexart/codemode-sdk` when you need:
+
+- **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
+
+**ui-renderer → codemode-sdk is an escalation, not a requirement.**
+
+Most interactive, preview, and display use cases are complete with ui-renderer alone.
+
+---
+
+## Authority Model
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  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      │
+└─────────────────────────────────────────────────────────┘
+```
 
 ---
 
@@ -46,63 +107,36 @@ const runtime = createPreviewRuntime({
 runtime.startLoop();
 ```
 
-Preview mode may visually differ due to scaling/budgets. For canonical output and verification, run the same code with `@nexart/codemode-sdk`.
-
-### Detecting Preview Mode
+### Detecting Runtime Mode
 
 ```typescript
 const stats = runtime.getPreviewStats();
 
-if (stats.mode === 'preview') {
-  console.log('Running in preview mode');
-  console.log('Scale:', stats.scale);
-  console.log('Frames:', stats.frames);
-}
+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);
 ```
 
-### Handling Budget Exceeded
+### Handling Budget Limits
 
 ```typescript
 const stats = runtime.getPreviewStats();
 
 if (stats.budgetExceeded) {
-  console.log('Exceeded:', stats.budgetExceeded.reason);
+  console.log('Reason:', 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
+  // 1. Simplify sketch (fewer iterations)
+  // 2. Increase maxFrames or maxTimeMs
+  // 3. Use budgetBehavior: 'degrade' to continue with frame skipping
 }
 ```
 
 ---
 
-## Preview vs Canonical
-
-| 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 |
+## Trust & Safety
 
-**Rule of thumb:**
-- Use **ui-renderer** for quick visual feedback during development
-- Use **codemode-sdk** for final output, minting, or any permanent storage
-
----
-
-## v0.9.0 — Budget Callbacks + Observability
-
-### New Features
-
-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
+### Budgets Prevent Runaway Code
 
 ```typescript
 const runtime = createPreviewRuntime({
@@ -112,99 +146,83 @@ const runtime = createPreviewRuntime({
   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
+  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) => {
-    console.log('Budget exceeded:', info.reason);
-    console.log('Frames:', info.framesRendered);
-    console.log('Time:', info.totalTimeMs);
+    // No silent failures — you always know
+    console.log('Stopped:', info.reason);
   },
 });
 ```
 
-### Preview Stats
+### Observable State
 
 ```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
+//   scale: 0.46,
+//   semanticWidth: 1950,
+//   semanticHeight: 2400,
+//   bufferWidth: 897,
+//   bufferHeight: 900,
+//   frames: 150,
+//   stride: 1,
+//   totalTimeMs: 18750,
 //   budgetExceeded?: { reason: 'frame_limit' | 'time_limit' }
 // }
 ```
 
-### Canonical Handoff
+### What Can Differ vs Canonical
 
-```typescript
-import { toCanonicalRequest } from '@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 |
 
-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) });
-```
+**Scaling may change fine details. Budgets may skip work. Core semantics are preserved.**
 
 ---
 
-## Troubleshooting
-
-### "My sketch stops animating"
-
-Check `getPreviewStats().budgetExceeded`:
+## Bounded Execution vs Canonical
 
-```typescript
-const stats = runtime.getPreviewStats();
-if (stats.budgetExceeded) {
-  console.log('Stopped because:', stats.budgetExceeded.reason);
-}
-```
+| 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 |
 
-**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 is too small"
+## Optional: Canonical Handoff
 
-Preview scales canvases to max 900px for performance:
+When you need to escalate to canonical rendering:
 
 ```typescript
-const stats = runtime.getPreviewStats();
-console.log('Buffer size:', stats.bufferWidth, 'x', stats.bufferHeight);
-console.log('Semantic size:', stats.semanticWidth, 'x', stats.semanticHeight);
-```
-
-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.
+import { toCanonicalRequest } from '@nexart/ui-renderer';
 
-### "Animation looks choppy"
+const config = { 
+  canvas, 
+  source: sketchCode, 
+  mode: 'loop', 
+  width: 1950, 
+  height: 2400, 
+  seed: 12345 
+};
 
-Preview runs at native RAF cadence (~60 FPS). If animations appear choppy:
+const req = toCanonicalRequest(config);
 
-1. Check if budget exceeded (degrade mode skips frames):
-```typescript
-const stats = runtime.getPreviewStats();
-if (stats.budgetExceeded && stats.stride > 1) {
-  console.log('Running in degraded mode, skipping frames');
-}
+// Pass to backend with @nexart/codemode-sdk:
+// await fetch('/api/render', { body: JSON.stringify(req) });
 ```
 
-2. Reduce sketch complexity (heavy draw() calls)
-3. Check browser performance (GPU acceleration, tab throttling)
-
 ---
 
 ## Install
@@ -213,7 +231,7 @@ if (stats.budgetExceeded && stats.stride > 1) {
 npm install @nexart/ui-renderer
 ```
 
-Or use directly in HTML:
+Or use directly:
 ```html
 <script type="module">
   import { createPreviewRuntime } from 'https://unpkg.com/@nexart/ui-renderer/dist/index.js';
@@ -224,9 +242,9 @@ Or use directly in HTML:
 
 ## API Reference
 
-### `createPreviewRuntime(config)` ⭐ Recommended
+### `createPreviewRuntime(config)` — Recommended
 
-Create a preview renderer. This is the recommended entrypoint.
+Create a bounded preview renderer.
 
 ```typescript
 const runtime = createPreviewRuntime({
@@ -235,11 +253,11 @@ const runtime = createPreviewRuntime({
   mode: 'static' | 'loop',
   width: number,
   height: number,
-  seed?: number,               // PRNG seed
+  seed?: number,
   vars?: number[],             // VAR[0..9] (0-100 range)
   totalFrames?: number,        // For loop mode (default: 120)
   
-  // v0.9.0 budget options
+  // Budget options
   onBudgetExceeded?: (info: BudgetExceededInfo) => void,
   budgetBehavior?: 'stop' | 'degrade',
   showOverlay?: boolean,
@@ -255,34 +273,11 @@ runtime.previewScale;          // Canvas scale factor
 runtime.destroy();             // Clean up
 ```
 
-### `createSystem(input)` + `previewSystem(system, canvas)`
-
-Legacy API for declarative systems. Still supported:
-
-```typescript
-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],
-});
-
-const renderer = previewSystem(system, canvas);
-renderer.start();
-```
-
 ### `toCanonicalRequest(config)`
 
-Generate a request object for handoff to `@nexart/codemode-sdk`:
+Generate a handoff object for `@nexart/codemode-sdk`:
 
 ```typescript
-import { toCanonicalRequest } from '@nexart/ui-renderer';
-
 const req = toCanonicalRequest(config);
 // { seed, vars, code, settings, renderer: 'preview', uiRendererVersion }
 ```
@@ -292,17 +287,53 @@ const req = toCanonicalRequest(config);
 Discover SDK capabilities:
 
 ```typescript
-import { getCapabilities } from '@nexart/ui-renderer';
-
 const caps = getCapabilities();
 // { version, isCanonical, previewBudget, canvasLimits, ... }
 ```
 
 ---
 
+## Troubleshooting
+
+### "My sketch stops animating"
+
+Check `getPreviewStats().budgetExceeded`:
+
+```typescript
+const stats = runtime.getPreviewStats();
+if (stats.budgetExceeded) {
+  console.log('Stopped because:', stats.budgetExceeded.reason);
+}
+```
+
+**Solutions:**
+1. Reduce sketch complexity
+2. Increase budget: `maxFrames: 3600` or `maxTimeMs: 600000`
+3. Use `budgetBehavior: 'degrade'` to continue with frame skipping
+
+### "Canvas is too small"
+
+Preview scales to max 900px for performance:
+
+```typescript
+const stats = runtime.getPreviewStats();
+console.log('Buffer:', stats.bufferWidth, 'x', stats.bufferHeight);
+console.log('Semantic:', stats.semanticWidth, 'x', stats.semanticHeight);
+```
+
+Your sketch code sees original `width`/`height`. Canvas buffer is scaled.
+
+### "Animation looks choppy"
+
+1. Check if in degraded mode (skipping frames)
+2. Reduce sketch complexity
+3. Check browser performance
+
+---
+
 ## Available Helpers
 
-The preview runtime includes all standard p5-like functions:
+All standard p5-like functions included:
 
 | Helper | Description |
 |--------|-------------|
@@ -316,15 +347,25 @@ The preview runtime includes all standard p5-like functions:
 
 ---
 
-## What This SDK Does NOT Do
+## Legacy API
 
-| 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 by budget (default 1800 frames) |
-| Full resolution | Limited to 900px max dimension |
+Still supported for backward compatibility:
+
+```typescript
+import { createSystem, previewSystem } from '@nexart/ui-renderer';
+
+const system = createSystem({
+  type: 'code',
+  mode: 'loop',
+  width: 1950,
+  height: 2400,
+  source: sketchCode,
+  seed: 12345,
+});
+
+const renderer = previewSystem(system, canvas);
+renderer.start();
+```
 
 ---
 
@@ -339,6 +380,4 @@ The preview runtime includes all standard p5-like functions:
 
 ## License
 
-MIT License
-
-Copyright (c) 2024-2026 NexArt
+MIT License — Copyright (c) 2024-2026 NexArt

package/dist/index.d.ts

@@ -65,7 +65,7 @@ export type { Capabilities, PrimitiveCapability, ParameterSpec, } from './capabi
  * ```
  */
 export { createPreviewEngine as createPreviewRuntime } from './preview/preview-engine';
-export declare const SDK_VERSION = "0.9.0";
+export declare const SDK_VERSION = "0.9.1";
 export declare const PROTOCOL_VERSION = "0.9";
 export declare const IS_CANONICAL = false;
 export declare const IS_ARCHIVAL = false;

package/dist/index.js

@@ -65,7 +65,7 @@ export { AESTHETIC_DEFAULTS, SDK_VERSION as TYPE_SDK_VERSION } from './types';
  * ```
  */
 export { createPreviewEngine as createPreviewRuntime } from './preview/preview-engine';
-export const SDK_VERSION = '0.9.0';
+export const SDK_VERSION = '0.9.1';
 export const PROTOCOL_VERSION = '0.9';
 export const IS_CANONICAL = false;
 export const IS_ARCHIVAL = false;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nexart/ui-renderer",
-  "version": "0.9.0",
-  "description": "Lightweight Preview Runtime for NexArt Protocol. Non-canonical, browser-first, with budget callbacks and observability for AI coding agents.",
+  "version": "0.9.1",
+  "description": "Browser-first bounded generative renderer for safe, fast, interactive visuals. Resolution scaling, frame budgets, observable state.",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -33,21 +33,24 @@
     "typescript": "^5.0.0"
   },
   "keywords": [
-    "nexart",
-    "generative-art",
+    "generative",
+    "renderer",
     "canvas",
-    "browser",
-    "declarative",
-    "protocol",
-    "authoring",
+    "creative-coding",
     "preview",
-    "ai-agent",
-    "deterministic"
+    "sandbox",
+    "bounded",
+    "runtime",
+    "miniapp",
+    "browser",
+    "deterministic",
+    "ai-agent"
   ],
   "repository": {
     "type": "git",
     "url": "https://github.com/artnames/nexart-ui-renderer.git"
   },
+  "homepage": "https://github.com/artnames/nexart-ui-renderer#readme",
   "author": "NexArt",
   "publishConfig": {
     "access": "public"