@nexart/codemode-sdk 1.1.0 → 1.1.1

package/CHANGELOG.md

@@ -0,0 +1,109 @@
+# Changelog
+
+All notable changes to @nexart/codemode-sdk will be documented in this file.
+
+---
+
+## [1.1.1] — 2024-12-31
+
+### Critical Bug Fix: Seeded Random
+
+**BREAKING FIX**: The published npm package (v1.1.0 and earlier) had a critical bug where `random()` used `Math.random()` instead of the seeded Mulberry32 PRNG. This broke determinism guarantees.
+
+#### Fixed
+- `random()` now correctly uses seeded Mulberry32 PRNG
+- `randomSeed(seed)` now properly recreates the RNG with new seed
+- `randomGaussian()` now uses seeded Box-Muller transform
+- `noise()` now uses proper seeded Perlin noise with octaves
+- `noiseSeed(seed)` now properly recreates the noise generator
+- `lerpColor()` now properly interpolates colors (was returning c1)
+
+#### Changed
+- Rebuilt package with proper TypeScript compilation
+- Added standalone package.json and tsconfig.json for clean builds
+- New entry point: `core-index.ts` (excludes external dependencies)
+
+#### Verification
+```javascript
+// Same seed = same output (determinism restored)
+randomSeed(42);
+console.log(random()); // Always 0.8379...
+console.log(random()); // Always 0.9032...
+```
+
+---
+
+## [1.1.0] — 2024-12-30
+
+### Minor Bump for npm Publishing (DEPRECATED)
+
+**WARNING**: This version had a critical bug. Use v1.1.1 or later.
+
+- Updated SDK version from 1.0.2 to 1.1.0
+- Protocol version remains v1.0.0 (unchanged)
+- No breaking changes from 1.0.2
+
+---
+
+## [1.0.2] — 2024-12-30
+
+### Changed
+
+- **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, NO clamping)
+  - Runtime VAR is ALWAYS 10 elements (padded with zeros for consistency)
+- **VAR enforcement updated**
+  - Read-only via Proxy (throws on write attempts)
+  - Out-of-range values now throw (previously warned)
+- **Backwards compatible**: existing code passing 10 elements works unchanged
+
+---
+
+## [1.0.1] — 2024-12-29
+
+### Documentation
+
+- Protocol Lock section formalized with HARD LOCKED status
+- VAR specification clarified with enforcement tables
+- CHANGELOG added to track version history
+- Smoke tests added for cross-SDK verification
+
+---
+
+## [1.0.0] — 2024-12-29
+
+### Protocol Lock
+
+**NexArt Code Mode Protocol v1.0.0 is now HARD LOCKED.**
+
+This version establishes the canonical Code Mode execution surface for:
+- NexArt app
+- ByX curated collections
+- External builders and AI platforms
+
+### Frozen
+
+The following are locked and will not change in v1.x:
+
+- **Execution Model**: Static (setup-only) and Loop (frame-authoritative) modes
+- **VAR[0..9]**: Exactly 10 read-only protocol variables (0-100 recommended)
+- **Determinism**: Same code + same seed + same VARs = identical output
+- **Time Semantics**: t ∈ [0,1), frameCount, time, tGlobal
+- **Random**: Seeded Mulberry32 PRNG via random()
+- **Noise**: Seeded Perlin noise via noise()
+- **Forbidden Patterns**: 13 patterns rejected with [Code Mode Protocol Error]
+- **Canvas**: Pre-initialized, no createCanvas()
+
+### API
+
+- `executeCodeMode()` — Canonical entry point for all Code Mode execution
+- `validateCodeModeSource()` — Pre-flight validation without execution
+- `createEngine()` — Legacy API (still supported)
+
+### Notes
+
+- Any breaking change requires v2.0.0
+- VAR count is fixed at 10 and will not be extended
+- This version enables external builders to depend on stable protocol semantics

package/CODE_MODE_PROTOCOL.md

@@ -0,0 +1,312 @@
+# Code Mode Protocol v1.0.0 — Phase 1
+
+> **Status:** LOCKED  
+> **Enforcement:** HARD  
+> **Effective Date:** December 2024
+
+This document is **normative**. It defines the official Code Mode execution surface for NexArt Protocol. All implementations (NexArt app, ByX, external builders) MUST conform to this specification.
+
+---
+
+## 1. Protocol Identity
+
+| Property | Value |
+|----------|-------|
+| Protocol | `nexart` |
+| Engine | `codemode` |
+| Version | `1.0.0` |
+| Phase | `1` |
+| Deterministic | `true` |
+
+---
+
+## 2. Execution Modes
+
+### 2.1 Static Mode
+- Executes `setup()` once
+- `draw()` is **NOT** executed
+- Output: Single PNG image
+- Time variables: All `0`
+
+### 2.2 Loop Mode
+- Executes `setup()` once
+- Executes `draw()` for each frame
+- Canvas is cleared before each `draw()` call
+- Output: MP4 video (1-4 seconds, 30 FPS)
+- Requires `totalFrames` to be specified
+
+---
+
+## 3. Protocol Variables (VAR[0..9])
+
+### 3.1 Definition
+- Input: 0-10 elements allowed (protocol error if > 10)
+- Runtime: ALWAYS 10 elements (padded with zeros)
+- Type: `readonly number[]`
+- Range: `0` to `100` (strict — protocol error if out of range)
+- Default: All zeros `[0, 0, 0, 0, 0, 0, 0, 0, 0, 0]`
+
+### 3.2 Access
+```javascript
+// ✅ Allowed - reading (missing indices return 0)
+let size = VAR[0];        // Returns provided value or 0
+let opacity = map(VAR[1], 0, 100, 0, 255);
+
+// ❌ Forbidden - writing (throws protocol error)
+VAR[0] = 50; // [Code Mode Protocol Error] VAR is read-only
+```
+
+### 3.3 Enforcement
+| Condition | Enforcement |
+|-----------|-------------|
+| Input length > 10 | HARD — throws protocol error |
+| Value outside 0-100 | HARD — throws protocol error |
+| Non-number value | HARD — throws protocol error |
+| Write attempt | HARD — throws protocol error |
+| Missing input | Runtime padded with zeros |
+
+- Input is normalized to 10 elements (padded with zeros)
+- VAR is wrapped in a write-blocking Proxy
+- Write attempts MUST throw an error
+- Write attempts MUST NOT modify values
+
+---
+
+## 4. Supported Globals
+
+### 4.1 Canvas Environment
+| Global | Type | Description |
+|--------|------|-------------|
+| `width` | `number` | Canvas width (default: 1950) |
+| `height` | `number` | Canvas height (default: 2400) |
+
+### 4.2 Time Variables
+| Global | Type | Description |
+|--------|------|-------------|
+| `frameCount` | `number` | Current frame (0, 1, 2, ...) |
+| `t` | `number` | Normalized time [0.0, 1.0) |
+| `time` | `number` | Elapsed seconds |
+| `tGlobal` | `number` | Alias for `t` |
+
+### 4.3 Math Constants
+| Global | Value |
+|--------|-------|
+| `PI` | `3.141592653589793` |
+| `TWO_PI` | `6.283185307179586` |
+| `HALF_PI` | `1.5707963267948966` |
+| `QUARTER_PI` | `0.7853981633974483` |
+| `TAU` | `6.283185307179586` |
+
+---
+
+## 5. Supported Functions (Phase 1)
+
+### 5.1 Drawing Primitives
+- `line(x1, y1, x2, y2)`
+- `rect(x, y, w, h, [r])`
+- `ellipse(x, y, w, h)`
+- `circle(x, y, d)`
+- `triangle(x1, y1, x2, y2, x3, y3)`
+- `quad(x1, y1, x2, y2, x3, y3, x4, y4)`
+- `arc(x, y, w, h, start, stop, [mode])`
+- `point(x, y)`
+- `beginShape()` / `vertex(x, y)` / `endShape([close])`
+- `bezier(x1, y1, cx1, cy1, cx2, cy2, x2, y2)`
+- `curve(x1, y1, x2, y2, x3, y3, x4, y4)`
+
+### 5.2 Style
+- `fill(...)` — Supports all CSS color formats
+- `noFill()`
+- `stroke(...)` — Supports all CSS color formats
+- `noStroke()`
+- `strokeWeight(w)`
+- `strokeCap(cap)`
+- `strokeJoin(join)`
+- `background(...)` — Supports all CSS color formats
+- `colorMode(mode, [max1], [max2], [max3], [maxA])`
+
+### 5.3 Color Functions
+- `color(...)` — Create color object
+- `lerpColor(c1, c2, amt)` — Interpolate colors
+- `red(c)` / `green(c)` / `blue(c)` / `alpha(c)` — Extract components
+- `hue(c)` / `saturation(c)` / `brightness(c)` — HSB extraction
+
+### 5.4 Transforms
+- `push()` / `pop()`
+- `translate(x, y)`
+- `rotate(angle)`
+- `scale(s)` / `scale(sx, sy)`
+- `resetMatrix()`
+- `shearX(angle)` / `shearY(angle)`
+
+### 5.5 Random (Seeded)
+- `random([min], [max])` — Seeded pseudo-random
+- `randomSeed(seed)` — Set random seed
+- `randomGaussian([mean], [sd])` — Seeded Gaussian
+
+### 5.6 Noise (Seeded)
+- `noise(x, [y], [z])` — Seeded Perlin noise
+- `noiseSeed(seed)` — Set noise seed
+- `noiseDetail(octaves, [falloff])` — Configure noise
+
+### 5.7 Math Utilities
+- `map(value, start1, stop1, start2, stop2)`
+- `constrain(value, min, max)`
+- `lerp(start, stop, amt)`
+- `dist(x1, y1, x2, y2)`
+- `mag(x, y)`
+- `norm(value, start, stop)`
+- `abs()` / `floor()` / `ceil()` / `round()` / `sqrt()` / `pow()` / `exp()` / `log()`
+- `sin()` / `cos()` / `tan()` / `asin()` / `acos()` / `atan()` / `atan2()`
+- `min()` / `max()`
+- `radians(degrees)` / `degrees(radians)`
+
+### 5.8 Text
+- `text(str, x, y)`
+- `textSize(size)`
+- `textFont(font)`
+- `textAlign(horizAlign, [vertAlign])`
+- `textWidth(str)`
+
+### 5.9 Image/Pixel
+- `loadPixels()` / `updatePixels()`
+- `get(x, y)` / `set(x, y, color)`
+- `pixels[]` — Pixel array
+- `createGraphics(w, h)` — Offscreen buffer
+
+---
+
+## 6. Forbidden Patterns
+
+The following patterns are **explicitly forbidden** and MUST throw errors:
+
+| Pattern | Reason |
+|---------|--------|
+| `setTimeout()` | Async timing breaks determinism |
+| `setInterval()` | Async timing breaks determinism |
+| `requestAnimationFrame()` | Async timing breaks determinism |
+| `noLoop()` (in Loop Mode) | Incompatible with frame capture |
+| `createCanvas()` | Canvas is pre-initialized |
+| `fetch()` / `XMLHttpRequest` | External IO breaks determinism |
+| `import` / `require` | No external modules |
+| DOM manipulation | No direct DOM access |
+| `Date.now()` / `new Date()` | Time-based entropy breaks determinism |
+| `Math.random()` | Use `random()` instead (seeded) |
+
+---
+
+## 7. Determinism Guarantees
+
+### 7.1 Invariant
+```
+Same code + Same seed + Same VARs = Identical output
+```
+
+### 7.2 Sources of Randomness
+- **Allowed:** `random()`, `noise()` — Both are seeded
+- **Forbidden:** `Math.random()`, `Date`, browser entropy
+
+### 7.3 Verification
+Any execution can be verified by re-running with the same inputs.
+
+---
+
+## 8. Canonical Execution API
+
+### 8.1 Entry Point
+```typescript
+executeCodeMode({
+  source: string,
+  width: number,
+  height: number,
+  seed: number,
+  vars?: number[],
+  mode: 'static' | 'loop',
+  totalFrames?: number
+}) => Promise<ExecutionResult>
+```
+
+### 8.2 Result Structure
+```typescript
+interface ExecutionResult {
+  image?: Blob;           // Static mode: PNG
+  video?: Blob;           // Loop mode: MP4
+  frames?: ImageData[];   // Optional: raw frames
+  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;
+  }
+}
+```
+
+---
+
+## 9. Implementation Requirements
+
+### 9.1 SDK Authority
+- `@nexart/codemode-sdk` is the single source of truth
+- NexArt app, ByX, and external clients MUST delegate to this SDK
+- No other renderer may redefine Code Mode semantics
+
+### 9.2 Logging
+All executions MUST log:
+```
+[CodeMode] Rendered via @nexart/codemode-sdk (Protocol v1.0.0)
+```
+
+### 9.3 Error Handling
+- Missing `draw()` in Loop Mode → Error
+- Missing `totalFrames` in Loop Mode → Error
+- VAR mutation attempt → Warning + Error log (no crash)
+- Unsupported function → Clear error message
+
+---
+
+## 10. Non-Goals (Phase 1)
+
+The following are **explicitly NOT part of Phase 1**:
+
+- ❌ Sliders or UI controls
+- ❌ Additional VAR slots beyond 10
+- ❌ New drawing primitives
+- ❌ WebGL or 3D rendering
+- ❌ Audio input/output
+- ❌ External asset loading
+- ❌ Performance optimizations
+
+---
+
+## 11. Future Phases
+
+| Phase | Scope |
+|-------|-------|
+| Phase 2 | Additional primitives, shader support |
+| Phase 3 | External asset loading (controlled) |
+| Phase 4 | WebGL/3D support |
+
+Each phase requires a protocol version bump and formal specification.
+
+---
+
+## 12. Changelog
+
+### v1.0.0 (December 2024)
+- Initial locked specification
+- VAR[0..9] read-only protocol variables
+- Full CSS color support
+- Seeded random/noise
+- Static + Loop modes
+- HARD enforcement enabled
+
+---
+
+**End of Specification**