@nexart/ui-renderer 0.4.0 → 0.7.0

package/README.md

@@ -1,6 +1,6 @@
 # @nexart/ui-renderer
 
-Version: 0.4.0
+Version: 0.7.0
 
 **Declarative and Code Mode System Authoring SDK for NexArt Protocol**
 
@@ -19,30 +19,32 @@ Version: 0.4.0
 
 ---
 
-## PROTOCOL LOCK — v1.0.0 (MIRROR)
+## PROTOCOL LOCK — v1.2.0 (MIRROR)
 
 | Property | Value |
 |----------|-------|
 | Protocol Name | NexArt Code Mode |
-| Version | v1.0.0 |
-| Status | **HARD LOCKED** |
+| Version | v1.2.0 |
+| Status | **STABLE** |
+| Phase | 3 |
 | This SDK | Mirror only — NOT authoritative |
-| Canonical Authority | @nexart/codemode-sdk |
-| Lock Date | December 2024 |
+| Canonical Authority | @nexart/codemode-sdk v1.4.0 |
+| Lock Date | January 2026 |
 
-**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 the v1.2.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 (exactly 10 read-only variables)
+- VAR[0..9] specification (0-10 input, always 10 at runtime)
 - Determinism behavior (seed + VAR → consistent preview)
-- Time semantics (t, frameCount, time, tGlobal)
+- Time semantics (t, frameCount, time, tGlobal, totalFrames)
 - Forbidden patterns list (13 patterns)
 - Error message format (`[Code Mode Protocol Error]`)
+- v1.2.0 features: curveVertex, bezierVertex, pixel system, createGraphics
 
 ---
 
-## Protocol Alignment (v1.0.0)
+## Protocol Alignment (v1.2.0)
 
 This SDK mirrors NexArt Protocol behavior. It is NOT canonical.
 
@@ -83,43 +85,47 @@ The following patterns are rejected (mirroring @nexart/codemode-sdk exactly):
 - `document.*`, `window.*` — DOM access forbidden
 - `import`, `require()` — external imports forbidden
 
-### VAR Protocol — LOCKED v1.0.0 (MIRROR)
+### VAR Protocol — v1.2.0 (MIRROR of SDK v1.4.0)
 
-VAR[0..9] is a read-only array of 10 protocol variables (0-100 recommended).
+VAR[0..9] is a read-only array of 10 protocol variables (0-100 strict range).
 
-**VAR Specification (FROZEN — mirrors @nexart/codemode-sdk):**
+**VAR Specification (mirrors @nexart/codemode-sdk v1.4.0):**
 
 | 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 |
+| 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 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.
+**This specification mirrors @nexart/codemode-sdk v1.4.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; // Blocked with warning
+VAR[0] = 50; // Throws: "[Code Mode Protocol Error] VAR is read-only..."
 ```
 
 **Error examples:**
 ```typescript
-// Protocol error: wrong length
-vars: [50, 50, 50] // "[Code Mode Protocol Error] VAR array must have exactly 10 elements"
+// 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"
 
-// Warning only: out of range (not clamped)
-vars: [150, 50, 50, 50, 50, 50, 50, 50, 50, 50] // Warns but allows
+// 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
 ```
 
 ---
@@ -142,15 +148,59 @@ Opinionated presets with guardrails. Provides consistent, protocol-aligned backg
 
 ### `primitive`
 
-Declarative generative components. Structured parameters, no raw code.
+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: 'dots',       // dots, lines, waves, grid, flowField, orbits
-  count: 100,
+  name: 'spirals',    // Any of the 30 primitives above
+  count: 12,
   color: '#ffffff',
-  motion: { speed: 0.5 }
+  motion: 'medium',   // 'slow', 'medium', 'fast'
+  strokeWeight: 'thin', // 'thin', 'medium', 'thick', or number
+  opacity: 0.8
 }
 ```
 
@@ -272,7 +322,7 @@ const system = createSystem({
   source: string,           // Raw p5-like sketch code
   seed?: number,            // Optional: PRNG seed
   totalFrames?: number,     // Required for loop mode
-  vars?: number[]           // Optional: VAR[0..9] (10 values, 0-100)
+  vars?: number[]           // Optional: VAR[0..9] (0-10 values, 0-100 range)
 });
 ```
 
@@ -305,23 +355,134 @@ if (!result.valid) {
 
 ### `getCapabilities()`
 
-Discover SDK capabilities.
+Discover SDK capabilities for AI and tooling.
 
 ```typescript
 import { getCapabilities } from '@nexart/ui-renderer';
 
 const caps = getCapabilities();
 // {
-//   version: '0.4.0',
+//   version: '0.7.0',
 //   isCanonical: false,
 //   isArchival: false,
 //   renderer: '@nexart/ui-renderer',
-//   delegatesTo: '@nexart/codemode-sdk',
-//   protocolVersion: '1.0.0',
+//   primitivesMeta: { notice: '...', count: 30, isCanonical: false },
+//   primitives: [ { name, category, description, parameters } ],
 //   ...
 // }
 ```
 
+### `getPrimitiveTypes()`
+
+Get all 30 primitive names as array.
+
+```typescript
+import { getPrimitiveTypes } from '@nexart/ui-renderer';
+
+const names = getPrimitiveTypes();
+// ['dots', 'lines', 'waves', 'stripes', ... ]
+```
+
+### `getPrimitivesByCategory()`
+
+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']
+// }
+```
+
+### `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 }
+// }
+```
+
+### `isPrimitiveValid(name)`
+
+Check if a primitive name is valid.
+
+```typescript
+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
+
+```typescript
+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
@@ -330,7 +491,7 @@ All Code Mode previews log their delegation:
 
 ```
 [UIRenderer] Preview delegation → @nexart/codemode-sdk
-[UIRenderer] Protocol version: 1.0.0
+[UIRenderer] Protocol version: 1.2.0
 [UIRenderer] Mode: loop
 ```
 
@@ -374,4 +535,4 @@ If the protocol rejects code:
 
 MIT License
 
-Copyright (c) 2024 NexArt
+Copyright (c) 2024-2026 NexArt

package/dist/capabilities.d.ts

@@ -1,13 +1,28 @@
 /**
- * @nexart/ui-renderer v0.2.0 - Capabilities Discovery
+ * @nexart/ui-renderer v0.7.0 - Capabilities Discovery
  *
  * Exposes SDK capabilities for AI tools and builders.
  * Critical for preventing hallucination and SDK bypass.
+ * Mirrors @nexart/codemode-sdk v1.4.0 (Protocol v1.2.0)
+ *
+ * ⚠️ PRIMITIVES ARE NON-CANONICAL
+ * Primitives are helper generators that compile to Code Mode sketches.
+ * They exist for convenience and rapid prototyping only.
+ * The canonical output is always the compiled Code Mode source.
  */
 export interface PrimitiveCapability {
-    type: string;
+    name: string;
+    category: 'basic' | 'geometric' | 'radial' | 'flow' | 'patterns' | 'organic';
     description: string;
-    parameters: Record<string, ParameterSpec>;
+    compilesTo: 'codemode';
+    isCanonical: false;
+    parameters: {
+        count: ParameterSpec;
+        color: ParameterSpec;
+        opacity: ParameterSpec;
+        strokeWeight: ParameterSpec;
+        motion: ParameterSpec;
+    };
 }
 export interface ParameterSpec {
     type: 'number' | 'string' | 'enum' | 'tuple' | 'boolean';
@@ -24,6 +39,13 @@ export interface Capabilities {
     isCanonical: false;
     isArchival: false;
     renderer: '@nexart/ui-renderer';
+    primitivesMeta: {
+        notice: string;
+        count: number;
+        categories: string[];
+        compilesTo: 'codemode';
+        isCanonical: false;
+    };
     primitives: PrimitiveCapability[];
     background: {
         color: ParameterSpec;
@@ -40,15 +62,15 @@ export interface Capabilities {
     };
     limits: {
         maxElements: number;
-        maxParticles: number;
-        maxDots: number;
-        maxLines: number;
-        maxOrbits: number;
-        maxGridSize: number;
+        maxCount: number;
+        maxPrimitives: number;
     };
 }
 export declare function getCapabilities(): Capabilities;
 export declare function getPrimitiveTypes(): string[];
+export declare function getPrimitivesByCategory(): Record<string, string[]>;
+export declare function getPrimitiveInfo(name: string): PrimitiveCapability | null;
 export declare function getMotionSources(): string[];
 export declare function getBackgroundTextures(): string[];
+export declare function isPrimitiveValid(name: string): boolean;
 //# sourceMappingURL=capabilities.d.ts.map

package/dist/capabilities.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,GAAG,WAAW,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;IAC7E,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,UAAU,CAAC;IACvB,WAAW,EAAE,KAAK,CAAC;IACnB,UAAU,EAAE;QACV,KAAK,EAAE,aAAa,CAAC;QACrB,KAAK,EAAE,aAAa,CAAC;QACrB,OAAO,EAAE,aAAa,CAAC;QACvB,YAAY,EAAE,aAAa,CAAC;QAC5B,MAAM,EAAE,aAAa,CAAC;KACvB,CAAC;CACH;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,cAAc,EAAE;QACd,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,EAAE,MAAM,EAAE,CAAC;QACrB,UAAU,EAAE,UAAU,CAAC;QACvB,WAAW,EAAE,KAAK,CAAC;KACpB,CAAC;IAEF,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,QAAQ,EAAE,MAAM,CAAC;QACjB,aAAa,EAAE,MAAM,CAAC;KACvB,CAAC;CACH;AAwDD,wBAAgB,eAAe,IAAI,YAAY,CA0G9C;AAED,wBAAgB,iBAAiB,IAAI,MAAM,EAAE,CAS5C;AAED,wBAAgB,uBAAuB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CASlE;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI,CAGzE;AAED,wBAAgB,gBAAgB,IAAI,MAAM,EAAE,CAE3C;AAED,wBAAgB,qBAAqB,IAAI,MAAM,EAAE,CAEhD;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEtD"}