@nexart/codemode-sdk 1.1.1 → 1.5.0

package/README.md

@@ -1,6 +1,6 @@
 # NexArt Code Mode Runtime SDK
 
-**Version: 1.0.2 (Protocol v1.0.0)**
+**Version: 1.5.0 (Protocol v1.2.0)**
 
 ╔══════════════════════════════════════════════════════════════════════════════╗
 ║  @nexart/codemode-sdk — Canonical Code Mode Authority                        ║
@@ -10,32 +10,32 @@
 ║                                                                              ║
 ║  Protocol: nexart                                                            ║
 ║  Engine: codemode                                                            ║
-║  SDK Version: 1.0.2                                                          ║
-║  Protocol Version: 1.0.0                                                     ║
-║  Phase: 1                                                                    ║
+║  SDK Version: 1.5.0                                                          ║
+║  Protocol Version: 1.2.0                                                     ║
+║  Phase: 3                                                                    ║
 ║  Enforcement: HARD                                                           ║
 ╚══════════════════════════════════════════════════════════════════════════════╝
 
 ---
 
-## PROTOCOL LOCK — v1.0.0
+## PROTOCOL LOCK — v1.x
 
 | Property | Value |
 |----------|-------|
 | Protocol Name | NexArt Code Mode |
-| Version | v1.0.0 |
-| Status | **HARD LOCKED** |
-| Phase | 1 |
-| Lock Date | December 2024 |
+| Version | v1.2.0 |
+| Status | **STABLE** |
+| Phase | 3 |
+| Lock Date | January 2026 |
 
-**This protocol surface is frozen. Any breaking change requires v2.0.0.**
+**Core 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)
+- Time semantics (t, frameCount, time, tGlobal, totalFrames)
 - Random and noise behavior (seeded Mulberry32, Perlin)
 - Forbidden patterns list (13 patterns)
 - Canvas pre-initialization (no createCanvas)
@@ -54,27 +54,52 @@ The answer is: "Whatever @nexart/codemode-sdk does — that is the protocol."
 
 ---
 
-## What's New in v1.0.2
+## What's New in v1.5.0
 
-- **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
+**Critical Fix — NPM Package Sync**
 
-## v1.0.1
+- **Restored seeded Mulberry32 PRNG** for `random()`, `randomSeed()`, `randomGaussian()`
+- **Restored seeded Perlin noise** for `noise()`, `noiseSeed()`
+- Full sync between SDK source and npm package
 
-- Protocol Lock section formalized with HARD LOCKED status
-- VAR specification clarified with enforcement tables
+The v1.4.0 npm package had an outdated runtime that used `Math.random()` directly. This release restores determinism.
 
-## v1.0.0 (Protocol Lock)
+## v1.4.0 (Protocol v1.2.0)
+
+**Phase 3 — Pixel & Graphics**
+
+- **Vertex Functions**: `curveVertex(x, y)`, `bezierVertex(cx1, cy1, cx2, cy2, x, y)` for smooth curves
+- **Pixel System**: `loadPixels()`, `updatePixels()`, `pixels[]`, `get(x, y)`, `set(x, y, color)`
+- **Graphics System**: `createGraphics(w, h)`, `image(pg, x, y, w, h)` for offscreen rendering
+- **totalFrames**: Now injected into Loop Mode runtime
+
+## v1.3.0 (Protocol v1.1.0)
+
+**Phase 2 — Expressive Extensions**
+
+- **Math Helpers**: `fract(n)`, `sign(n)`
+- **Vector Helpers**: `vec`, `vecAdd`, `vecSub`, `vecMult`, `vecMag`, `vecNorm`, `vecDist`
+- **Shape Helpers**: `polygon()`, `star()`
+- **Blend Modes**: `blendMode(NORMAL|ADD|MULTIPLY|SCREEN)`
+- **Noise Extensions**: `fbm()`, `ridgedNoise()`, `curlNoise()`
+- **Easing Functions**: `easeIn`, `easeOut`, `easeInOut`, `easeCubic`, `easeExpo`
+
+## v1.2.0
+
+- Added `bezier()`, `curve()`, `strokeCap()`, `strokeJoin()`, `shearX()`, `shearY()`
+- Added text system: `text()`, `textSize()`, `textFont()`, `textAlign()`, `textWidth()`
+- Added `sq()`, `int()`, `TAU`, arc mode constants
+
+## v1.1.1
+
+- **Critical Fix**: `random()` now uses seeded Mulberry32 PRNG (was using Math.random)
+- All randomness is now deterministic
+
+## v1.0.x (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
 
 ---
@@ -88,7 +113,7 @@ This SDK provides the **canonical runtime** for executing p5.js-style generative
 - **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.
+The SDK enforces the **NexArt Code Mode Protocol v1.2.0** for reproducible, mint-safe generative art.
 
 ---
 
@@ -104,8 +129,7 @@ The SDK enforces the **NexArt Code Mode Protocol v1.0.0** for reproducible, mint
 ## Installation
 
 ```bash
-# Copy the sdk/codemode folder to your project
-cp -r sdk/codemode your-project/lib/codemode
+npm install @nexart/codemode-sdk
 ```
 
 ---
@@ -140,7 +164,7 @@ const result = await executeCodeMode({
 // 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.protocolVersion); // '1.2.0'
 console.log(result.metadata.deterministic);   // true
 console.log(result.image);                    // PNG Blob
 ```
@@ -167,8 +191,8 @@ interface ExecuteCodeModeResult {
   metadata: {
     protocol: 'nexart';
     engine: 'codemode';
-    protocolVersion: '1.0.0';
-    phase: 1;
+    protocolVersion: '1.2.0';
+    phase: 3;
     deterministic: true;
     seed: number;
     vars: number[];
@@ -182,67 +206,11 @@ interface ExecuteCodeModeResult {
 
 ---
 
-## 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 './codemode';
-
-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
-});
-```
-
-### `engine.run(options: RunOptions): Promise<void>`
-
-Execute code and produce output.
-
-```typescript
-await engine.run({
-  code: `
-    function setup() {
-      background(255);
-      fill(0);
-      // 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
-  },
-  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);
-  },
-});
-```
-
-### Protocol Variables (VAR[0..9]) — Protocol v1.0.0
+## 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):**
+**VAR Specification:**
 
 | Property | Value | Enforcement |
 |----------|-------|-------------|
@@ -256,20 +224,7 @@ Protocol variables are first-class inputs that control artwork parameters.
 | 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
+// 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);
@@ -285,14 +240,6 @@ function setup() {
 - 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).
-
-### `engine.getConfig(): EngineConfig`
-
-Get the resolved engine configuration.
-
 ---
 
 ## Execution Rules
@@ -320,6 +267,7 @@ Get the resolved engine configuration.
 | `t` | float | Normalized time [0.0, 1.0) |
 | `time` | float | Elapsed seconds |
 | `tGlobal` | float | Alias for `t` |
+| `totalFrames` | int | Total frames in loop (v1.4.0+) |
 
 ---
 
@@ -348,95 +296,40 @@ Additionally in Loop Mode:
 
 ---
 
-## Example: Static Mode
-
-```typescript
-import { createEngine } from './codemode';
-
-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 './codemode';
-
-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 />`;
-  },
-});
-```
-
----
-
 ## Supported Functions
 
-The SDK includes a minimal p5.js-like runtime with:
+The SDK includes a comprehensive p5.js-like runtime with 130+ functions:
 
 **Drawing:**
-`background`, `clear`, `fill`, `noFill`, `stroke`, `noStroke`, `strokeWeight`
+`background`, `clear`, `fill`, `noFill`, `stroke`, `noStroke`, `strokeWeight`, `strokeCap`, `strokeJoin`
 
 **Shapes:**
-`ellipse`, `circle`, `rect`, `square`, `line`, `point`, `triangle`, `quad`, `arc`
+`ellipse`, `circle`, `rect`, `square`, `line`, `point`, `triangle`, `quad`, `arc`, `bezier`, `curve`
 
-**Vertex:**
-`beginShape`, `vertex`, `endShape`
+**Vertex (v1.4.0):**
+`beginShape`, `vertex`, `curveVertex`, `bezierVertex`, `endShape`
+
+**Shape Helpers (v1.3.0):**
+`polygon`, `star`
 
 **Transform:**
-`push`, `pop`, `translate`, `rotate`, `scale`, `resetMatrix`
+`push`, `pop`, `translate`, `rotate`, `scale`, `resetMatrix`, `shearX`, `shearY`
 
 **Color:**
 `colorMode`, `color`, `lerpColor`, `red`, `green`, `blue`, `alpha`, `hue`, `saturation`, `brightness`
 
+**Text:**
+`text`, `textSize`, `textFont`, `textAlign`, `textWidth`
+
+**Blend Modes (v1.3.0):**
+`blendMode(NORMAL|ADD|MULTIPLY|SCREEN)`
+
+**Pixel System (v1.4.0):**
+`loadPixels`, `updatePixels`, `pixels[]`, `get`, `set`
+
+**Graphics (v1.4.0):**
+`createGraphics`, `image`
+
 **Color Formats:**
 All of the following are accepted by `fill()`, `stroke()`, `background()`:
 - Grayscale: `fill(128)`, `fill(128, 127)`
@@ -448,48 +341,40 @@ All of the following are accepted by `fill()`, `stroke()`, `background()`:
 `VAR` — Array of 10 values (VAR[0] through VAR[9])
 
 **Math:**
-`random`, `noise`, `map`, `constrain`, `lerp`, `dist`, `mag`, `norm`
+`random`, `noise`, `map`, `constrain`, `lerp`, `dist`, `mag`, `norm`, `sq`, `int`, `fract`, `sign`
 
-**Trig:**
-`sin`, `cos`, `tan`, `asin`, `acos`, `atan`, `atan2`, `radians`, `degrees`
+**Vectors (v1.3.0):**
+`vec`, `vecAdd`, `vecSub`, `vecMult`, `vecMag`, `vecNorm`, `vecDist`
 
-**Constants:**
-`PI`, `TWO_PI`, `HALF_PI`, `QUARTER_PI`, `width`, `height`, `frameCount`
-
----
+**Noise Extensions (v1.3.0):**
+`fbm`, `ridgedNoise`, `curlNoise`
 
-## Video Encoding
+**Easing (v1.3.0):**
+`easeIn`, `easeOut`, `easeInOut`, `easeCubic`, `easeExpo`
 
-Loop Mode requires server-side video encoding. The SDK calls:
-
-```
-POST /api/encode-loop
-```
-
-Ensure your server has this endpoint available (NexArt provides this).
-
----
-
-## Files
+**Trig:**
+`sin`, `cos`, `tan`, `asin`, `acos`, `atan`, `atan2`, `radians`, `degrees`
 
-```
-sdk/codemode/
-├── index.ts         # Main export
-├── engine.ts        # createEngine entry point
-├── types.ts         # TypeScript types
-├── static-engine.ts # Static mode implementation
-├── loop-engine.ts   # Loop mode implementation
-├── p5-runtime.ts    # p5.js-like runtime
-└── README.md        # This file
-```
+**Constants:**
+`PI`, `TWO_PI`, `TAU`, `HALF_PI`, `QUARTER_PI`, `width`, `height`, `frameCount`, `totalFrames`
 
 ---
 
-## License
+## Frozen Execution Guarantees — v1.0.0
 
-MIT License
+The following guarantees are LOCKED and will not change in v1.x:
 
-Copyright (c) 2024 NexArt
+| 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) |
 
 ---
 
@@ -512,13 +397,13 @@ const result = await executeCodeMode({
   width: 1950,
   height: 2400,
   seed: 12345,
-  vars: [50, 75, 25, 0, 0, 0, 0, 0, 0, 0],  // Exactly 10 values
+  vars: [50, 75, 25, 0, 0, 0, 0, 0, 0, 0],
   mode: 'static'
 });
 
 // Result includes full protocol metadata for verification
 const { image, metadata } = result;
-console.log(metadata.protocolVersion); // '1.0.0'
+console.log(metadata.protocolVersion); // '1.2.0'
 console.log(metadata.deterministic);   // true
 ```
 
@@ -538,27 +423,35 @@ try {
 
 ---
 
-## Frozen Execution Guarantees — v1.0.0
+## Video Encoding
 
-The following guarantees are LOCKED and will not change in v1.x:
+Loop Mode requires server-side video encoding. The SDK calls:
 
-| 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) |
+```
+POST /api/encode-loop
+```
+
+Ensure your server has this endpoint available (NexArt provides this).
+
+---
+
+## Files
+
+```
+@nexart/codemode-sdk/
+├── index.ts         # Main export
+├── engine.ts        # createEngine entry point
+├── types.ts         # TypeScript types
+├── static-engine.ts # Static mode implementation
+├── loop-engine.ts   # Loop mode implementation
+├── p5-runtime.ts    # p5.js-like runtime
+└── README.md        # This file
+```
 
 ---
 
-## Future Work (Phase 2+)
+## License
+
+MIT License
 
-- GSL v1 SDK (protocol layer) — separate package
-- Extended p5.js compatibility
-- WebGL rendering support
-- GIF output option
+Copyright (c) 2024-2026 NexArt

package/dist/engine.d.ts

@@ -1,24 +1,46 @@
 /**
- * NexArt Code Mode Runtime SDK
- * Version: 0.1.0
+ * NexArt Code Mode Runtime SDK - Canonical Execution Entry Point
  *
- * Main entry point for the Code Mode runtime engine.
- *
- * Usage:
- *   const engine = createEngine({ mode: 'static' });
- *   engine.run({
- *     code: 'function setup() { background(255); ellipse(width/2, height/2, 100); }',
- *     onComplete: (result) => console.log(result.blob)
- *   });
+ * ╔══════════════════════════════════════════════════════════════════════════╗
+ * ║  CODE MODE PROTOCOL v1.2.0 (Phase 3) — 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 type { Engine, EngineConfig } from './types';
+import { ExecuteCodeModeInput, ExecuteCodeModeResult } from './types';
 /**
- * Create a NexArt Code Mode rendering engine.
+ * 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
  *
- * @param config - Engine configuration
- * @returns Engine instance
+ * @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.2.0'
+ * console.log(result.image); // PNG Blob
+ * ```
+ */
+export declare function executeCodeMode(input: ExecuteCodeModeInput): Promise<ExecuteCodeModeResult>;
+/**
+ * Validate code without executing
  */
-export declare function createEngine(config: EngineConfig): Engine;
-export type { Engine, EngineConfig, RunOptions, RenderResult, ProgressInfo } from './types';
-export { DEFAULT_CONFIG } from './types';
+export declare function validateCodeModeSource(source: string, mode: 'static' | 'loop'): {
+    valid: boolean;
+    errors: string[];
+};
 //# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,YAAY,EAAc,MAAM,SAAS,CAAC;AAKhE;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CA+CzD;AAGD,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC5F,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../engine.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"}