@nexart/codemode-sdk 1.0.0 → 1.1.0

package/README.md

@@ -1,134 +1,219 @@
 # NexArt Code Mode Runtime SDK
 
-Version: 0.1.1
-
-A minimal, deterministic rendering engine for generative art.
+**Version: 1.0.2 (Protocol v1.0.0)**
+
+╔══════════════════════════════════════════════════════════════════════════════╗
+║  @nexart/codemode-sdk — Canonical Code Mode Authority                        ║
+║                                                                              ║
+║  This SDK defines the official Code Mode execution surface.                  ║
+║  All implementations (NexArt, ByX, external) MUST use this SDK.              ║
+║                                                                              ║
+║  Protocol: nexart                                                            ║
+║  Engine: codemode                                                            ║
+║  SDK Version: 1.0.2                                                          ║
+║  Protocol Version: 1.0.0                                                     ║
+║  Phase: 1                                                                    ║
+║  Enforcement: HARD                                                           ║
+╚══════════════════════════════════════════════════════════════════════════════╝
 
 ---
 
-> **This SDK enforces the NexArt Code Mode Runtime Execution Specification (v0.x).**
->
-> **This is NOT the protocol-stable GSL v1.**
+## PROTOCOL LOCK — v1.0.0
+
+| Property | Value |
+|----------|-------|
+| Protocol Name | NexArt Code Mode |
+| Version | v1.0.0 |
+| Status | **HARD LOCKED** |
+| Phase | 1 |
+| Lock Date | December 2024 |
+
+**This protocol surface is frozen. Any breaking change requires v2.0.0.**
+
+The following are locked and will not change in v1.x:
+
+- Execution model (Static and Loop modes)
+- VAR[0..9] specification (0-10 read-only variables, missing indices return 0)
+- Determinism guarantee (seed + VAR → identical output)
+- Time semantics (t, frameCount, time, tGlobal)
+- Random and noise behavior (seeded Mulberry32, Perlin)
+- Forbidden patterns list (13 patterns)
+- Canvas pre-initialization (no createCanvas)
 
 ---
 
-## Install
+A minimal, deterministic rendering engine for generative art.
 
-```bash
-npm install @nexart/codemode-sdk
-```
+## Protocol Authority
+
+**This SDK is the single source of truth for Code Mode semantics.**
+
+If someone asks: "How does Code Mode work in NexArt?"
+
+The answer is: "Whatever @nexart/codemode-sdk does — that is the protocol."
 
 ---
 
-## Usage
+## What's New in v1.0.2
 
-```typescript
-import { createEngine } from '@nexart/codemode-sdk';
+- **VAR input is now optional (0-10 elements)**
+  - Omit `vars` or pass `[]` for empty (defaults to all zeros)
+  - Input length must be 0-10 (throws if > 10)
+  - Values must be finite numbers in [0, 100] (throws if out of range)
+  - Runtime VAR is ALWAYS 10 elements (padded with zeros for consistency)
+- **Backwards compatible**: existing code passing 10 elements works unchanged
 
-const engine = createEngine({ mode: 'static' });
+## v1.0.1
 
-await engine.run({
-  code: `
-    function setup() {
-      background(255);
-      fill(0);
-      ellipse(width/2, height/2, 100);
-    }
-  `,
-  onComplete: (result) => {
-    console.log(result.type); // 'image'
-    console.log(result.blob); // PNG Blob
-  }
-});
-```
+- Protocol Lock section formalized with HARD LOCKED status
+- VAR specification clarified with enforcement tables
+
+## v1.0.0 (Protocol Lock)
+
+- **Protocol Lock**: Phase 1 execution surface is now LOCKED
+- **Canonical Entry Point**: `executeCodeMode()` is the official execution API
+- **Protocol Metadata**: All executions include protocol headers for verification
+- **VAR[0..9] Protocol Variables**: First-class protocol inputs (read-only, 0-100)
+- **Full CSS Color Support**: hex, rgb(), rgba(), hsl(), hsla()
+- **Determinism Guarantee**: Same code + seed + vars = identical output
 
 ---
 
 ## What This SDK Is
 
-This SDK provides a headless runtime for executing p5.js-style generative art code and producing deterministic output:
+This SDK provides the **canonical runtime** for executing p5.js-style generative art:
 
 - **Static Mode**: Executes `setup()` only, outputs PNG
 - **Loop Mode**: Frame-authoritative rendering, outputs MP4
+- **Deterministic**: Seed-controlled randomness, no external state
+- **Protocol-Compliant**: All outputs include verification metadata
+
+The SDK enforces the **NexArt Code Mode Protocol v1.0.0** for reproducible, mint-safe generative art.
 
 ---
 
 ## What This SDK Is NOT
 
-- **Not a protocol layer** — Does not validate protocol claims, system hashes, or GSL v1
+- **Not a suggestion** — This SDK IS the protocol, not a reference implementation
 - **Not a UI library** — No React components, no wallet integration
 - **Not an IPFS client** — Does not handle storage or minting
 - **Not p5.js** — Uses a minimal subset of p5.js-like functions
 
 ---
 
-## Target Version
-
-**Code Mode Runtime v0.x**
+## Installation
 
-This SDK extracts the current NexArt Code Mode execution logic. Future versions may introduce:
-- GSL v1 SDK (protocol layer) — separate package
-- Extended p5.js compatibility
+```bash
+npm install @nexart/codemode-sdk
+```
 
 ---
 
-## API
-
-### `createEngine(config: EngineConfig): Engine`
+## Canonical API
 
-Create a rendering engine instance.
+### `executeCodeMode(input: ExecuteCodeModeInput): Promise<ExecuteCodeModeResult>`
 
-```typescript
-import { createEngine } from '@nexart/codemode-sdk';
-
-const engine = createEngine({
-  mode: 'static',      // 'static' | 'loop'
-  width: 1950,         // Optional, default: 1950
-  height: 2400,        // Optional, default: 2400
-  duration: 2,         // Loop mode only, 1-4 seconds
-  fps: 30,             // Loop mode only, default: 30
-});
-```
+**This is the official, canonical entry point for Code Mode execution.**
 
-### `engine.run(options: RunOptions): Promise<void>`
-
-Execute code and produce output.
+All implementations MUST use this function.
 
 ```typescript
-await engine.run({
-  code: `
+import { executeCodeMode } from '@nexart/codemode-sdk';
+
+const result = await executeCodeMode({
+  source: `
     function setup() {
       background(255);
       fill(0);
-      ellipse(width/2, height/2, 100);
+      let size = map(VAR[0], 0, 100, 50, 200);
+      ellipse(width/2, height/2, size);
     }
   `,
-  onPreview: (canvas) => {
-    // Optional: called with canvas after first frame
-  },
-  onProgress: (info) => {
-    // Optional: progress updates
-    console.log(info.message, info.percent + '%');
-  },
-  onComplete: (result) => {
-    // Required: called with final result
-    console.log(result.type); // 'image' | 'video'
-    console.log(result.blob); // Blob
-  },
-  onError: (error) => {
-    // Optional: called on error
-    console.error(error);
-  },
+  width: 1950,
+  height: 2400,
+  seed: 12345,
+  vars: [50, 75, 0, 0, 0, 0, 0, 0, 0, 0],
+  mode: 'static'
 });
+
+// Result includes protocol metadata
+console.log(result.metadata.protocol);        // 'nexart'
+console.log(result.metadata.engine);          // 'codemode'
+console.log(result.metadata.protocolVersion); // '1.0.0'
+console.log(result.metadata.deterministic);   // true
+console.log(result.image);                    // PNG Blob
+```
+
+### Input Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `source` | `string` | ✅ | Code with setup() and optional draw() |
+| `width` | `number` | ✅ | Canvas width in pixels |
+| `height` | `number` | ✅ | Canvas height in pixels |
+| `seed` | `number` | ✅ | Seed for deterministic randomness |
+| `vars` | `number[]` | ❌ | VAR values (0-10 elements, 0-100 range), missing indices return 0 |
+| `mode` | `'static' \| 'loop'` | ✅ | Execution mode |
+| `totalFrames` | `number` | ⚠️ | Required for loop mode |
+
+### Result Structure
+
+```typescript
+interface ExecuteCodeModeResult {
+  image?: Blob;          // Static mode: PNG
+  video?: Blob;          // Loop mode: MP4
+  frames?: ImageData[];  // Optional: raw frame data
+  metadata: {
+    protocol: 'nexart';
+    engine: 'codemode';
+    protocolVersion: '1.0.0';
+    phase: 1;
+    deterministic: true;
+    seed: number;
+    vars: number[];
+    width: number;
+    height: number;
+    mode: 'static' | 'loop';
+    totalFrames?: number;
+  }
+}
 ```
 
-### `engine.stop(): void`
+---
+
+## Protocol Variables (VAR[0..9]) — Protocol v1.0.0
 
-Cancel a running render (Loop mode only).
+Protocol variables are first-class inputs that control artwork parameters.
 
-### `engine.getConfig(): EngineConfig`
+**VAR Specification (SDK v1.0.2):**
 
-Get the resolved engine configuration.
+| 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 — Proxy blocks writes |
+| Injection | Before execution | Guaranteed |
+| Lifecycle | Stable for entire render | Guaranteed |
+| Default | All zeros | If not provided |
+
+```typescript
+// Access in sketch code (missing indices return 0)
+function setup() {
+  let density = map(VAR[0], 0, 100, 10, 200);
+  let speed = map(VAR[1], 0, 100, 0.5, 5);
+  // VAR[5] returns 0 if not provided
+}
+```
+
+**Rules (Protocol Law):**
+- Input accepts 0-10 elements; runtime VAR is always 10 elements
+- VAR is injected BEFORE code execution (padded with zeros if needed)
+- VAR values are READ-ONLY at runtime (Proxy-protected)
+- Writing to VAR throws a protocol error
+- Values MUST be in range 0-100 (throws if out of range)
+- Same code + same seed + same VARs = identical output
 
 ---
 
@@ -160,83 +245,28 @@ Get the resolved engine configuration.
 
 ---
 
-## Forbidden Patterns
-
-These patterns will throw errors:
-
-- `createCanvas()` — Canvas is pre-initialized by the SDK
-- `setTimeout()`, `setInterval()`, `requestAnimationFrame()` — Async timing breaks determinism
-- `noLoop()` in Loop Mode — Incompatible with frame capture
-
----
-
-## Example: Static Mode
-
-```typescript
-import { createEngine } from '@nexart/codemode-sdk';
-
-const engine = createEngine({ mode: 'static' });
-
-await engine.run({
-  code: `
-    function setup() {
-      background(30);
-      noStroke();
-      for (let i = 0; i < 100; i++) {
-        fill(random(255), random(255), random(255));
-        ellipse(random(width), random(height), 50);
-      }
-    }
-  `,
-  onComplete: (result) => {
-    // result.type === 'image'
-    // result.blob is a PNG Blob
-    const url = URL.createObjectURL(result.blob);
-    document.body.innerHTML = `<img src="${url}" />`;
-  },
-});
-```
-
----
-
-## Example: Loop Mode
-
-```typescript
-import { createEngine } from '@nexart/codemode-sdk';
-
-const engine = createEngine({
-  mode: 'loop',
-  duration: 2,  // 2 second loop
-});
-
-await engine.run({
-  code: `
-    function setup() {
-      // Called once
-    }
-    
-    function draw() {
-      background(30);
-      
-      // t goes from 0 to 1 over the loop duration
-      let x = width/2 + cos(t * TWO_PI) * 200;
-      let y = height/2 + sin(t * TWO_PI) * 200;
-      
-      fill(255);
-      ellipse(x, y, 80);
-    }
-  `,
-  onProgress: (info) => {
-    console.log(info.message);
-  },
-  onComplete: (result) => {
-    // result.type === 'video'
-    // result.blob is an MP4 Blob
-    const url = URL.createObjectURL(result.blob);
-    document.body.innerHTML = `<video src="${url}" autoplay loop />`;
-  },
-});
-```
+## Forbidden Patterns — LOCKED v1.0.0
+
+The following 13 patterns are rejected with `[Code Mode Protocol Error]`:
+
+| Pattern | Reason |
+|---------|--------|
+| `setTimeout` | Async timing breaks determinism |
+| `setInterval` | Async timing breaks determinism |
+| `requestAnimationFrame` | Async timing breaks determinism |
+| `Date.now()` | Time-based entropy forbidden |
+| `new Date()` | Time-based entropy forbidden |
+| `Math.random()` | Use seeded `random()` instead |
+| `fetch()` | External IO forbidden |
+| `XMLHttpRequest` | External IO forbidden |
+| `createCanvas()` | Canvas is pre-initialized |
+| `document.*` | DOM access forbidden |
+| `window.*` | DOM access forbidden |
+| `import` | External imports forbidden |
+| `require()` | External imports forbidden |
+
+Additionally in Loop Mode:
+- `noLoop()` — Incompatible with frame capture
 
 ---
 
@@ -257,7 +287,17 @@ The SDK includes a minimal p5.js-like runtime with:
 `push`, `pop`, `translate`, `rotate`, `scale`, `resetMatrix`
 
 **Color:**
-`colorMode`, `color`, `lerpColor`
+`colorMode`, `color`, `lerpColor`, `red`, `green`, `blue`, `alpha`, `hue`, `saturation`, `brightness`
+
+**Color Formats:**
+All of the following are accepted by `fill()`, `stroke()`, `background()`:
+- Grayscale: `fill(128)`, `fill(128, 127)`
+- RGB: `fill(255, 0, 0)`, `fill(255, 0, 0, 128)`
+- Hex: `fill('#ff0000')`, `fill('#f00')`
+- CSS: `fill('rgb(255,0,0)')`, `fill('rgba(255,0,0,0.5)')`, `fill('hsl(180,50%,50%)')`
+
+**Protocol Variables:**
+`VAR` — Array of 10 values (VAR[0] through VAR[9])
 
 **Math:**
 `random`, `noise`, `map`, `constrain`, `lerp`, `dist`, `mag`, `norm`
@@ -270,6 +310,69 @@ The SDK includes a minimal p5.js-like runtime with:
 
 ---
 
+## Frozen Execution Guarantees — v1.0.0
+
+The following guarantees are LOCKED and will not change in v1.x:
+
+| Guarantee | Description |
+|-----------|-------------|
+| Determinism | Same code + same seed + same VARs = identical output |
+| Static Mode | `setup()` only, single PNG output |
+| Loop Mode | Frame-authoritative, `draw()` per frame, MP4 output |
+| Time Semantics | `t` ∈ [0,1), `frameCount` ∈ [0,totalFrames), `time` in seconds |
+| Random | Seeded Mulberry32 PRNG via `random()` |
+| Noise | Seeded Perlin noise via `noise()` |
+| Canvas | Pre-initialized, no `createCanvas()` |
+| VAR | Exactly 10 read-only protocol variables |
+| Forbidden Patterns | 13 patterns rejected (see above) |
+
+---
+
+## External Builders
+
+This SDK is designed for use by:
+
+- **NexArt App**: The main generative art platform
+- **ByX**: Curated collection system
+- **External Builders**: Any platform consuming NexArt Code Mode
+
+### Integration Example
+
+```typescript
+import { executeCodeMode } from '@nexart/codemode-sdk';
+
+// Execute with explicit VAR values
+const result = await executeCodeMode({
+  source: artistCode,
+  width: 1950,
+  height: 2400,
+  seed: 12345,
+  vars: [50, 75, 25, 0, 0, 0, 0, 0, 0, 0],  // Exactly 10 values
+  mode: 'static'
+});
+
+// Result includes full protocol metadata for verification
+const { image, metadata } = result;
+console.log(metadata.protocolVersion); // '1.0.0'
+console.log(metadata.deterministic);   // true
+```
+
+### Error Handling
+
+All protocol violations throw descriptive errors:
+
+```typescript
+try {
+  await executeCodeMode({ ... });
+} catch (error) {
+  // "[Code Mode Protocol Error] VAR array must have exactly 10 elements, got 5"
+  // "[Code Mode Protocol Error] Forbidden pattern: Math.random()"
+  console.error(error.message);
+}
+```
+
+---
+
 ## Video Encoding
 
 Loop Mode requires server-side video encoding. The SDK calls:
@@ -278,7 +381,7 @@ Loop Mode requires server-side video encoding. The SDK calls:
 POST /api/encode-loop
 ```
 
-Ensure your server has this endpoint available, or provide your own encoding solution.
+Ensure your server has this endpoint available (NexArt provides this).
 
 ---
 
@@ -288,6 +391,7 @@ Ensure your server has this endpoint available, or provide your own encoding sol
 @nexart/codemode-sdk/
 ├── index.ts         # Main export
 ├── engine.ts        # createEngine entry point
+├── execute.ts       # Canonical executeCodeMode API
 ├── types.ts         # TypeScript types
 ├── static-engine.ts # Static mode implementation
 ├── loop-engine.ts   # Loop mode implementation
@@ -299,7 +403,13 @@ Ensure your server has this endpoint available, or provide your own encoding sol
 
 ## Changelog
 
-**0.1.1** — Fixed beginShape / vertex / endShape rendering bug. Vertex-based shapes (waves, spirals, Lissajous curves, hexagons) now render correctly and match nexart.xyz behavior.
+**1.0.2** — VAR is now optional (0-10 elements). Missing indices return 0. Out-of-range throws.
+
+**1.0.1** — Protocol Lock formalized. VAR specification clarified. CHANGELOG added.
+
+**1.0.0** — Protocol Lock. Phase 1 execution surface HARD LOCKED. executeCodeMode() canonical API.
+
+**0.1.1** — Fixed beginShape / vertex / endShape rendering bug.
 
 **0.1.0** — Initial release.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nexart/codemode-sdk",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "NexArt Code Mode Runtime SDK - Deterministic generative art rendering engine",
   "license": "MIT",
   "main": "dist/index.js",