@nexart/codemode-sdk 1.8.1 → 1.8.2

package/CHANGELOG.md

@@ -4,6 +4,52 @@ All notable changes to @nexart/codemode-sdk will be documented in this file.
 
 ---
 
+## [1.8.2] — 2026-01-24
+
+### Changed — AI Agent Adoption Friction Reduction
+
+**Non-Breaking, Documentation-Only Release**
+
+This release addresses external review feedback (Grok/Lovable/Replit) about AI agent adoption friction. No runtime, API, or behavior changes. Protocol remains v1.2.0.
+
+#### Agent Quickstart Example Added
+- **New `examples/agent-quickstart.ts`** — Copy-paste ready reference for AI agents
+  - Uses ONLY `createRuntime()` (modern, agent-first API)
+  - No canvas, no p5, browser-safe
+  - Demonstrates: seed → runtime → deterministic ops → digest → verification
+  - Shows strict mode enforcement and error handling
+
+#### Documentation Clarified — Entrypoint Selection
+- **"Which API should I use?"** section added to README
+  - Decision table: `createRuntime()` vs `executeCodeMode()`
+  - Clear guidance: `createRuntime()` = DEFAULT, `executeCodeMode()` = legacy/node-only
+- **"For AI coding agents"** section expanded with:
+  - Quick rules: always `createRuntime()`, never `Math.random()`, always `strict: true`
+  - Link to `examples/agent-quickstart.ts`
+  - Detailed strict mode explanation (why it exists, scoping, restoration)
+
+#### Version Consistency Pass
+- **New `version.ts`** — Single source of truth for SDK_VERSION, PROTOCOL_VERSION, PROTOCOL_PHASE
+- All programmatic exports (runtime.ts, core-index.ts, entry/browser.ts) now import from version.ts
+- Eliminates version drift between package.json, runtime exports, and documentation
+- All documentation updated to reference version 1.8.2
+- README, CHANGELOG, package.json all synchronized
+
+#### Package Updates
+- **Version**: 1.8.2
+- **New script**: `npm run example:agent` — Run agent quickstart example
+
+### 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
+- No changes to strict mode enforcement
+- Full backward compatibility with v1.8.1
+
+---
+
 ## [1.8.1] — 2026-01-24
 
 ### Changed — Documentation & Licensing Clarity

package/LICENSE.md

@@ -1,6 +1,6 @@
 NexArt Code Mode SDK — License
 
-Version: 1.6.0
+See package.json for current version
 Status: DRAFT — Enforcement Not Active
 
 ⸻
@@ -20,10 +20,10 @@ Future Commercial Licensing (Not Active)
 NexArt intends to introduce a separate commercial license for specific categories of usage in a future release.
 
 Planned commercial usage categories may include (non-exhaustive):
-	•	Minting NFTs for sale
-	•	Revenue-generating applications
-	•	Products or services that charge fees
-	•	Enterprise or business deployments
+        •       Minting NFTs for sale
+        •       Revenue-generating applications
+        •       Products or services that charge fees
+        •       Enterprise or business deployments
 
 Enforcement is NOT active.
 

package/README.md

@@ -1,11 +1,38 @@
 # @nexart/codemode-sdk
 
-**Version: 1.8.1 (Protocol v1.2.0)**
+**Version: 1.8.2 (Protocol v1.2.0)**
 
 A deterministic execution runtime for reproducible, verifiable computation.
 
 ---
 
+## Which API Should I Use?
+
+**Decision table for choosing the right entrypoint:**
+
+| Your Goal | Use This | Import Path |
+|-----------|----------|-------------|
+| Deterministic random/noise in any environment | **`createRuntime()`** ✅ DEFAULT | `@nexart/codemode-sdk` |
+| AI agent integration | **`createRuntime()`** ✅ DEFAULT | `@nexart/codemode-sdk` |
+| Browser/React/Vite app | **`createRuntime()`** ✅ DEFAULT | `@nexart/codemode-sdk` |
+| Server-side image rendering | `executeCodeMode()` | `@nexart/codemode-sdk/node` |
+| Full p5.js-style canvas execution | `executeCodeMode()` | `@nexart/codemode-sdk/node` |
+
+**`createRuntime()`** is the **default and recommended** API:
+- ✅ Works in browser and Node.js
+- ✅ No canvas dependency
+- ✅ Agent-first design
+- ✅ Strict mode enforcement
+- ✅ Lightweight
+
+**`executeCodeMode()`** is the **legacy / Node-only** API:
+- Requires Node.js with `canvas` package
+- Full p5.js-style execution environment
+- Returns rendered PNG/MP4
+- Use only when you need actual image/video output
+
+---
+
 ## 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.
@@ -42,7 +69,16 @@ For most applications, seeded randomness is unnecessary complexity.
 
 ## For AI Coding Agents (Replit / Lovable / Claude Code)
 
-**Use `createRuntime({ seed, strict: true })` for deterministic execution.**
+**Always start with `createRuntime()` — it is the default and recommended API.**
+
+### Quick Rules for AI Agents
+
+1. **Always use `createRuntime()`** — NOT `executeCodeMode()`
+2. **Never use `Math.random()` or `Date.now()`** — use `runtime.random()` instead
+3. **Always use `strict: true`** — unless you explicitly know why you aren't
+4. **See `examples/agent-quickstart.ts`** — copy-paste ready reference
+
+### Minimal Example
 
 ```typescript
 import { createRuntime } from "@nexart/codemode-sdk";
@@ -50,23 +86,47 @@ import { createRuntime } from "@nexart/codemode-sdk";
 const runtime = createRuntime({
   seed: "my-artwork-42",
   vars: [50, 75, 25],
-  strict: true,  // Throws on Math.random, Date.now, etc.
+  strict: true,  // ALWAYS use strict: true — throws on non-deterministic APIs
   mode: "static"
 });
 
-// Deterministic APIs
+// Deterministic APIs (use these, not Math.random!)
 const value = runtime.random();          // [0, 1)
 const intVal = runtime.randomInt(0, 10); // integer in range
-const n = runtime.noise(x, y);           // Perlin noise
+const n = runtime.noise(0.5, 0.5);       // Perlin noise
+
+// Execute with strict enforcement
+const result = runtime.run(() => {
+  // Your deterministic code here
+  return runtime.random() * 100;
+});
 
 // Verification
-console.log(runtime.digest());   // Stable hash
-console.log(runtime.getState()); // Canonical state snapshot
+console.log(runtime.digest());   // Stable hash for verification
+console.log(runtime.getState()); // Canonical state snapshot for replay
+```
+
+### Strict Mode Explained
+
+Strict mode protects determinism by intercepting non-deterministic APIs during `runtime.run()`:
+
+```typescript
+runtime.run(() => {
+  Math.random();  // Throws: NEXART_STRICT: Non-deterministic API used: Math.random. Use runtime.random() instead.
+  Date.now();     // Throws: NEXART_STRICT: Non-deterministic API used: Date.now. Pass time as an input or use deterministic counters.
+});
 ```
 
-**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.`
+**Why strict mode exists:**
+- Determinism is the core guarantee — same inputs must always produce same outputs
+- AI agents often default to `Math.random()` before reading documentation
+- Strict mode catches these mistakes immediately with actionable error messages
+- Interception is **scoped to `runtime.run()`** — it does NOT globally mutate your application
+- Globals are restored after execution
+
+**When to use `strict: false`:**
+- Almost never. Only if you're intentionally mixing deterministic and non-deterministic code.
+- If you're not sure, use `strict: true`.
 
 ---
 
@@ -176,7 +236,7 @@ These are examples — the SDK is designed for any system requiring deterministi
 |----------|-------|
 | Protocol Version | v1.2.0 |
 | Status | **STABLE** |
-| SDK Version | 1.8.1 |
+| SDK Version | 1.8.2 |
 
 **Core protocol surface is frozen. Breaking changes require v2.0.0.**
 
@@ -377,6 +437,7 @@ The following are rejected with `[Code Mode Protocol Error]`:
 ## Examples
 
 ```bash
+npm run example:agent   # Agent quickstart (RECOMMENDED for AI agents)
 npm run example:basic   # Basic usage
 npm run example:verify  # Determinism verification
 ```

package/dist/sdk/codemode/core-index.d.ts

@@ -1,12 +1,13 @@
 /**
- * @nexart/codemode-sdk v1.4.0 — Core Exports
+ * @nexart/codemode-sdk — Core Exports
+ * See version.ts for SDK version (single source of truth)
  *
  * Canonical execution engine for NexArt Code Mode.
  * This is the single source of truth for Code Mode semantics.
  *
- * Protocol: v1.2.0 (Phase 3)
  * Enforcement: HARD
  */
+import { PROTOCOL_VERSION, PROTOCOL_PHASE } from './version';
 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';
@@ -14,8 +15,9 @@ export { runStaticMode, } from './static-engine';
 export { runLoopMode, cancelLoopMode, } from './loop-engine';
 export { createEngine, } from './engine';
 /**
- * SDK Identity
+ * SDK Identity — imported from version.ts (single source of truth)
  */
-export declare const SDK_VERSION = "1.1.1";
+export declare const SDK_VERSION = "1.8.2";
 export declare const SDK_NAME = "@nexart/codemode-sdk";
+export { PROTOCOL_VERSION, PROTOCOL_PHASE };
 //# sourceMappingURL=core-index.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"core-index.d.ts","sourceRoot":"","sources":["../../../core-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAA+B,gBAAgB,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAG1F,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,UAAe,CAAC;AACxC,eAAO,MAAM,QAAQ,yBAAyB,CAAC;AAC/C,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,CAAC"}

package/dist/sdk/codemode/core-index.js

@@ -1,12 +1,13 @@
 /**
- * @nexart/codemode-sdk v1.4.0 — Core Exports
+ * @nexart/codemode-sdk — Core Exports
+ * See version.ts for SDK version (single source of truth)
  *
  * Canonical execution engine for NexArt Code Mode.
  * This is the single source of truth for Code Mode semantics.
  *
- * Protocol: v1.2.0 (Phase 3)
  * Enforcement: HARD
  */
+import { SDK_VERSION as _SDK_VERSION, PROTOCOL_VERSION, PROTOCOL_PHASE } from './version';
 // Core execution
 export { executeCodeMode, validateCodeModeSource, } from './execute';
 // Protocol types
@@ -20,7 +21,8 @@ export { runLoopMode, cancelLoopMode, } from './loop-engine';
 // Engine utilities
 export { createEngine, } from './engine';
 /**
- * SDK Identity
+ * SDK Identity — imported from version.ts (single source of truth)
  */
-export const SDK_VERSION = '1.1.1';
+export const SDK_VERSION = _SDK_VERSION;
 export const SDK_NAME = '@nexart/codemode-sdk';
+export { PROTOCOL_VERSION, PROTOCOL_PHASE };

package/dist/{entry → sdk/codemode/entry}/browser.d.ts

@@ -1,8 +1,9 @@
 /**
  * @nexart/codemode-sdk/browser — Browser-Safe Entry Point
+ * See ../version.ts for SDK version (single source of truth)
  *
  * ╔══════════════════════════════════════════════════════════════════════════╗
- * ║  BROWSER-SAFE SDK ENTRY POINT (v1.8.0)                                   ║
+ * ║  BROWSER-SAFE SDK ENTRY POINT                                            ║
  * ║                                                                          ║
  * ║  This entrypoint exports ONLY browser-safe modules.                      ║
  * ║  It does NOT include static-engine or any Node.js dependencies.          ║
@@ -25,7 +26,9 @@ export { createEngine, } from '../engine';
 export { registerBuilderManifest, } from '../builder-manifest';
 export { createRuntime, NexArtRuntime, RUNTIME_VERSION, } from '../runtime';
 export type { RuntimeOptions, RuntimeState, NexArtRuntime as NexArtRuntimeType, } from '../runtime';
-export declare const SDK_VERSION = "1.8.0";
+export { renderSoundArtViaCodeMode, canRenderViaCodeMode, getCodeModeAvailableStyles, } from '../soundart-engine';
+export type { TweakParams, SoundArtEngineConfig, SoundArtRenderOptions, SoundArtRenderResult, SoundArtMetadata, SoundSnapshot, SoundFeatures, SoundArtSketchName, } from '../soundart-engine';
+export declare const SDK_VERSION = "1.8.2";
 export declare const SDK_NAME = "@nexart/codemode-sdk";
 export declare const SDK_ENTRY = "browser";
 /**

package/dist/sdk/codemode/entry/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../../../entry/browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAOH,YAAY,EACV,UAAU,EACV,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,MAAM,EACN,aAAa,EACb,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,EACpB,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,UAAU,CAAC;AAElB,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,cAAc,GACf,MAAM,UAAU,CAAC;AAKlB,OAAO,EACL,cAAc,EACd,mBAAmB,EACnB,cAAc,EACd,mBAAmB,EACnB,uBAAuB,EACvB,gBAAgB,GACjB,MAAM,sBAAsB,CAAC;AAK9B,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,uBAAuB,EACvB,iBAAiB,EACjB,SAAS,EACT,OAAO,EACP,OAAO,EACP,0BAA0B,EAC1B,wBAAwB,EACxB,qBAAqB,GACtB,MAAM,eAAe,CAAC;AAEvB,YAAY,EACV,SAAS,EACT,eAAe,GAChB,MAAM,eAAe,CAAC;AAKvB,OAAO,EACL,WAAW,EACX,cAAc,GACf,MAAM,gBAAgB,CAAC;AAKxB,OAAO,EACL,sBAAsB,GACvB,MAAM,YAAY,CAAC;AAKpB,OAAO,EACL,YAAY,GACb,MAAM,WAAW,CAAC;AAKnB,OAAO,EACL,uBAAuB,GACxB,MAAM,qBAAqB,CAAC;AAK7B,OAAO,EACL,aAAa,EACb,aAAa,EACb,eAAe,GAChB,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,cAAc,EACd,YAAY,EACZ,aAAa,IAAI,iBAAiB,GACnC,MAAM,YAAY,CAAC;AAKpB,OAAO,EACL,yBAAyB,EACzB,oBAAoB,EACpB,0BAA0B,GAC3B,MAAM,oBAAoB,CAAC;AAE5B,YAAY,EACV,WAAW,EACX,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,EACpB,gBAAgB,EAChB,aAAa,EACb,aAAa,EACb,kBAAkB,GACnB,MAAM,oBAAoB,CAAC;AAK5B,eAAO,MAAM,WAAW,UAAe,CAAC;AACxC,eAAO,MAAM,QAAQ,yBAAyB,CAAC;AAC/C,eAAO,MAAM,SAAS,YAAY,CAAC;AAEnC;;;;;;;;;;;GAWG"}

package/dist/{entry → sdk/codemode/entry}/browser.js

@@ -1,8 +1,9 @@
 /**
  * @nexart/codemode-sdk/browser — Browser-Safe Entry Point
+ * See ../version.ts for SDK version (single source of truth)
  *
  * ╔══════════════════════════════════════════════════════════════════════════╗
- * ║  BROWSER-SAFE SDK ENTRY POINT (v1.8.0)                                   ║
+ * ║  BROWSER-SAFE SDK ENTRY POINT                                            ║
  * ║                                                                          ║
  * ║  This entrypoint exports ONLY browser-safe modules.                      ║
  * ║  It does NOT include static-engine or any Node.js dependencies.          ║
@@ -14,6 +15,7 @@
  * ║  AI AGENTS: Start with createRuntime({ seed, strict: true })             ║
  * ╚══════════════════════════════════════════════════════════════════════════╝
  */
+import { SDK_VERSION as _SDK_VERSION } from '../version';
 export { PROTOCOL_IDENTITY, DEFAULT_VARS, DEFAULT_CONFIG, } from '../types';
 // ═══════════════════════════════════════════════════════════════════════════
 // EXECUTION SANDBOX — Browser-safe (no Node dependencies)
@@ -40,13 +42,17 @@ export { createEngine, } from '../engine';
 // ═══════════════════════════════════════════════════════════════════════════
 export { registerBuilderManifest, } from '../builder-manifest';
 // ═══════════════════════════════════════════════════════════════════════════
-// AGENT-FIRST RUNTIME — v1.8.0 (Browser-safe, no Node dependencies)
+// AGENT-FIRST RUNTIME — Browser-safe, no Node dependencies
 // ═══════════════════════════════════════════════════════════════════════════
 export { createRuntime, NexArtRuntime, RUNTIME_VERSION, } from '../runtime';
 // ═══════════════════════════════════════════════════════════════════════════
-// SDK IDENTITY
+// SOUNDART ENGINE — Browser-safe (canvas-based rendering)
 // ═══════════════════════════════════════════════════════════════════════════
-export const SDK_VERSION = '1.8.0';
+export { renderSoundArtViaCodeMode, canRenderViaCodeMode, getCodeModeAvailableStyles, } from '../soundart-engine';
+// ═══════════════════════════════════════════════════════════════════════════
+// SDK IDENTITY — imported from version.ts (single source of truth)
+// ═══════════════════════════════════════════════════════════════════════════
+export const SDK_VERSION = _SDK_VERSION;
 export const SDK_NAME = '@nexart/codemode-sdk';
 export const SDK_ENTRY = 'browser';
 /**

package/dist/{entry → sdk/codemode/entry}/node.d.ts

@@ -1,8 +1,9 @@
 /**
  * @nexart/codemode-sdk/node — Node.js Entry Point
+ * See ../version.ts for SDK version (single source of truth)
  *
  * ╔══════════════════════════════════════════════════════════════════════════╗
- * ║  NODE.JS SDK ENTRY POINT (v1.8.0)                                        ║
+ * ║  NODE.JS SDK ENTRY POINT                                                 ║
  * ║                                                                          ║
  * ║  This entrypoint exports Node.js-specific modules that require:          ║
  * ║  - canvas package (node-canvas)                                          ║

package/dist/sdk/codemode/entry/node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../../../entry/node.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAKH,cAAc,WAAW,CAAC;AAK1B,OAAO,EACL,aAAa,GACd,MAAM,kBAAkB,CAAC;AAK1B,OAAO,EACL,eAAe,GAChB,MAAM,YAAY,CAAC;AAKpB,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAClD,eAAO,MAAM,SAAS,SAAS,CAAC"}

package/dist/{entry → sdk/codemode/entry}/node.js

@@ -1,8 +1,9 @@
 /**
  * @nexart/codemode-sdk/node — Node.js Entry Point
+ * See ../version.ts for SDK version (single source of truth)
  *
  * ╔══════════════════════════════════════════════════════════════════════════╗
- * ║  NODE.JS SDK ENTRY POINT (v1.8.0)                                        ║
+ * ║  NODE.JS SDK ENTRY POINT                                                 ║
  * ║                                                                          ║
  * ║  This entrypoint exports Node.js-specific modules that require:          ║
  * ║  - canvas package (node-canvas)                                          ║

package/dist/{runtime.d.ts → sdk/codemode/runtime.d.ts}

@@ -1,6 +1,6 @@
 /**
  * NexArt Code Mode SDK - Agent-First Runtime Authority Layer
- * Version: 1.8.0 (Protocol v1.2.0)
+ * See version.ts for SDK version (single source of truth)
  *
  * ╔══════════════════════════════════════════════════════════════════════════╗
  * ║  AGENT-FIRST RUNTIME — DETERMINISTIC EXECUTION AUTHORITY                 ║
@@ -18,7 +18,7 @@
  * ║  BROWSER-SAFE: No Node.js dependencies. Works in Vite/Next/React.        ║
  * ╚══════════════════════════════════════════════════════════════════════════╝
  */
-export declare const RUNTIME_VERSION = "1.8.0";
+export declare const RUNTIME_VERSION = "1.8.2";
 export interface RuntimeOptions {
     seed: string | number;
     vars?: number[];

package/dist/sdk/codemode/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../../runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,eAAO,MAAM,eAAe,UAAc,CAAC;AAE3C,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,IAAI,EAAE,QAAQ,GAAG,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,IAAI,MAAM,CAAC;IACjB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5C,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IAC9C,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACjD,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;IACvB,MAAM,IAAI,MAAM,CAAC;IACjB,QAAQ,IAAI,YAAY,CAAC;IACzB,OAAO,IAAI,MAAM,CAAC;IAClB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAqGD,wBAAgB,aAAa,CAAC,OAAO,EAAE,cAAc,GAAG,aAAa,CAuHpE;AAED,eAAO,MAAM,aAAa;;;CAGzB,CAAC"}

package/dist/{runtime.js → sdk/codemode/runtime.js}

@@ -1,6 +1,6 @@
 /**
  * NexArt Code Mode SDK - Agent-First Runtime Authority Layer
- * Version: 1.8.0 (Protocol v1.2.0)
+ * See version.ts for SDK version (single source of truth)
  *
  * ╔══════════════════════════════════════════════════════════════════════════╗
  * ║  AGENT-FIRST RUNTIME — DETERMINISTIC EXECUTION AUTHORITY                 ║
@@ -18,7 +18,8 @@
  * ║  BROWSER-SAFE: No Node.js dependencies. Works in Vite/Next/React.        ║
  * ╚══════════════════════════════════════════════════════════════════════════╝
  */
-export const RUNTIME_VERSION = '1.8.0';
+import { SDK_VERSION } from './version';
+export const RUNTIME_VERSION = SDK_VERSION;
 function hashSeed(seed) {
     if (typeof seed === 'number') {
         return Math.floor(seed) >>> 0;

package/dist/sdk/codemode/static-engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"static-engine.d.ts","sourceRoot":"","sources":["../../../static-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAgB,MAAM,SAAS,CAAC;AAoCtE,wBAAsB,aAAa,CACjC,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,UAAU,GAClB,OAAO,CAAC,IAAI,CAAC,CA6Hf"}
+{"version":3,"file":"static-engine.d.ts","sourceRoot":"","sources":["../../../static-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAgB,MAAM,SAAS,CAAC;AAkDtE,wBAAsB,aAAa,CACjC,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,UAAU,GAClB,OAAO,CAAC,IAAI,CAAC,CA6Hf"}

package/dist/sdk/codemode/static-engine.js

@@ -15,17 +15,32 @@
  * When returnImageData is true, returns raw ImageData for determinism hashing.
  * Works in both browser (HTMLCanvasElement) and Node (canvas package) environments.
  */
-import { createRequire } from 'module';
 import { DEFAULT_CONFIG } from './types';
 import { createP5Runtime, injectTimeVariables, injectProtocolVariables } from './p5-runtime';
 import { FORBIDDEN_APIS, createSafeMath } from './execution-sandbox';
-const require = createRequire(import.meta.url);
+let nodeCanvasModule = null;
+async function getNodeCanvas() {
+    if (nodeCanvasModule)
+        return nodeCanvasModule;
+    if (typeof window === 'undefined') {
+        try {
+            const { createRequire } = await import('module');
+            const require = createRequire(import.meta.url);
+            nodeCanvasModule = require('canvas');
+            return nodeCanvasModule;
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
 /**
  * Create a runtime canvas that works in both browser and Node environments.
  * Browser: uses HTMLCanvasElement
  * Node/Headless: uses `canvas` npm package
  */
-function createRuntimeCanvas(width, height) {
+async function createRuntimeCanvas(width, height) {
     // Browser environment
     if (typeof document !== 'undefined' && typeof document.createElement === 'function') {
         const canvas = document.createElement('canvas');
@@ -34,14 +49,12 @@ function createRuntimeCanvas(width, height) {
         return canvas;
     }
     // Node / headless environment (oracle, CI)
-    try {
-        const { createCanvas } = require('canvas');
-        return createCanvas(width, height);
-    }
-    catch (err) {
-        throw new Error('[Code Mode Protocol Error] Headless canvas unavailable. ' +
-            'Install `canvas` for oracle execution.');
+    const nodeCanvas = await getNodeCanvas();
+    if (nodeCanvas && nodeCanvas.createCanvas) {
+        return nodeCanvas.createCanvas(width, height);
     }
+    throw new Error('[Code Mode Protocol Error] Headless canvas unavailable. ' +
+        'Install `canvas` for oracle execution.');
 }
 export async function runStaticMode(config, options) {
     const { code, seed, vars, onPreview, onProgress, onComplete, onError, returnImageData } = options;
@@ -54,7 +67,7 @@ export async function runStaticMode(config, options) {
             message: 'Initializing canvas...',
         });
         // Create runtime canvas (browser or Node)
-        const canvas = createRuntimeCanvas(width, height);
+        const canvas = await createRuntimeCanvas(width, height);
         // Create p5 runtime with optional seed for determinism
         const p = createP5Runtime(canvas, width, height, { seed });
         // Inject time variables (static = frame 0, t = 0, totalFrames = 1)

package/dist/sdk/codemode/version.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @nexart/codemode-sdk — Single Source of Truth for Version Constants
+ *
+ * All version exports across the SDK MUST import from this module.
+ * This prevents version drift between package.json, runtime exports, and documentation.
+ *
+ * To update: Change values here and run `npm run build`.
+ * See package.json for the canonical npm version.
+ */
+/** SDK version - must match package.json version */
+export declare const SDK_VERSION = "1.8.2";
+/** Protocol version - defines runtime semantics and determinism guarantees */
+export declare const PROTOCOL_VERSION = "1.2.0";
+/** Protocol phase - phase 3 = stable, production-ready */
+export declare const PROTOCOL_PHASE = 3;
+/** Combined version string for display */
+export declare const VERSION_STRING = "v1.8.2 (Protocol v1.2.0)";
+//# sourceMappingURL=version.d.ts.map

package/dist/sdk/codemode/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../../version.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,oDAAoD;AACpD,eAAO,MAAM,WAAW,UAAU,CAAC;AAEnC,8EAA8E;AAC9E,eAAO,MAAM,gBAAgB,UAAU,CAAC;AAExC,0DAA0D;AAC1D,eAAO,MAAM,cAAc,IAAI,CAAC;AAEhC,0CAA0C;AAC1C,eAAO,MAAM,cAAc,6BAAoD,CAAC"}

package/dist/sdk/codemode/version.js

@@ -0,0 +1,17 @@
+/**
+ * @nexart/codemode-sdk — Single Source of Truth for Version Constants
+ *
+ * All version exports across the SDK MUST import from this module.
+ * This prevents version drift between package.json, runtime exports, and documentation.
+ *
+ * To update: Change values here and run `npm run build`.
+ * See package.json for the canonical npm version.
+ */
+/** SDK version - must match package.json version */
+export const SDK_VERSION = '1.8.2';
+/** Protocol version - defines runtime semantics and determinism guarantees */
+export const PROTOCOL_VERSION = '1.2.0';
+/** Protocol phase - phase 3 = stable, production-ready */
+export const PROTOCOL_PHASE = 3;
+/** Combined version string for display */
+export const VERSION_STRING = `v${SDK_VERSION} (Protocol v${PROTOCOL_VERSION})`;