npm - @nexart/codemode-sdk - Versions diffs - 1.8.0 → 1.8.1 - Mend

@nexart/codemode-sdk 1.8.0 → 1.8.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/CHANGELOG.md CHANGED Viewed

@@ -4,6 +4,45 @@ All notable changes to @nexart/codemode-sdk will be documented in this file.
 ---
+## [1.8.1] — 2026-01-24
+### Changed — Documentation & Licensing Clarity
+**Non-Breaking, Metadata-Only Release**
+This release addresses external review feedback about documentation framing and licensing clarity. No runtime, API, or behavior changes.
+#### Documentation Reframed
+- **Removed app-specific framing** — SDK no longer positioned as "for Frontierra" or "for ByX"
+- **Genre-based language** — Now describes use cases (generative art, games, simulations, research)
+- **"Who this is for / Who this is not for"** section added for clarity
+- **"Where this fits"** section explains architectural boundary
+- **"Why not roll your own?"** section honestly addresses when to skip this SDK
+- **"Used by"** section lists NexArt, ByX, Frontierra as examples (not defining use cases)
+- **Removed "This SDK IS the protocol" language** — Now describes as "reference implementation"
+#### Licensing Clarified
+- **COMMERCIAL.md added** — Plain language licensing terms
+- **Free for**: personal, experiments, research, open-source
+- **Commercial production**: requires license
+- **Contact**: licensing@nexart.xyz
+- **No phase language, no future enforcement language**
+#### Package Updates
+- **Version**: 1.8.1
+- **files**: Added COMMERCIAL.md
+- **homepage**: Added to package.json
+### Unchanged
+- No changes to runtime behavior
+- No changes to APIs or exports
+- No changes to protocol version (remains v1.2.0)
+- No changes to determinism guarantees
+- Full backward compatibility with v1.8.0
+---
 ## [1.8.0] — 2026-01-24
 ### Added — Agent-First Runtime Authority Layer

package/COMMERCIAL.md ADDED Viewed

@@ -0,0 +1,41 @@
+# Commercial Licensing
+## @nexart/codemode-sdk
+---
+## Free Use
+You may use this SDK at no cost for:
+- **Personal projects** — Learning, hobby work, portfolio pieces
+- **Experiments and prototypes** — Proof of concepts, demos, hackathons
+- **Research and education** — Academic work, teaching, scientific research
+- **Open-source projects** — Projects with source code publicly available under an OSI-approved license
+---
+## Commercial Use
+Commercial production deployments require a license.
+**Commercial use includes:**
+- Products or services that generate revenue
+- Internal tools used in commercial operations
+- SaaS applications
+- Games or simulations sold or monetized
+- Enterprise deployments
+---
+## Get a License
+Contact: **licensing@artnames.io**
+We offer flexible licensing options for teams and enterprises.
+---
+## Questions?
+If you're unsure whether your use case requires a license, reach out to licensing@artnames.io. We're happy to help.

package/README.md CHANGED Viewed

@@ -1,25 +1,48 @@
-# NexArt Code Mode Runtime SDK
-**Version: 1.8.0 (Protocol v1.2.0)**
-╔══════════════════════════════════════════════════════════════════════════════╗
-║  @nexart/codemode-sdk — Canonical Execution Surface                          ║
-║                                                                              ║
-║  This SDK IS the protocol. All implementations MUST use this SDK.            ║
-║                                                                              ║
-║  Protocol: nexart                                                            ║
-║  Engine: codemode                                                            ║
-║  SDK Version: 1.8.0                                                          ║
-║  Protocol Version: 1.2.0                                                     ║
-║  Phase: 3                                                                    ║
-║  Enforcement: HARD                                                           ║
-╚══════════════════════════════════════════════════════════════════════════════╝
+# @nexart/codemode-sdk
+**Version: 1.8.1 (Protocol v1.2.0)**
+A deterministic execution runtime for reproducible, verifiable computation.
+---
+## What This SDK Does
+This SDK provides a **deterministic runtime layer** for executing code that must produce identical output given identical inputs — across environments, over time, and under verification.
+**Core guarantees:**
+- Same `seed` + `vars` + `code` → identical output (always)
+- Cross-environment stability (browser, Node.js, CI pipelines)
+- Strict mode blocks non-deterministic APIs (`Math.random`, `Date.now`, etc.)
+- Canonical state snapshots for replay and verification
+- Stable digest for integrity verification
+---
+## Who This Is For
+**Use this SDK if determinism is non-negotiable:**
+- **On-chain generative art** — NFTs, archival renders, mint verification
+- **Procedural games** — Open-world generation, replay systems, save states
+- **Simulations** — Physics, agent-based models, reproducible experiments
+- **Finance research** — Backtesting, Monte Carlo, reproducible analysis
+- **Education labs** — Repeatable demonstrations, grading consistency
+**Skip this SDK if you're building:**
+- CRUD apps
+- Dashboards
+- E-commerce
+- Typical web applications without reproducibility requirements
+For most applications, seeded randomness is unnecessary complexity.
 ---
 ## For AI Coding Agents (Replit / Lovable / Claude Code)
-**ALWAYS use `createRuntime({ seed, strict: true })` for deterministic execution.**
+**Use `createRuntime({ seed, strict: true })` for deterministic execution.**
 ```typescript
 import { createRuntime } from "@nexart/codemode-sdk";
@@ -27,24 +50,70 @@ import { createRuntime } from "@nexart/codemode-sdk";
 const runtime = createRuntime({
   seed: "my-artwork-42",
   vars: [50, 75, 25],
-  strict: true,  // IMPORTANT: Throws on Math.random, Date.now, etc.
+  strict: true,  // Throws on Math.random, Date.now, etc.
   mode: "static"
 });
-// Use runtime.random() instead of Math.random()
-const value = runtime.random();          // Deterministic [0, 1)
-const intVal = runtime.randomInt(0, 10); // Deterministic integer
-const n = runtime.noise(x, y);           // Deterministic Perlin noise
+// Deterministic APIs
+const value = runtime.random();          // [0, 1)
+const intVal = runtime.randomInt(0, 10); // integer in range
+const n = runtime.noise(x, y);           // Perlin noise
-// Verify determinism
-console.log(runtime.digest());  // Stable hash for verification
+// Verification
+console.log(runtime.digest());   // Stable hash
 console.log(runtime.getState()); // Canonical state snapshot
 ```
 **Strict mode throws actionable errors:**
 - `NEXART_STRICT: Non-deterministic API used: Math.random. Use runtime.random() instead.`
 - `NEXART_STRICT: Non-deterministic API used: Date.now. Pass time as an input or use deterministic counters.`
-- `NEXART_STRICT: Non-deterministic API used: performance.now.`
+---
+## Where This Fits
+```
+┌─────────────────────────────────────────────────────────┐
+│  Your Application                                       │
+│  (React, Canvas, Three.js, game engine, simulation)     │
+└────────────────────────┬────────────────────────────────┘
+                         │
+                         ▼
+┌─────────────────────────────────────────────────────────┐
+│  @nexart/codemode-sdk                                   │
+│  Deterministic runtime layer                            │
+│  - Seeded PRNG (Mulberry32)                             │
+│  - Seeded noise (Perlin)                                │
+│  - Strict mode enforcement                              │
+│  - State snapshots + digest                             │
+└────────────────────────┬────────────────────────────────┘
+                         │
+                         ▼
+┌─────────────────────────────────────────────────────────┐
+│  Output                                                 │
+│  - Deterministic result                                 │
+│  - Verification digest                                  │
+│  - Replay state                                         │
+└─────────────────────────────────────────────────────────┘
+```
+The SDK sits between your UI/framework and your output. It does not render, does not manage state, does not touch the DOM. It provides deterministic primitives.
+---
+## Why Not Roll Your Own?
+**What's easy:**
+- Seeded PRNG (dozens of implementations exist)
+- Noise libraries (simplex, Perlin, available everywhere)
+**What's hard:**
+- **Cross-environment stability** — Same seed producing same sequence across browser versions, Node.js versions, bundlers, and platforms
+- **Strict enforcement** — Actually blocking `Math.random()` and `Date.now()` during execution, with actionable error messages
+- **Replay and verification** — Canonical state snapshots that can reconstruct execution
+- **Long-term drift resistance** — Guaranteeing identical output years later, not just today
+If you need a quick seeded random, use any PRNG. If you need guaranteed reproducibility across time, environments, and verification systems — that's what this SDK provides.
 ---
@@ -60,14 +129,14 @@ console.log(runtime.getState()); // Canonical state snapshot
 - `Math.random()` — use `runtime.random()` instead
 - `Date.now()` — pass time as input or use frame counters
 - `performance.now()` — use deterministic timing
-- External IO during deterministic runs (not supported)
+- External IO during deterministic runs
 ---
-## Why Not Just Use a PRNG?
+## Feature Comparison
-| Feature | Plain PRNG | NexArt Runtime |
-|---------|-----------|----------------|
+| Feature | Plain PRNG | This SDK |
+|---------|-----------|----------|
 | Seeded random | ✅ | ✅ |
 | Seeded noise | ❌ (separate lib) | ✅ built-in |
 | Strict mode (blocks entropy) | ❌ | ✅ |
@@ -77,8 +146,6 @@ console.log(runtime.getState()); // Canonical state snapshot
 | Replay/verification | Manual | Built-in |
 | Error messages for agents | ❌ | ✅ actionable |
-**The runtime provides a complete determinism layer, not just random numbers.**
 ---
 ## Environment Imports
@@ -89,64 +156,64 @@ console.log(runtime.getState()); // Canonical state snapshot
 | Node.js (general use) | `import { createRuntime } from "@nexart/codemode-sdk"` |
 | Node.js server rendering (canvas) | `import { executeCodeMode } from "@nexart/codemode-sdk/node"` |
-**The default import is always browser-safe.** Node-only features (`executeCodeMode`, `runStaticMode`) require explicit `/node` import.
+**The default import is browser-safe.** Node-only features require explicit `/node` import.
 ---
-## License
+## Used By
-**Free for:**
-- Experiments and prototypes
-- Personal projects
-- Open-source projects
+- **NexArt** — Generative art platform
+- **ByX** — Curated collections
+- **Frontierra** — External builder integration
-**Commercial production deployments require a license.** See [LICENSING.md](./LICENSING.md) for details.
+These are examples — the SDK is designed for any system requiring deterministic execution.
 ---
-## PROTOCOL LOCK — v1.x
+## Protocol Stability
 | Property | Value |
 |----------|-------|
-| Protocol Name | NexArt Code Mode |
-| Version | v1.2.0 |
+| Protocol Version | v1.2.0 |
 | Status | **STABLE** |
-| Phase | 3 |
-| Lock Date | January 2026 |
-**Core protocol surface is frozen. Any breaking change requires v2.0.0.**
+| SDK Version | 1.8.1 |
-The following are locked and will not change in v1.x:
+**Core protocol surface is frozen. Breaking changes require v2.0.0.**
+The following are locked 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)
+- VAR[0..9] specification
+- Determinism guarantee
 - Time semantics (t, frameCount, time, tGlobal, totalFrames)
-- Random and noise behavior (seeded Mulberry32, Perlin)
-- Forbidden patterns list (13 patterns)
-- Canvas pre-initialization (no createCanvas)
+- Random and noise behavior
+- Forbidden patterns list
 ---
-A minimal, deterministic rendering engine for generative art.
+## Licensing
+Free for personal projects, experiments, research, and open-source.
-## Protocol Authority
+Commercial production deployments require a license.
-**This SDK is the single source of truth for Code Mode semantics.**
+See [COMMERCIAL.md](./COMMERCIAL.md) for details.
-If someone asks: "How does Code Mode work in NexArt?"
+---
+## Installation
-The answer is: "Whatever @nexart/codemode-sdk does — that is the protocol."
+```bash
+npm install @nexart/codemode-sdk
+```
 ---
-## What's New in v1.8.0
+## Runtime API
-**Agent-First Runtime Authority Layer**
+### `createRuntime(options)`
-This release introduces `createRuntime()` — an agent-first API designed for AI coding assistants to reliably execute deterministic code.
+Create a deterministic runtime instance.
-### New Runtime API
 ```typescript
 import { createRuntime } from "@nexart/codemode-sdk";
@@ -167,239 +234,52 @@ runtime.run(() => { ... }); // Execute with strict enforcement
 ```
 ### Strict Mode
-- Throws actionable errors on `Math.random`, `Date.now`, `performance.now`
-- Only applies during `runtime.run()` — non-invasive
-- Error messages guide agents to correct usage
-### Agent-First Documentation
-- "For AI Coding Agents" section at top of README
-- Determinism Contract with ✅/❌ checklist
-- PRNG comparison table
-- Environment import matrix
-### Examples
-- `npm run example:basic` — Basic usage demonstration
-- `npm run example:verify` — Determinism verification tests
-### No Breaking Changes
-- All existing APIs work unchanged
-- Default import remains browser-safe
-- Protocol version unchanged (v1.2.0)
----
-## What's New in v1.7.0
-**Browser-Safe Entrypoint + Conditional Exports**
-This release makes the SDK reliably usable in browser environments (Vite/React) without any Node.js dependency leakage.
-### New Entry Points
-- `@nexart/codemode-sdk/browser` — Browser-safe modules only (no Node.js dependencies)
-- `@nexart/codemode-sdk/node` — Full SDK including static-engine (requires `canvas` package)
-### Package.json Conditional Exports
-- Default import (`.`) now uses conditional exports: browser gets browser entry, Node gets Node entry
-- Explicit subpaths: `./browser` and `./node` for direct control
-### Why This Matters
-- AI agents and bundlers will no longer accidentally import Node.js modules in browser builds
-- Vite/React apps can safely import the SDK without "createRequire is not defined" errors
-- Server-side code gets full functionality including static image rendering
-### No Breaking Changes
-- Protocol behavior and determinism unchanged
-- API surface unchanged
-- Existing Node.js code continues to work
----
-## What's New in v1.6.0
-**Licensing & Builder Identity Scaffolding (Metadata Only)**
-This is a non-breaking, metadata-only release. No changes to execution or determinism.
-### Licensing (Informational Only)
-- Added `LICENSE.md` with draft commercial licensing terms
-- Enforcement is NOT active — all usage currently permitted under MIT
-### Builder Manifest Schema
-- Added `builder.manifest.schema.json` for optional builder attribution
-- Fields: `builder_id`, `project_name`, `contact`, `website`, `intended_use`
-- This file is **optional**, **not validated**, and **not loaded at runtime**
-### Documentation
-- SDK positioned as "canonical execution surface"
-- Explicit determinism guarantees documented
-- Real product references (ByX, Frontierra)
----
-## Determinism Guarantees
-**The NexArt Code Mode SDK guarantees deterministic output.**
-Given identical inputs:
-- Same `source` code
-- Same `seed`
-- Same `vars` array
-- Same `width` and `height`
-- Same `mode`
-The SDK will produce **byte-for-byte identical output** across all executions.
+When `strict: true`, the runtime intercepts non-deterministic APIs during `run()`:
-### What Breaks Determinism
-The following actions will break determinism and are **blocked** by the SDK:
-| Pattern | Reason | Enforcement |
-|---------|--------|-------------|
-| `Math.random()` | Unseeded randomness | BLOCKED |
-| `Date.now()` | Time-based entropy | BLOCKED |
-| `new Date()` | Time-based entropy | BLOCKED |
-| `performance.now()` | Timing entropy | BLOCKED |
-| `crypto.getRandomValues()` | Crypto randomness | BLOCKED |
-| `fetch()` | External IO | BLOCKED |
-| External imports | Uncontrolled code | BLOCKED |
-Use `random()` (seeded) and `noise()` (seeded) for all randomness needs.
-### Oracle Verification
-Before any release, run the determinism check:
-```bash
-npx tsx scripts/check-determinism.ts
+```typescript
+runtime.run(() => {
+  Math.random();  // Throws: NEXART_STRICT: Non-deterministic API used
+});
 ```
-This compares output against a known oracle hash. If the hash changes without a protocol version bump, the release is invalid.
----
-## Products Using This SDK
-- **NexArt**: Primary generative art platform
-- **ByX**: Curated collection system
-- **Frontierra**: External builder integration
----
-## v1.5.1
-**Builder Manifest — Passive Attribution (Write-Only)**
-- `registerBuilderManifest(manifest?)` — Declare builder identity for future attribution
-The Builder Manifest is a declaration of intent, not a capability. Write-only, optional, non-enforced.
----
-## 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
-- **VAR[0..9] Protocol Variables**: First-class protocol inputs (read-only, 0-100)
-- **Determinism Guarantee**: Same code + seed + vars = identical output
----
-## What This SDK Is
-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.2.0** for reproducible, mint-safe generative art.
----
-## What This SDK Is NOT
-- **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
----
-## Installation
-```bash
-# Copy the sdk/codemode folder to your project
-cp -r sdk/codemode your-project/lib/codemode
-```
+Strict mode:
+- Only applies during `runtime.run()` — non-invasive
+- Does NOT globally mutate your application
+- Provides actionable error messages
 ---
-## Browser Usage (v1.7.0+)
+## Browser Usage
-For Vite, React, Next.js, or any browser environment, import from the browser-safe entry:
+For Vite, React, Next.js, or any browser environment:
 ```typescript
 import {
+  createRuntime,
   runLoopMode,
   cancelLoopMode,
   createP5Runtime,
   validateCodeModeSource,
-  PROTOCOL_IDENTITY,
-  DEFAULT_CONFIG,
-} from '@nexart/codemode-sdk/browser';
+} from '@nexart/codemode-sdk';
 ```
-**What's included in `@nexart/codemode-sdk/browser`:**
-- All types (RenderMode, EngineConfig, ExecuteCodeModeInput, etc.)
+**What's included:**
+- Runtime API (createRuntime)
 - P5 runtime (createP5Runtime, injectTimeVariables, injectProtocolVariables)
 - Loop engine (runLoopMode, cancelLoopMode)
 - Execution sandbox (FORBIDDEN_APIS, createSafeMath)
 - Validation (validateCodeModeSource)
-- Builder manifest (registerBuilderManifest)
 **What's NOT included (Node.js only):**
-- `executeCodeMode` — Uses static-engine which requires Node.js canvas
-- `runStaticMode` — Requires Node.js canvas package
-For static rendering in browser apps, use your server-side API endpoint.
+- `executeCodeMode` — Requires Node.js canvas
+- `runStaticMode` — Requires Node.js canvas
 ---
-## Node.js Usage (v1.7.0+)
+## Node.js Usage
-For server-side rendering, oracles, or CLI tools, import from the Node entry:
+For server-side rendering, oracles, or CLI tools:
 ```typescript
 import {
@@ -410,27 +290,20 @@ import {
 } from '@nexart/codemode-sdk/node';
 ```
-**What's included in `@nexart/codemode-sdk/node`:**
-- Everything from the browser entry
-- `executeCodeMode` — Canonical execution API
-- `runStaticMode` — Node.js static rendering (requires `canvas` package)
 **Requirements:**
 - Node.js 18+
-- `canvas` package installed for static mode (`npm install canvas`)
+- `canvas` package for static mode
 ---
-## Canonical API
+## Canonical Execution API
-### `executeCodeMode(input: ExecuteCodeModeInput): Promise<ExecuteCodeModeResult>`
+### `executeCodeMode(input): Promise<Result>`
-**This is the official, canonical entry point for Code Mode execution.**
-All implementations MUST use this function.
+For systems requiring p5.js-style execution with full protocol metadata:
 ```typescript
-import { executeCodeMode } from '@nexart/codemode-sdk';
+import { executeCodeMode } from '@nexart/codemode-sdk/node';
 const result = await executeCodeMode({
   source: `
@@ -448,180 +321,24 @@ const result = await executeCodeMode({
   mode: 'static'
 });
-// Result includes protocol metadata
-console.log(result.metadata.protocol);        // 'nexart'
-console.log(result.metadata.engine);          // 'codemode'
-console.log(result.metadata.protocolVersion); // '1.2.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;
-  }
-}
-```
----
-## 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 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
-}
+console.log(result.metadata.deterministic); // true
+console.log(result.image);                  // PNG Blob
 ```
-**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).
-### `engine.getConfig(): EngineConfig`
-Get the resolved engine configuration.
 ---
 ## Execution Rules
 ### Static Mode
-1. `setup()` is executed once
-2. `draw()` is **NOT** executed
-3. Canvas is captured as PNG
-4. Time variables are all `0`
+1. `setup()` executes once
+2. `draw()` is NOT executed
+3. Canvas captured as PNG
+4. Time variables are 0
 ### Loop Mode
-1. `setup()` is executed once
-2. `draw()` is executed once per frame
-3. Canvas is **cleared** before each `draw()` call
-4. If artist calls `background()` in draw, it paints over the clear
-5. No canvas persistence between frames
+1. `setup()` executes once
+2. `draw()` executes per frame
+3. Canvas cleared before each `draw()`
 **Time Variables:**
@@ -631,277 +348,49 @@ 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 |
 ---
-## Forbidden Patterns — LOCKED v1.0.0
+## Forbidden Patterns
-The following 13 patterns are rejected with `[Code Mode Protocol Error]`:
+The following 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 './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 comprehensive p5.js-like runtime with 130+ functions:
-**Drawing:**
-`background`, `clear`, `fill`, `noFill`, `stroke`, `noStroke`, `strokeWeight`, `strokeCap`, `strokeJoin`
-**Shapes:**
-`ellipse`, `circle`, `rect`, `square`, `line`, `point`, `triangle`, `quad`, `arc`, `bezier`, `curve`
-**Vertex (v1.4.0):**
-`beginShape`, `vertex`, `curveVertex`, `bezierVertex`, `endShape`
-**Shape Helpers (v1.3.0):**
-`polygon`, `star`
-**Transform:**
-`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)`
-- 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`, `sq`, `int`, `fract`, `sign`
-**Vectors (v1.3.0):**
-`vec`, `vecAdd`, `vecSub`, `vecMult`, `vecMag`, `vecNorm`, `vecDist`
-**Noise Extensions (v1.3.0):**
-`fbm`, `ridgedNoise`, `curlNoise`
-**Easing (v1.3.0):**
-`easeIn`, `easeOut`, `easeInOut`, `easeCubic`, `easeExpo`
-**Trig:**
-`sin`, `cos`, `tan`, `asin`, `acos`, `atan`, `atan2`, `radians`, `degrees`
-**Constants:**
-`PI`, `TWO_PI`, `TAU`, `HALF_PI`, `QUARTER_PI`, `width`, `height`, `frameCount`, `totalFrames`
----
-## Video Encoding
-Loop Mode requires server-side video encoding. The SDK calls:
-```
-POST /api/encode-loop
-```
-Ensure your server has this endpoint available (NexArt provides this).
+| `Math.random()` | Use seeded `random()` |
+| `Date.now()` | Time-based entropy |
+| `new Date()` | Time-based entropy |
+| `performance.now()` | Timing entropy |
+| `crypto.getRandomValues()` | Crypto randomness |
+| `fetch()` | External IO |
+| `setTimeout` | Async timing |
+| `setInterval` | Async timing |
+| `requestAnimationFrame` | Async timing |
+| `document.*` | DOM access |
+| `window.*` | DOM access |
+| `import` | External imports |
+| `require()` | External imports |
 ---
-## Files
+## Examples
-```
-sdk/codemode/
-├── entry/
-│   ├── browser.ts    # Browser-safe entry point (v1.7.0)
-│   └── node.ts       # Node.js entry point (v1.7.0)
-├── index.ts          # Main export (app integration layer)
-├── core-index.ts     # Core runtime exports
-├── execute.ts        # executeCodeMode canonical entry point
-├── engine.ts         # createEngine entry point (legacy)
-├── types.ts          # TypeScript types
-├── static-engine.ts  # Static mode implementation (Node.js)
-├── loop-engine.ts    # Loop mode implementation (browser)
-├── p5-runtime.ts     # p5.js-like runtime
-├── execution-sandbox.ts # Determinism enforcement
-├── builder-manifest.ts # Builder manifest (write-only)
-├── CHANGELOG.md      # Version history
-└── README.md         # This file
+```bash
+npm run example:basic   # Basic usage
+npm run example:verify  # Determinism verification
 ```
 ---
-## License
+## Changelog
-MIT License
-Copyright (c) 2024-2026 NexArt
+See [CHANGELOG.md](./CHANGELOG.md) for version history.
 ---
-## 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.2.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) |
----
+## About
-## Future Work (Phase 4+)
+This SDK is a reference implementation of a deterministic execution protocol designed for replay, verification, and long-term stability.
-- External asset loading (controlled)
-- WebGL/3D rendering support
-- GIF output option
-- GSL v1 SDK (protocol layer) — separate package
+It prioritizes correctness and reproducibility over features.

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@nexart/codemode-sdk",
-  "version": "1.8.0",
+  "version": "1.8.1",
   "description": "NexArt Code Mode SDK - Deterministic, reproducible, verifiable generative art runtime. Agent-first design for AI coding assistants.",
   "type": "module",
   "main": "./dist/entry/browser.js",
@@ -40,7 +40,7 @@
     "CHANGELOG.md",
     "CODE_MODE_PROTOCOL.md",
     "LICENSE.md",
-    "LICENSING.md",
+    "COMMERCIAL.md",
     "builder.manifest.schema.json"
   ],
   "scripts": {
@@ -78,6 +78,7 @@
     "type": "git",
     "url": "https://github.com/artnames/nexart-codemode-sdk.git"
   },
+  "homepage": "https://github.com/artnames/nexart-codemode-sdk#readme",
   "publishConfig": {
     "access": "public"
   },