@nexart/codemode-sdk 1.0.1 → 1.1.1

package/README.md

@@ -1,85 +1,197 @@
 # 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
+## Installation
 
-**Code Mode Runtime v0.x**
+```bash
+# Copy the sdk/codemode folder to your project
+cp -r sdk/codemode your-project/lib/codemode
+```
 
-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
+---
+
+## Canonical API
+
+### `executeCodeMode(input: ExecuteCodeModeInput): Promise<ExecuteCodeModeResult>`
+
+**This is the official, canonical entry point for Code Mode execution.**
+
+All implementations MUST use this function.
+
+```typescript
+import { executeCodeMode } from '@nexart/codemode-sdk';
+
+const result = await executeCodeMode({
+  source: `
+    function setup() {
+      background(255);
+      fill(0);
+      let size = map(VAR[0], 0, 100, 50, 200);
+      ellipse(width/2, height/2, size);
+    }
+  `,
+  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[0..9] values (0-100), defaults to all zeros |
+| `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;
+  }
+}
+```
 
 ---
 
-## API
+## Legacy API
+
+> ⚠️ **Note**: The `createEngine()` API is still supported but new implementations should use `executeCodeMode()`.
 
 ### `createEngine(config: EngineConfig): Engine`
 
 Create a rendering engine instance.
 
 ```typescript
-import { createEngine } from '@nexart/codemode-sdk';
+import { createEngine } from './codemode';
 
 const engine = createEngine({
   mode: 'static',      // 'static' | 'loop'
@@ -100,9 +212,13 @@ await engine.run({
     function setup() {
       background(255);
       fill(0);
-      ellipse(width/2, height/2, 100);
+      // Use VAR for external control
+      let size = map(VAR[0], 0, 100, 50, 200);
+      ellipse(width/2, height/2, size);
     }
   `,
+  seed: 12345,              // Optional: seed for deterministic randomness
+  vars: [50, 75, 0, 0, 0, 0, 0, 0, 0, 0],  // Optional: VAR[0..9] values (0-100)
   onPreview: (canvas) => {
     // Optional: called with canvas after first frame
   },
@@ -122,6 +238,53 @@ await engine.run({
 });
 ```
 
+### Protocol Variables (VAR[0..9]) — Protocol v1.0.0
+
+Protocol variables are first-class inputs that control artwork parameters.
+
+**VAR Specification (SDK v1.0.2):**
+
+| 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
+// Pass values when running (0-10 elements)
+await engine.run({
+  code: myCode,
+  vars: [80, 50, 25],  // VAR[0]=80, VAR[1]=50, VAR[2]=25, VAR[3..9]=0
+  onComplete: (result) => { /* ... */ },
+});
+
+// Or omit entirely (all zeros)
+await engine.run({
+  code: myCode,
+  onComplete: (result) => { /* ... */ },
+});
+
+// Access in sketch code
+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
+
 ### `engine.stop(): void`
 
 Cancel a running render (Loop mode only).
@@ -160,20 +323,35 @@ 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
+## 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
 
 ---
 
 ## Example: Static Mode
 
 ```typescript
-import { createEngine } from '@nexart/codemode-sdk';
+import { createEngine } from './codemode';
 
 const engine = createEngine({ mode: 'static' });
 
@@ -202,7 +380,7 @@ await engine.run({
 ## Example: Loop Mode
 
 ```typescript
-import { createEngine } from '@nexart/codemode-sdk';
+import { createEngine } from './codemode';
 
 const engine = createEngine({
   mode: 'loop',
@@ -257,7 +435,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`
@@ -278,14 +466,14 @@ 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).
 
 ---
 
 ## Files
 
 ```
-@nexart/codemode-sdk/
+sdk/codemode/
 ├── index.ts         # Main export
 ├── engine.ts        # createEngine entry point
 ├── types.ts         # TypeScript types
@@ -297,16 +485,80 @@ Ensure your server has this endpoint available, or provide your own encoding sol
 
 ---
 
-## Changelog
+## License
 
-**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.
+MIT License
 
-**0.1.0** — Initial release.
+Copyright (c) 2024 NexArt
 
 ---
 
-## License
+## External Builders
 
-MIT License
+This SDK is designed for use by:
 
-Copyright (c) 2024 NexArt
+- **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);
+}
+```
+
+---
+
+## 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) |
+
+---
+
+## Future Work (Phase 2+)
+
+- GSL v1 SDK (protocol layer) — separate package
+- Extended p5.js compatibility
+- WebGL rendering support
+- GIF output option

package/dist/core-index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @nexart/codemode-sdk v1.1.0 — Core Exports
+ *
+ * Canonical execution engine for NexArt Code Mode.
+ * This is the single source of truth for Code Mode semantics.
+ *
+ * Protocol: v1.0.0 (LOCKED)
+ * Enforcement: HARD
+ */
+export { executeCodeMode, validateCodeModeSource, } from './execute';
+export { type RenderMode, type TimeVariables, type ProtocolMetadata, type EngineConfig, type RenderResult, type RunOptions, type ProgressInfo, type Engine, type ExecuteCodeModeInput, type ExecuteCodeModeResult, PROTOCOL_IDENTITY, DEFAULT_VARS, DEFAULT_CONFIG, } from './types';
+export { createP5Runtime, injectTimeVariables, createProtocolVAR, VAR_COUNT, VAR_MIN, VAR_MAX, CODE_MODE_PROTOCOL_VERSION, CODE_MODE_PROTOCOL_PHASE, CODE_MODE_ENFORCEMENT, type P5Runtime, type P5RuntimeConfig, } from './p5-runtime';
+export { runStaticMode, } from './static-engine';
+export { runLoopMode, cancelLoopMode, } from './loop-engine';
+export { createEngine, } from './engine';
+/**
+ * SDK Identity
+ */
+export declare const SDK_VERSION = "1.1.1";
+export declare const SDK_NAME = "@nexart/codemode-sdk";
+//# sourceMappingURL=core-index.d.ts.map

package/dist/core-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core-index.d.ts","sourceRoot":"","sources":["../core-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EACL,eAAe,EACf,sBAAsB,GACvB,MAAM,WAAW,CAAC;AAGnB,OAAO,EACL,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,MAAM,EACX,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,iBAAiB,EACjB,YAAY,EACZ,cAAc,GACf,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,iBAAiB,EACjB,SAAS,EACT,OAAO,EACP,OAAO,EACP,0BAA0B,EAC1B,wBAAwB,EACxB,qBAAqB,EACrB,KAAK,SAAS,EACd,KAAK,eAAe,GACrB,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,aAAa,GACd,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,WAAW,EACX,cAAc,GACf,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,YAAY,GACb,MAAM,UAAU,CAAC;AAElB;;GAEG;AACH,eAAO,MAAM,WAAW,UAAU,CAAC;AACnC,eAAO,MAAM,QAAQ,yBAAyB,CAAC"}

package/dist/core-index.js

@@ -0,0 +1,26 @@
+/**
+ * @nexart/codemode-sdk v1.1.0 — Core Exports
+ *
+ * Canonical execution engine for NexArt Code Mode.
+ * This is the single source of truth for Code Mode semantics.
+ *
+ * Protocol: v1.0.0 (LOCKED)
+ * Enforcement: HARD
+ */
+// Core execution
+export { executeCodeMode, validateCodeModeSource, } from './execute';
+// Protocol types
+export { PROTOCOL_IDENTITY, DEFAULT_VARS, DEFAULT_CONFIG, } from './types';
+// Runtime
+export { createP5Runtime, injectTimeVariables, createProtocolVAR, VAR_COUNT, VAR_MIN, VAR_MAX, CODE_MODE_PROTOCOL_VERSION, CODE_MODE_PROTOCOL_PHASE, CODE_MODE_ENFORCEMENT, } from './p5-runtime';
+// Static engine
+export { runStaticMode, } from './static-engine';
+// Loop engine
+export { runLoopMode, cancelLoopMode, } from './loop-engine';
+// Engine utilities
+export { createEngine, } from './engine';
+/**
+ * SDK Identity
+ */
+export const SDK_VERSION = '1.1.1';
+export const SDK_NAME = '@nexart/codemode-sdk';

package/dist/execute.d.ts

@@ -0,0 +1,46 @@
+/**
+ * NexArt Code Mode Runtime SDK - Canonical Execution Entry Point
+ *
+ * ╔══════════════════════════════════════════════════════════════════════════╗
+ * ║  CODE MODE PROTOCOL v1.0.0 (Phase 1) — CANONICAL ENTRY POINT             ║
+ * ║                                                                          ║
+ * ║  This is the ONLY official way to execute Code Mode.                     ║
+ * ║  All implementations (NexArt, ByX, external) MUST use this function.     ║
+ * ║                                                                          ║
+ * ║  Authority: @nexart/codemode-sdk                                         ║
+ * ╚══════════════════════════════════════════════════════════════════════════╝
+ */
+import { ExecuteCodeModeInput, ExecuteCodeModeResult } from './types';
+/**
+ * executeCodeMode — Canonical Code Mode Execution Entry Point
+ *
+ * This is the ONLY official way to execute Code Mode.
+ * All implementations MUST use this function.
+ *
+ * @param input - Execution parameters
+ * @returns Promise<ExecuteCodeModeResult> - Execution result with protocol metadata
+ *
+ * @example
+ * ```typescript
+ * const result = await executeCodeMode({
+ *   source: `function setup() { background(255); ellipse(width/2, height/2, 100); }`,
+ *   width: 1950,
+ *   height: 2400,
+ *   seed: 12345,
+ *   vars: [50, 75, 0, 0, 0, 0, 0, 0, 0, 0],
+ *   mode: 'static'
+ * });
+ *
+ * console.log(result.metadata.protocolVersion); // '1.0.0'
+ * console.log(result.image); // PNG Blob
+ * ```
+ */
+export declare function executeCodeMode(input: ExecuteCodeModeInput): Promise<ExecuteCodeModeResult>;
+/**
+ * Validate code without executing
+ */
+export declare function validateCodeModeSource(source: string, mode: 'static' | 'loop'): {
+    valid: boolean;
+    errors: string[];
+};
+//# sourceMappingURL=execute.d.ts.map

package/dist/execute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../execute.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EAKtB,MAAM,SAAS,CAAC;AA4MjB;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,oBAAoB,GAC1B,OAAO,CAAC,qBAAqB,CAAC,CAqBhC;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAuCpH"}