@nexart/ui-renderer 0.3.1 → 0.4.0

package/README.md

@@ -1,36 +1,177 @@
 # @nexart/ui-renderer
 
-Version: 0.3.0
+Version: 0.4.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 (exactly 10 read-only variables)
+- 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 — LOCKED v1.0.0 (MIRROR)
+
+VAR[0..9] is a read-only array of 10 protocol variables (0-100 recommended).
+
+**VAR Specification (FROZEN — mirrors @nexart/codemode-sdk):**
+
+| Property | Value | Enforcement |
+|----------|-------|-------------|
+| Count | Exactly 10 (VAR[0]..VAR[9]) | HARD — throws if not 10 |
+| Type | number | HARD — throws if non-number |
+| Range | 0-100 recommended | SOFT — warns, does NOT clamp |
+| Mutability | Read-only | HARD — frozen, writes blocked |
+| Injection | Before execution | Guaranteed |
+| Lifecycle | Stable for entire render | Guaranteed |
+| Default | All zeros | If not provided |
+
+**This specification is INTENTIONAL and MUST NOT be extended in v1.x.**
+
+**DO NOT** add support for dynamic-length VAR arrays.  
+**DO NOT** allow user-defined VAR counts.
+
+```typescript
+// Correct usage
+const size = map(VAR[0], 0, 100, 10, 200);
+const count = floor(map(VAR[1], 0, 100, 5, 50));
+
+// Error: VAR is read-only
+VAR[0] = 50; // Blocked with warning
+```
+
+**Error examples:**
+```typescript
+// Protocol error: wrong length
+vars: [50, 50, 50] // "[Code Mode Protocol Error] VAR array must have exactly 10 elements"
+
+// Warning only: out of range (not clamped)
+vars: [150, 50, 50, 50, 50, 50, 50, 50, 50, 50] // Warns but allows
+```
+
+---
+
+## 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.
+
+```typescript
+{
+  type: 'primitive',
+  name: 'dots',       // dots, lines, waves, grid, flowField, orbits
+  count: 100,
+  color: '#ffffff',
+  motion: { speed: 0.5 }
+}
+```
+
+### `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 +192,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 +206,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 +214,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 +238,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 +254,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 +271,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] (10 values, 0-100)
 });
 ```
 
@@ -222,25 +292,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 +305,59 @@ if (!result.valid) {
 
 ### `getCapabilities()`
 
-Discover SDK capabilities — critical for AI tools and builders.
+Discover SDK capabilities.
 
 ```typescript
 import { getCapabilities } from '@nexart/ui-renderer';
 
 const caps = getCapabilities();
 // {
-//   version: '0.2.0',
+//   version: '0.4.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
+//   delegatesTo: '@nexart/codemode-sdk',
+//   protocolVersion: '1.0.0',
+//   ...
 // }
 ```
 
-Use this to:
-- Prevent AI hallucination of non-existent primitives
-- Validate parameter ranges before system creation
-- Build dynamic UIs that adapt to SDK capabilities
-
 ---
 
-## Primitive Vocabulary (v0.3)
-
-### Elements
-
-| 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 |
-
-### Background
-
-| Property | Options |
-|----------|---------|
-| color | Any CSS color or name |
-| texture | `none`, `noise`, `grain` |
-| gradient | `{ type, colors, angle? }` |
+## Delegation Logging
 
-### Motion
+All Code Mode previews log their delegation:
 
-| Source | Behavior |
-|--------|----------|
-| `none` | Static image |
-| `time` | Animate based on elapsed time |
-| `seed` | Static per seed |
+```
+[UIRenderer] Preview delegation → @nexart/codemode-sdk
+[UIRenderer] Protocol version: 1.0.0
+[UIRenderer] Mode: loop
+```
 
 ---
 
-## For AI Platforms
-
-This SDK is designed for AI code generation. Use `getCapabilities()` first:
-
-```typescript
-import { getCapabilities, createSystem, previewSystem } 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 }
-  ]
-});
+## Error Mirroring
 
-// 3. Preview
-previewSystem(system, canvas).render();
-```
+If the protocol rejects code:
+- Rendering stops immediately
+- Black canvas is displayed
+- Error is logged verbatim
+- No "best effort" recovery
 
-**AI Prompt Example:**
 ```
-"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 +368,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 +375,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`.

package/dist/preview/code-renderer.d.ts

@@ -1,17 +1,30 @@
 /**
- * @nexart/ui-renderer v0.3.0 - Code Mode Renderer
+ * @nexart/ui-renderer v0.4.0 - Code Mode Renderer
  *
- * Renders Code Mode systems using the canonical NexArt p5-like runtime.
- * This uses the exact same execution logic as nexart.xyz for determinism.
+ * ╔══════════════════════════════════════════════════════════════════════════╗
+ * ║  PREVIEW RENDERER — MIRRORS @nexart/codemode-sdk BEHAVIOR                ║
+ * ║                                                                          ║
+ * ║  This file is a MIRROR, not an authority.                                ║
+ * ║                                                                          ║
+ * ║  Authority: @nexart/codemode-sdk (Protocol v1.0.0)                       ║
+ * ╚══════════════════════════════════════════════════════════════════════════╝
+ *
+ * ARCHITECTURAL NOTE:
+ * -------------------
+ * Live preview animation requires local p5 runtime execution because:
+ * - @nexart/codemode-sdk.executeCodeMode() returns blobs (PNG/MP4), not frames
+ * - Real-time animation in the browser requires frame-by-frame canvas updates
+ * - The SDK's loop mode produces video files, not real-time rendering
+ *
+ * To ensure faithful mirroring, this renderer:
+ * 1. Uses identical forbidden pattern validation as the SDK
+ * 2. Uses identical VAR handling (read-only, 10 elements, 0-100 range, errors not clamps)
+ * 3. Uses identical seeded RNG (Mulberry32) and Perlin noise
+ * 4. Uses identical time variable semantics (frameCount, t, time, tGlobal)
+ *
+ * For archival/canonical output, use @nexart/codemode-sdk directly.
  */
 import type { NexArtCodeSystem, PreviewOptions } from '../types';
-interface P5Runtime {
-    [key: string]: any;
-    width: number;
-    height: number;
-    frameCount: number;
-}
-export declare function createP5Runtime(canvas: HTMLCanvasElement, width: number, height: number, seed: number): P5Runtime;
 export interface CodeRenderer {
     render: () => void;
     start: () => void;
@@ -20,6 +33,14 @@ export interface CodeRenderer {
     isCanonical: false;
     isArchival: false;
 }
+interface P5Runtime {
+    [key: string]: any;
+    width: number;
+    height: number;
+    frameCount: number;
+    VAR: readonly number[];
+}
+export declare function createP5Runtime(canvas: HTMLCanvasElement, width: number, height: number, seed: number, vars?: number[]): P5Runtime;
 export declare function renderCodeModeSystem(system: NexArtCodeSystem, canvas: HTMLCanvasElement, options?: PreviewOptions): CodeRenderer;
 export {};
 //# sourceMappingURL=code-renderer.d.ts.map

package/dist/preview/code-renderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"code-renderer.d.ts","sourceRoot":"","sources":["../../src/preview/code-renderer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAWjE,UAAU,SAAS;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AA4DD,wBAAgB,eAAe,CAC7B,MAAM,EAAE,iBAAiB,EACzB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACX,SAAS,CAueX;AASD,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,WAAW,EAAE,KAAK,CAAC;IACnB,UAAU,EAAE,KAAK,CAAC;CACnB;AAED,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE,iBAAiB,EACzB,OAAO,GAAE,cAAmB,GAC3B,YAAY,CAoMd"}
+{"version":3,"file":"code-renderer.d.ts","sourceRoot":"","sources":["../../src/preview/code-renderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAMjE,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,WAAW,EAAE,KAAK,CAAC;IACnB,UAAU,EAAE,KAAK,CAAC;CACnB;AA4CD,UAAU,SAAS;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,SAAS,MAAM,EAAE,CAAC;CACxB;AAgFD,wBAAgB,eAAe,CAC7B,MAAM,EAAE,iBAAiB,EACzB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,MAAM,EAAmC,GAC9C,SAAS,CA0eX;AAsCD,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE,iBAAiB,EACzB,OAAO,GAAE,cAAmB,GAC3B,YAAY,CA4Md"}