@nexart/ui-renderer 0.3.1 → 0.6.0

package/README.md

@@ -1,36 +1,225 @@
 # @nexart/ui-renderer
 
-Version: 0.3.0
+Version: 0.6.0
 
 **Declarative and Code Mode System Authoring SDK for NexArt Protocol**
 
 ---
 
-> ⚠️ **IMPORTANT DISCLAIMER**
+> **This SDK is a PREVIEW MIRROR, not an authority.**
 >
-> **This SDK is for authoring and preview only.**
-> **Canonical, archival output is produced exclusively by @nexart/codemode-sdk.**
+> It mirrors the behavior of @nexart/codemode-sdk faithfully for preview purposes.
 >
-> This SDK is:
+> It is:
 > - **NOT canonical** — Does not produce archival-quality output
-> - **NOT archival** — Not suitable for NFT minting
-> - **NOT protocol-authoritative** — Best-effort rendering only
+> - **NOT archival** — Not the source of truth for production rendering
+> - **NOT protocol-authoritative** — Delegates all Code Mode execution semantics
 >
-> Same system → same preview output within this SDK, but **preview ≠ mint truth**.
+> Same inputs → same restrictions → same errors → same semantics as @nexart/codemode-sdk.
 
 ---
 
-## Philosophy
+## PROTOCOL LOCK — v1.0.0 (MIRROR)
 
-The NexArt Protocol defines how generative art systems work. This SDK provides:
+| Property | Value |
+|----------|-------|
+| Protocol Name | NexArt Code Mode |
+| Version | v1.0.0 |
+| Status | **HARD LOCKED** |
+| This SDK | Mirror only — NOT authoritative |
+| Canonical Authority | @nexart/codemode-sdk |
+| Lock Date | December 2024 |
 
-1. **System Authoring** — Declarative API to define NexArt systems
-2. **Preview Rendering** — Visual approximation in the browser
-3. **Compilation** — Export protocol-compatible JSON for canonical execution
+**This SDK mirrors the frozen v1.0.0 protocol surface. Any future protocol change requires v2.0.0 in @nexart/codemode-sdk first.**
 
-This SDK exists to **reduce friction** for builders, artists, and AI platforms. It is the front door to the NexArt Protocol — not the authority.
+This SDK mirrors:
+- Execution model (Static and Loop modes)
+- VAR[0..9] specification (0-10 input, always 10 at runtime)
+- Determinism behavior (seed + VAR → consistent preview)
+- Time semantics (t, frameCount, time, tGlobal)
+- Forbidden patterns list (13 patterns)
+- Error message format (`[Code Mode Protocol Error]`)
 
-**Canonical execution happens via `@nexart/codemode-sdk`.**
+---
+
+## Protocol Alignment (v1.0.0)
+
+This SDK mirrors NexArt Protocol behavior. It is NOT canonical.
+
+**Canonical execution is performed exclusively by @nexart/codemode-sdk.**
+
+This SDK exists for:
+- Preview and prototyping
+- Tooling and AI builders
+- Development and experimentation
+
+### Authority Boundaries
+
+| Aspect | This SDK | @nexart/codemode-sdk |
+|--------|----------|---------------------|
+| Authority | None — mirror only | Canonical gate |
+| Determinism | Mirrors protocol RNG | Authoritative RNG |
+| VAR Handling | Protocol-aligned (read-only, 0-100) | Authoritative enforcement |
+| Error Behavior | Mirrors protocol errors | Defines protocol errors |
+| Output | Preview-quality | Archival-quality |
+
+### HARD Enforcement Modes
+
+This SDK mirrors the following protocol-enforced modes:
+- **Code Mode** — Seeded RNG, VAR[0..9], forbidden patterns
+- **SoundArt** — Audio-to-visual transformation via Code Mode
+- **Noise** — Perlin/Cellular noise via Code Mode
+- **Shapes** — Geometric generation via Code Mode
+
+### Forbidden Patterns
+
+The following patterns are rejected (mirroring @nexart/codemode-sdk exactly):
+
+- `setTimeout`, `setInterval`, `requestAnimationFrame` — async timing
+- `Date.now()`, `new Date()` — time-based entropy
+- `Math.random()` — use `random()` instead (seeded)
+- `fetch()`, `XMLHttpRequest` — external IO
+- `createCanvas()` — canvas is pre-initialized
+- `document.*`, `window.*` — DOM access forbidden
+- `import`, `require()` — external imports forbidden
+
+### VAR Protocol — v1.0.0 (MIRROR of SDK v1.1.0)
+
+VAR[0..9] is a read-only array of 10 protocol variables (0-100 strict range).
+
+**VAR Specification (mirrors @nexart/codemode-sdk v1.1.0):**
+
+| Property | Value | Enforcement |
+|----------|-------|-------------|
+| Input count | 0-10 (VAR[0]..VAR[9]) | HARD — throws if > 10 |
+| Runtime count | Always 10 | Padded with zeros |
+| Type | finite number | HARD — throws if non-number |
+| Range | 0-100 | HARD — throws if out of range |
+| Mutability | Read-only | HARD — frozen, writes throw |
+| Injection | Before execution | Guaranteed |
+| Lifecycle | Stable for entire render | Guaranteed |
+| Default | All zeros | If not provided |
+
+**This specification mirrors @nexart/codemode-sdk v1.1.0 exactly.**
+
+```typescript
+// Correct usage
+const size = map(VAR[0], 0, 100, 10, 200);
+const count = floor(map(VAR[1], 0, 100, 5, 50));
+
+// VAR[5] returns 0 if input had fewer than 6 elements
+const value = VAR[5]; // Returns 0 if not provided
+
+// Error: VAR is read-only
+VAR[0] = 50; // Throws: "[Code Mode Protocol Error] VAR is read-only..."
+```
+
+**Error examples:**
+```typescript
+// Protocol error: too many elements
+vars: [1,2,3,4,5,6,7,8,9,10,11] // Throws: "VAR array must have at most 10 elements, got 11"
+
+// Protocol error: out of range
+vars: [150, 50, 50] // Throws: "VAR[0] = 150 is out of range. Values must be 0-100."
+
+// Valid: fewer than 10 elements (padded with zeros)
+vars: [50, 75, 25] // Works! VAR[3..9] will be 0
+```
+
+---
+
+## Supported Element Types
+
+The SDK supports three element types, rendered in order:
+
+### `background`
+
+Opinionated presets with guardrails. Provides consistent, protocol-aligned backgrounds.
+
+```typescript
+{
+  type: 'background',
+  style: 'gradient',  // gradient, solid, noise, grain
+  palette: 'warm'     // warm, cool, neutral, vibrant
+}
+```
+
+### `primitive`
+
+Declarative generative components. Structured parameters, no raw code. **30 primitives available:**
+
+**Basic Shapes:**
+- `dots` — Grid/random dot patterns
+- `lines` — Vertical wavy lines
+- `waves` — Horizontal wave patterns
+- `stripes` — Simple horizontal stripes
+- `circles` — Concentric pulsing circles
+- `grid` — Rotating square grid
+
+**Geometric:**
+- `polygons` — Random rotating polygons (3-7 sides)
+- `diamonds` — Diamond grid with noise rotation
+- `hexgrid` — Honeycomb hexagonal grid
+- `stars` — Scattered rotating star shapes
+- `concentricSquares` — Nested rotating squares
+
+**Radial:**
+- `spirals` — Multiple expanding spirals
+- `rays` — Lines emanating from center
+- `orbits` — Wobbling orbital rings
+- `rings` — Alternating concentric rings
+- `arcs` — Random partial circles
+- `radialLines` — Lines from inner to outer radius
+- `petals` — Flower petal pattern
+
+**Flow & Motion:**
+- `flow` — Particle flow field
+- `particles` — Scattered particles with tails
+- `bubbles` — Rising floating bubbles
+
+**Patterns:**
+- `crosshatch` — Cross-hatched shading lines
+- `chevrons` — V-shaped wave patterns
+- `zigzag` — Zigzag horizontal lines
+- `weave` — Interlocking woven pattern
+- `moire` — Overlapping circle interference
+
+**Organic:**
+- `curves` — Random bezier curves
+- `noise` — Perlin noise vector field
+- `mesh` — Deformed triangular mesh
+- `branches` — Fractal tree branches
+
+```typescript
+{
+  type: 'primitive',
+  name: 'spirals',    // Any of the 30 primitives above
+  count: 12,
+  color: '#ffffff',
+  motion: 'medium',   // 'slow', 'medium', 'fast'
+  strokeWeight: 'thin', // 'thin', 'medium', 'thick', or number
+  opacity: 0.8
+}
+```
+
+### `sketch`
+
+Raw Code Mode execution in a sandboxed environment. Full p5-like API access.
+
+```typescript
+{
+  type: 'sketch',
+  code: `
+    function setup() {
+      background(0);
+    }
+    function draw() {
+      ellipse(width/2, height/2, 100);
+    }
+  `,
+  normalize: true
+}
+```
 
 ---
 
@@ -51,9 +240,9 @@ Or use directly in HTML:
 
 ## Quick Start
 
-### Code Mode Systems (v0.3+)
+### Code Mode Systems with VAR
 
-Create and preview Code Mode sketches with deterministic rendering:
+Create and preview Code Mode sketches using protocol variables:
 
 ```typescript
 import { createSystem, previewSystem } from '@nexart/ui-renderer';
@@ -65,6 +254,7 @@ const system = createSystem({
   height: 2400,
   totalFrames: 120,
   seed: 12345,
+  vars: [50, 75, 25, 0, 100, 50, 50, 50, 50, 50], // VAR[0..9]
   source: `
     function setup() {
       noFill();
@@ -72,8 +262,9 @@ const system = createSystem({
     }
     function draw() {
       background(246, 245, 242);
-      for (var i = 0; i < 10; i++) {
-        var x = width / 2 + cos(t * TWO_PI + i * 0.5) * 200;
+      var count = floor(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);
       }
@@ -95,11 +286,13 @@ const staticSystem = createSystem({
   width: 1950,
   height: 2400,
   seed: 12345,
+  vars: [50, 50, 50, 50, 50, 50, 50, 50, 50, 50],
   source: `
     function setup() {
       background(246, 245, 242);
       fill(0);
-      for (var i = 0; i < 100; i++) {
+      var count = floor(map(VAR[0], 0, 100, 10, 200));
+      for (var i = 0; i < count; i++) {
         ellipse(random(width), random(height), random(10, 50));
       }
     }
@@ -109,60 +302,6 @@ const staticSystem = createSystem({
 previewSystem(staticSystem, canvas).render();
 ```
 
-### Declarative Systems
-
-### 1. Create a System
-
-```typescript
-import { createSystem } from '@nexart/ui-renderer';
-
-const system = createSystem({
-  seed: 29445825,
-  background: {
-    color: 'blue',
-    texture: 'noise'
-  },
-  elements: [
-    {
-      type: 'waves',
-      axis: 'x',
-      amplitude: 0.4,
-      frequency: 0.7
-    },
-    {
-      type: 'dots',
-      distribution: 'radial',
-      count: 400,
-      size: [1, 4]
-    }
-  ],
-  motion: {
-    source: 'time',
-    speed: 0.2
-  }
-});
-```
-
-### 2. Preview the System
-
-```typescript
-import { previewSystem } from '@nexart/ui-renderer';
-
-const canvas = document.getElementById('canvas');
-const renderer = previewSystem(system, canvas, { mode: 'loop' });
-
-renderer.start();
-```
-
-### 3. Compile for Protocol
-
-```typescript
-import { compileSystem } from '@nexart/ui-renderer';
-
-const compiled = compileSystem(system);
-console.log(JSON.stringify(compiled, null, 2));
-```
-
 ---
 
 ## API Reference
@@ -180,29 +319,8 @@ const system = createSystem({
   height: number,
   source: string,           // Raw p5-like sketch code
   seed?: number,            // Optional: PRNG seed
-  totalFrames?: number      // Required for loop mode
-});
-```
-
-**Declarative Input:**
-```typescript
-const system = createSystem({
-  version?: string,        // Protocol version (default: '0.3')
-  seed: number,            // Required: PRNG seed
-  background: {
-    color: string,         // Required: background color
-    texture?: 'none' | 'noise' | 'grain',
-    gradient?: {
-      type: 'linear' | 'radial',
-      colors: string[],
-      angle?: number
-    }
-  },
-  elements: SystemElement[], // Required: array of primitives
-  motion?: {
-    source: 'none' | 'time' | 'seed',
-    speed?: number
-  }
+  totalFrames?: number,     // Required for loop mode
+  vars?: number[]           // Optional: VAR[0..9] (0-10 values, 0-100 range)
 });
 ```
 
@@ -222,25 +340,6 @@ renderer.stop();    // Stop loop
 renderer.destroy(); // Cleanup
 ```
 
-### `compileSystem(system)`
-
-Compile to protocol-compatible JSON.
-
-```typescript
-const compiled = compileSystem(system);
-// {
-//   protocol: 'nexart',
-//   systemVersion: '0.2',
-//   seed: 29445825,
-//   background: {...},
-//   elements: [...],
-//   motion: {...},
-//   deterministic: true,
-//   compiledAt: '2024-12-26T...',
-//   compilerVersion: '0.2.0'
-// }
-```
-
 ### `validateSystem(input)`
 
 Validate system input without creating.
@@ -254,98 +353,170 @@ if (!result.valid) {
 
 ### `getCapabilities()`
 
-Discover SDK capabilities — critical for AI tools and builders.
+Discover SDK capabilities for AI and tooling.
 
 ```typescript
 import { getCapabilities } from '@nexart/ui-renderer';
 
 const caps = getCapabilities();
 // {
-//   version: '0.2.0',
+//   version: '0.6.0',
 //   isCanonical: false,
 //   isArchival: false,
 //   renderer: '@nexart/ui-renderer',
-//   primitives: [...],     // Available element types with parameters
-//   background: {...},     // Background options
-//   motion: {...},         // Motion sources and speed
-//   limits: {...}          // Max values for safety
+//   primitivesMeta: { notice: '...', count: 30, isCanonical: false },
+//   primitives: [ { name, category, description, parameters } ],
+//   ...
 // }
 ```
 
-Use this to:
-- Prevent AI hallucination of non-existent primitives
-- Validate parameter ranges before system creation
-- Build dynamic UIs that adapt to SDK capabilities
+### `getPrimitiveTypes()`
 
----
+Get all 30 primitive names as array.
 
-## Primitive Vocabulary (v0.3)
+```typescript
+import { getPrimitiveTypes } from '@nexart/ui-renderer';
 
-### Elements
+const names = getPrimitiveTypes();
+// ['dots', 'lines', 'waves', 'stripes', ... ]
+```
 
-| Type | Properties |
-|------|------------|
-| `dots` | distribution, count, size, color, opacity |
-| `lines` | direction, count, thickness, color, opacity |
-| `waves` | axis, amplitude, frequency, count, color, opacity |
-| `grid` | rows, cols, cellSize, shape, color, opacity |
-| `flowField` | resolution, strength, particles, color, opacity |
-| `orbits` | count, radius, dotCount, speed, color, opacity |
+### `getPrimitivesByCategory()`
 
-### Background
+Get primitives organized by category.
+
+```typescript
+import { getPrimitivesByCategory } from '@nexart/ui-renderer';
+
+const byCategory = getPrimitivesByCategory();
+// {
+//   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']
+// }
+```
 
-| Property | Options |
-|----------|---------|
-| color | Any CSS color or name |
-| texture | `none`, `noise`, `grain` |
-| gradient | `{ type, colors, angle? }` |
+### `getPrimitiveInfo(name)`
+
+Get full capability info for a single primitive.
+
+```typescript
+import { getPrimitiveInfo } from '@nexart/ui-renderer';
+
+const info = getPrimitiveInfo('spirals');
+// {
+//   name: 'spirals',
+//   category: 'radial',
+//   description: 'Multiple expanding spirals from center',
+//   compilesTo: 'codemode',
+//   isCanonical: false,
+//   parameters: { count, color, opacity, strokeWeight, motion }
+// }
+```
 
-### Motion
+### `isPrimitiveValid(name)`
 
-| Source | Behavior |
-|--------|----------|
-| `none` | Static image |
-| `time` | Animate based on elapsed time |
-| `seed` | Static per seed |
+Check if a primitive name is valid.
+
+```typescript
+import { isPrimitiveValid } from '@nexart/ui-renderer';
+
+isPrimitiveValid('spirals');  // true
+isPrimitiveValid('invalid');  // false
+```
 
 ---
 
-## For AI Platforms
+## AI Capabilities API
+
+**Designed for AI agents to build valid systems without hallucination.**
 
-This SDK is designed for AI code generation. Use `getCapabilities()` first:
+⚠️ **Primitives are helper generators that compile to Code Mode sketches.**
+They are NOT canonical. The canonical output is always the compiled Code Mode source.
+
+### For AI Agents
 
 ```typescript
-import { getCapabilities, createSystem, previewSystem } from '@nexart/ui-renderer';
+import { getCapabilities, isPrimitiveValid, getPrimitiveInfo } from '@nexart/ui-renderer';
 
-// 1. Check what's available (prevents hallucination)
 const caps = getCapabilities();
-console.log(caps.primitives.map(p => p.type));
-// ['dots', 'lines', 'waves', 'grid', 'flowField', 'orbits']
 
-// 2. Create system using only valid primitives
-const system = createSystem({
-  seed: Date.now(),
-  background: { color: 'blue' },
-  elements: [
-    { type: 'waves', axis: 'x', amplitude: 0.5, frequency: 1 }
-  ]
-});
+caps.primitivesMeta.notice;     // "Primitives are helper generators..."
+caps.primitivesMeta.count;      // 30
+caps.primitivesMeta.isCanonical; // false
+
+for (const p of caps.primitives) {
+  console.log(p.name);                    // 'dots', 'spirals', etc.
+  console.log(p.category);                // 'basic', 'radial', etc.
+  console.log(p.description);             // Human-readable description
+  console.log(p.parameters.count.min);    // 3
+  console.log(p.parameters.count.max);    // 50
+  console.log(p.parameters.count.default); // 12
+}
+```
+
+### Primitive Parameter Specification
+
+All primitives share these parameters:
+
+| Parameter | Type | Required | Range | Default |
+|-----------|------|----------|-------|---------|
+| `count` | number | No | 3-50 | 12 |
+| `color` | string | No | CSS color | Palette foreground |
+| `opacity` | number | No | 0.1-1 | 1 |
+| `strokeWeight` | enum | No | 'auto', 'thin', 'medium', 'thick' | 'auto' |
+| `motion` | enum | No | 'slow', 'medium', 'fast' | 'slow' |
+
+### Valid Primitive Categories
+
+| Category | Primitives |
+|----------|-----------|
+| `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 |
+
+---
 
-// 3. Preview
-previewSystem(system, canvas).render();
+## Delegation Logging
+
+All Code Mode previews log their delegation:
+
+```
+[UIRenderer] Preview delegation → @nexart/codemode-sdk
+[UIRenderer] Protocol version: 1.0.0
+[UIRenderer] Mode: loop
 ```
 
-**AI Prompt Example:**
+---
+
+## Error Mirroring
+
+If the protocol rejects code:
+- Rendering stops immediately
+- Black canvas is displayed
+- Error is logged verbatim
+- No "best effort" recovery
+
 ```
-"Create a blue background with flowing waves using NexArt"
+[UIRenderer Protocol Error] Forbidden pattern: Math.random() — use random() instead (seeded)
 ```
 
-The finite vocabulary prevents invalid systems and ensures protocol alignment.
+---
+
+## What This SDK Does NOT Guarantee
 
-**Key AI Integration Points:**
-- `getCapabilities()` — Discover what's possible
-- `validateSystem()` — Check before creating
-- `compileSystem()` — Export protocol JSON
+| Not Guaranteed | Explanation |
+|----------------|-------------|
+| Canonical output | Production runtime is the only authority |
+| Archival quality | Output is for preview, not permanent storage |
+| Cross-version stability | Internal rendering may change between SDK versions |
+| Frame-perfect matching | Minor differences from production are expected |
 
 ---
 
@@ -356,21 +527,6 @@ The finite vocabulary prevents invalid systems and ensures protocol alignment.
 - Safari 13+
 - Edge 80+
 
-No polyfills required.
-
----
-
-## Comparison with @nexart/codemode-sdk
-
-| Feature | @nexart/ui-renderer | @nexart/codemode-sdk |
-|---------|---------------------|----------------------|
-| Environment | Browser only | Node.js / Server |
-| Purpose | Authoring / Preview | Production / Minting |
-| Canonical | ❌ No | ✅ Yes |
-| Archival | ❌ No | ✅ Yes |
-| Output | Canvas / JSON | PNG / MP4 buffers |
-| API | Declarative systems | Code execution |
-
 ---
 
 ## License
@@ -378,8 +534,3 @@ No polyfills required.
 MIT License
 
 Copyright (c) 2024 NexArt
-
----
-
-> **Reminder:** This SDK authors systems. It does NOT invent new rendering rules.
-> Canonical execution always happens via `@nexart/codemode-sdk`.