@nexart/ui-renderer 0.1.0 → 0.2.1

package/README.md

@@ -1,40 +1,36 @@
 # @nexart/ui-renderer
 
-Version: 0.1.0
+Version: 0.2.1
 
-**Browser-first UI renderer for exploratory generative art.**
+**Declarative System Authoring SDK for NexArt Protocol**
 
 ---
 
 > ⚠️ **IMPORTANT DISCLAIMER**
 >
-> **This SDK is for exploration and UI rendering only.**
+> **This SDK is for authoring and preview only.**
 > **Canonical, archival output is produced exclusively by @nexart/codemode-sdk.**
 >
-> This renderer is:
-> - **NOT canonical**
-> - **NOT archival**
-> - **NOT protocol-authoritative**
+> This SDK is:
+> - **NOT canonical** — Does not produce archival-quality output
+> - **NOT archival** — Not suitable for NFT minting
+> - **NOT protocol-authoritative** — Best-effort rendering only
 >
-> Use it for demos, playgrounds, miniapps, and experimentation.
+> Same system → same preview output within this SDK, but **preview ≠ mint truth**.
 
 ---
 
-## What This SDK Is
+## Philosophy
 
-A lightweight, browser-first renderer for NexArt-style generative art:
+The NexArt Protocol defines how generative art systems work. This SDK provides:
 
-- Works in browsers, Vite, React, plain HTML
-- Uses deterministic PRNG for reproducible visuals
-- Renders abstract flow fields, vortices, and orbital motion
-- Zero dependencies
-- No Node.js required
+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
 
-## What This SDK Is NOT
+This SDK exists to **reduce friction** for builders, artists, and AI platforms. It is the front door to the NexArt Protocol — not the authority.
 
-- **Not canonical** — Does not produce archival-quality output
-- **Not for NFT minting** — Use `@nexart/codemode-sdk` for production mints
-- **Not protocol-enforcing** — Best-effort determinism only
+**Canonical execution happens via `@nexart/codemode-sdk`.**
 
 ---
 
@@ -47,7 +43,7 @@ npm install @nexart/ui-renderer
 Or use directly in HTML:
 ```html
 <script type="module">
-  import { createUIRenderer } from 'https://unpkg.com/@nexart/ui-renderer/dist/index.js';
+  import { createSystem, previewSystem } from 'https://unpkg.com/@nexart/ui-renderer/dist/index.js';
 </script>
 ```
 
@@ -55,119 +51,232 @@ Or use directly in HTML:
 
 ## Quick Start
 
-```typescript
-import { createUIRenderer } from '@nexart/ui-renderer';
-
-const canvas = document.getElementById('canvas') as HTMLCanvasElement;
+### 1. Create a System
 
-const renderer = createUIRenderer({
-  canvas,
-  seed: Date.now(),
-  mode: 'static',
-  width: 800,
-  height: 800,
+```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
+  }
 });
-
-// Render once
-renderer.render();
-
-// Or start animation loop
-// renderer.start();
 ```
 
----
+### 2. Preview the System
+
+```typescript
+import { previewSystem } from '@nexart/ui-renderer';
 
-## API
+const canvas = document.getElementById('canvas');
+const renderer = previewSystem(system, canvas, { mode: 'loop' });
 
-### `createUIRenderer(options)`
+renderer.start();
+```
 
-Create a renderer instance.
+### 3. Compile for Protocol
 
 ```typescript
-const renderer = createUIRenderer({
-  canvas: HTMLCanvasElement,  // Required: target canvas
-  seed: number,               // Required: PRNG seed
-  mode: 'static' | 'loop',    // Required: render mode
-  width?: number,             // Optional: canvas width (default: canvas.width)
-  height?: number,            // Optional: canvas height (default: canvas.height)
-});
+import { compileSystem } from '@nexart/ui-renderer';
+
+const compiled = compileSystem(system);
+console.log(JSON.stringify(compiled, null, 2));
 ```
 
-### Renderer Methods
+---
 
-| Method | Description |
-|--------|-------------|
-| `render()` | Render a single static frame |
-| `start()` | Start animation loop (loop mode) |
-| `stop()` | Stop animation loop |
-| `setSeed(newSeed)` | Change seed and re-render |
-| `destroy()` | Clean up resources |
+## API Reference
 
-### Renderer Properties
+### `createSystem(input)`
 
-| Property | Value | Description |
-|----------|-------|-------------|
-| `isCanonical` | `false` | Always false - this is not canonical |
-| `isArchival` | `false` | Always false - this is not archival |
+Create a validated NexArt system.
 
----
+```typescript
+const system = createSystem({
+  version?: string,        // Protocol version (default: '0.2')
+  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
+  }
+});
+```
 
-## Examples
+### `previewSystem(system, canvas, options?)`
 
-### Static Render
+Render a visual preview.
 
 ```typescript
-const renderer = createUIRenderer({
-  canvas: document.querySelector('canvas'),
-  seed: 12345,
-  mode: 'static',
+const renderer = previewSystem(system, canvas, {
+  mode: 'static' | 'loop',  // default: 'static'
+  showBadge: boolean        // default: true
 });
 
-renderer.render();
+renderer.render();  // Single frame
+renderer.start();   // Animation loop
+renderer.stop();    // Stop loop
+renderer.destroy(); // Cleanup
 ```
 
-### Animated Loop
+### `compileSystem(system)`
+
+Compile to protocol-compatible JSON.
 
 ```typescript
-const renderer = createUIRenderer({
-  canvas: document.querySelector('canvas'),
-  seed: Date.now(),
-  mode: 'loop',
-});
+const compiled = compileSystem(system);
+// {
+//   protocol: 'nexart',
+//   systemVersion: '0.2',
+//   seed: 29445825,
+//   background: {...},
+//   elements: [...],
+//   motion: {...},
+//   deterministic: true,
+//   compiledAt: '2024-12-26T...',
+//   compilerVersion: '0.2.0'
+// }
+```
 
-renderer.start();
+### `validateSystem(input)`
+
+Validate system input without creating.
 
-// Stop after 10 seconds
-setTimeout(() => renderer.stop(), 10000);
+```typescript
+const result = validateSystem(input);
+if (!result.valid) {
+  console.error(result.errors);
+}
 ```
 
-### Re-render with New Seed
+### `getCapabilities()`
+
+Discover SDK capabilities — critical for AI tools and builders.
 
 ```typescript
-// Generate new art every 30 seconds
-setInterval(() => {
-  renderer.setSeed(Date.now());
-}, 30000);
+import { getCapabilities } from '@nexart/ui-renderer';
+
+const caps = getCapabilities();
+// {
+//   version: '0.2.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
+// }
 ```
 
+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.2)
+
+### 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? }` |
+
+### Motion
+
+| Source | Behavior |
+|--------|----------|
+| `none` | Static image |
+| `time` | Animate based on elapsed time |
+| `seed` | Static per seed |
+
 ---
 
-## Visual Style
+## For AI Platforms
 
-The renderer produces abstract generative art featuring:
+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 }
+  ]
+});
+
+// 3. Preview
+previewSystem(system, canvas).render();
+```
+
+**AI Prompt Example:**
+```
+"Create a blue background with flowing waves using NexArt"
+```
 
-- **Flow fields** — Particle traces following noise-based vector fields
-- **Vortex patterns** — Spiral motion around canvas center
-- **Orbital elements** — Dots moving in elliptical paths
-- **Central glow** — Radial gradient for depth
+The finite vocabulary prevents invalid systems and ensures protocol alignment.
 
-Colors are derived from the seed, creating unique palettes per render.
+**Key AI Integration Points:**
+- `getCapabilities()` — Discover what's possible
+- `validateSystem()` — Check before creating
+- `compileSystem()` — Export protocol JSON
 
 ---
 
 ## Browser Compatibility
 
-Works in all modern browsers:
 - Chrome 80+
 - Firefox 75+
 - Safari 13+
@@ -182,11 +291,11 @@ No polyfills required.
 | Feature | @nexart/ui-renderer | @nexart/codemode-sdk |
 |---------|---------------------|----------------------|
 | Environment | Browser only | Node.js / Server |
-| Purpose | Exploration / Demos | Production / NFT minting |
+| Purpose | Authoring / Preview | Production / Minting |
 | Canonical | ❌ No | ✅ Yes |
 | Archival | ❌ No | ✅ Yes |
-| Output | Canvas rendering | PNG / MP4 buffers |
-| Determinism | Best-effort | Strict |
+| Output | Canvas / JSON | PNG / MP4 buffers |
+| API | Declarative systems | Code execution |
 
 ---
 
@@ -198,5 +307,5 @@ Copyright (c) 2024 NexArt
 
 ---
 
-> **Reminder:** This SDK is about access, not authority.
-> For canonical output, always use `@nexart/codemode-sdk`.
+> **Reminder:** This SDK authors systems. It does NOT invent new rendering rules.
+> Canonical execution always happens via `@nexart/codemode-sdk`.

package/dist/capabilities.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @nexart/ui-renderer v0.2.0 - Capabilities Discovery
+ *
+ * Exposes SDK capabilities for AI tools and builders.
+ * Critical for preventing hallucination and SDK bypass.
+ */
+export interface PrimitiveCapability {
+    type: string;
+    description: string;
+    parameters: Record<string, ParameterSpec>;
+}
+export interface ParameterSpec {
+    type: 'number' | 'string' | 'enum' | 'tuple' | 'boolean';
+    required: boolean;
+    description: string;
+    min?: number;
+    max?: number;
+    options?: string[];
+    tupleLength?: number;
+    default?: unknown;
+}
+export interface Capabilities {
+    version: string;
+    isCanonical: false;
+    isArchival: false;
+    renderer: '@nexart/ui-renderer';
+    primitives: PrimitiveCapability[];
+    background: {
+        color: ParameterSpec;
+        texture: ParameterSpec;
+        gradient: {
+            type: ParameterSpec;
+            colors: ParameterSpec;
+            angle: ParameterSpec;
+        };
+    };
+    motion: {
+        sources: string[];
+        speed: ParameterSpec;
+    };
+    limits: {
+        maxElements: number;
+        maxParticles: number;
+        maxDots: number;
+        maxLines: number;
+        maxOrbits: number;
+        maxGridSize: number;
+    };
+}
+export declare function getCapabilities(): Capabilities;
+export declare function getPrimitiveTypes(): string[];
+export declare function getMotionSources(): string[];
+export declare function getBackgroundTextures(): string[];
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;IACzD,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,KAAK,CAAC;IACnB,UAAU,EAAE,KAAK,CAAC;IAClB,QAAQ,EAAE,qBAAqB,CAAC;IAEhC,UAAU,EAAE,mBAAmB,EAAE,CAAC;IAElC,UAAU,EAAE;QACV,KAAK,EAAE,aAAa,CAAC;QACrB,OAAO,EAAE,aAAa,CAAC;QACvB,QAAQ,EAAE;YACR,IAAI,EAAE,aAAa,CAAC;YACpB,MAAM,EAAE,aAAa,CAAC;YACtB,KAAK,EAAE,aAAa,CAAC;SACtB,CAAC;KACH,CAAC;IAEF,MAAM,EAAE;QACN,OAAO,EAAE,MAAM,EAAE,CAAC;QAClB,KAAK,EAAE,aAAa,CAAC;KACtB,CAAC;IAEF,MAAM,EAAE;QACN,WAAW,EAAE,MAAM,CAAC;QACpB,YAAY,EAAE,MAAM,CAAC;QACrB,OAAO,EAAE,MAAM,CAAC;QAChB,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;CACH;AAED,wBAAgB,eAAe,IAAI,YAAY,CAsU9C;AAED,wBAAgB,iBAAiB,IAAI,MAAM,EAAE,CAE5C;AAED,wBAAgB,gBAAgB,IAAI,MAAM,EAAE,CAE3C;AAED,wBAAgB,qBAAqB,IAAI,MAAM,EAAE,CAEhD"}