@nexart/ui-renderer

Version: 0.6.0

Declarative and Code Mode System Authoring SDK for NexArt Protocol

This SDK is a PREVIEW MIRROR, not an authority.

It mirrors the behavior of @nexart/codemode-sdk faithfully for preview purposes.

It is:

• NOT canonical — Does not produce archival-quality output
• NOT archival — Not the source of truth for production rendering
• NOT protocol-authoritative — Delegates all Code Mode execution semantics

Same inputs → same restrictions → same errors → same semantics as @nexart/codemode-sdk.

PROTOCOL LOCK — v1.0.0 (MIRROR)

| 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 |

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 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])

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.

// 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:

// 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.

{
  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

{
  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.

{
  type: 'sketch',
  code: `
    function setup() {
      background(0);
    }
    function draw() {
      ellipse(width/2, height/2, 100);
    }
  `,
  normalize: true
}

Install

npm install @nexart/ui-renderer

Or use directly in HTML:

<script type="module">
  import { createSystem, previewSystem } from 'https://unpkg.com/@nexart/ui-renderer/dist/index.js';
</script>

Quick Start

Code Mode Systems with VAR

Create and preview Code Mode sketches using protocol variables:

import { createSystem, previewSystem } from '@nexart/ui-renderer';

const system = createSystem({
  type: 'code',
  mode: 'loop',
  width: 1950,
  height: 2400,
  totalFrames: 120,
  seed: 12345,
  vars: [50, 75, 25, 0, 100, 50, 50, 50, 50, 50], // VAR[0..9]
  source: `
    function setup() {
      noFill();
      stroke(0);
    }
    function draw() {
      background(246, 245, 242);
      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);
      }
    }
  `
});

const canvas = document.getElementById('canvas');
const renderer = previewSystem(system, canvas);
renderer.start();

Static Mode (single-frame, setup only):

const staticSystem = createSystem({
  type: 'code',
  mode: 'static',
  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);
      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));
      }
    }
  `
});

previewSystem(staticSystem, canvas).render();

API Reference

createSystem(input)

Create a validated NexArt system.

Code Mode Input:

const system = createSystem({
  type: 'code',
  mode: 'static' | 'loop',
  width: number,
  height: number,
  source: string,           // Raw p5-like sketch code
  seed?: number,            // Optional: PRNG seed
  totalFrames?: number,     // Required for loop mode
  vars?: number[]           // Optional: VAR[0..9] (0-10 values, 0-100 range)
});

previewSystem(system, canvas, options?)

Render a visual preview.

const renderer = previewSystem(system, canvas, {
  mode: 'static' | 'loop',  // default: 'static'
  showBadge: boolean        // default: true
});

renderer.render();  // Single frame
renderer.start();   // Animation loop
renderer.stop();    // Stop loop
renderer.destroy(); // Cleanup

validateSystem(input)

Validate system input without creating.

const result = validateSystem(input);
if (!result.valid) {
  console.error(result.errors);
}

getCapabilities()

Discover SDK capabilities for AI and tooling.

import { getCapabilities } from '@nexart/ui-renderer';

const caps = getCapabilities();
// {
//   version: '0.6.0',
//   isCanonical: false,
//   isArchival: false,
//   renderer: '@nexart/ui-renderer',
//   primitivesMeta: { notice: '...', count: 30, isCanonical: false },
//   primitives: [ { name, category, description, parameters } ],
//   ...
// }

getPrimitiveTypes()

Get all 30 primitive names as array.

import { getPrimitiveTypes } from '@nexart/ui-renderer';

const names = getPrimitiveTypes();
// ['dots', 'lines', 'waves', 'stripes', ... ]

getPrimitivesByCategory()

Get primitives organized by category.

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']
// }

getPrimitiveInfo(name)

Get full capability info for a single primitive.

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 }
// }

isPrimitiveValid(name)

Check if a primitive name is valid.

import { isPrimitiveValid } from '@nexart/ui-renderer';

isPrimitiveValid('spirals');  // true
isPrimitiveValid('invalid');  // false

AI Capabilities API

Designed for AI agents to build valid systems without hallucination.

⚠️ 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

import { getCapabilities, isPrimitiveValid, getPrimitiveInfo } from '@nexart/ui-renderer';

const caps = getCapabilities();

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 |

Delegation Logging

All Code Mode previews log their delegation:

[UIRenderer] Preview delegation → @nexart/codemode-sdk
[UIRenderer] Protocol version: 1.0.0
[UIRenderer] Mode: loop

Error Mirroring

If the protocol rejects code:

• Rendering stops immediately
• Black canvas is displayed
• Error is logged verbatim
• No "best effort" recovery

[UIRenderer Protocol Error] Forbidden pattern: Math.random() — use random() instead (seeded)

What This SDK Does NOT Guarantee

| 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 |

Browser Compatibility

• Chrome 80+
• Firefox 75+
• Safari 13+
• Edge 80+

License

MIT License

Copyright (c) 2024 NexArt