@nexart/codemode-sdk 1.7.0 → 1.8.0

package/CHANGELOG.md

@@ -4,6 +4,66 @@ All notable changes to @nexart/codemode-sdk will be documented in this file.
 
 ---
 
+## [1.8.0] — 2026-01-24
+
+### Added — Agent-First Runtime Authority Layer
+
+**Additive, Non-Breaking Release**
+
+This release introduces `createRuntime()` — an agent-first API designed for AI coding assistants (Replit, Lovable, Claude Code) to reliably execute deterministic code without rolling their own PRNG/noise implementations.
+
+#### New Runtime API (`createRuntime`)
+- **`createRuntime(options)`** — Create a deterministic runtime instance
+  - `seed: string | number` — Seed for deterministic randomness
+  - `vars?: number[]` — VAR array (0-100 inputs), defaults to zeros
+  - `strict?: boolean` — Enable strict mode (default: false)
+  - `mode?: 'static' | 'loop'` — Execution mode (default: 'static')
+  - `metadata?: Record<string, any>` — Optional user metadata for digest
+
+#### Runtime Methods
+- **`random(): number`** — Deterministic random [0, 1) using Mulberry32
+- **`randomInt(min, max): number`** — Deterministic integer in range
+- **`randomRange(min, max): number`** — Deterministic float in range
+- **`noise(x, y?, z?): number`** — Deterministic Perlin noise
+- **`run(fn): T`** — Execute code with optional strict enforcement
+- **`digest(): string`** — Stable hash for verification (FNV-1a)
+- **`getState(): RuntimeState`** — Canonical state snapshot for replay
+
+#### Strict Mode Enforcement
+When `strict: true`, the runtime intercepts non-deterministic APIs during `run()`:
+- `Math.random` → Throws with actionable error message
+- `Date.now` → Throws with actionable error message  
+- `performance.now` → Throws with actionable error message
+
+Error format: `NEXART_STRICT: Non-deterministic API used: {api}. {guidance}`
+
+#### Documentation Updates
+- Added "For AI Coding Agents" section at top of README
+- Added "Determinism Contract" with ✅/❌ checklist
+- Added "Why Not Just Use a PRNG?" comparison table
+- Added "Environment Imports" matrix
+- Simplified license section for clarity
+
+#### Examples
+- `examples/basic.ts` — Basic usage demonstration
+- `examples/verify.ts` — Determinism verification tests
+- `npm run example:basic` — Run basic example
+- `npm run example:verify` — Run verification tests
+
+#### Package Updates
+- Added keywords: deterministic, reproducible, verifiable, replay, canonical, simulation, procedural, seed, prng, ai-agent, strict-mode
+- Updated description for agent discoverability
+
+### Unchanged
+
+- No changes to protocol behavior or determinism
+- No changes to protocol version (remains v1.2.0)
+- No changes to existing APIs (executeCodeMode, createEngine, etc.)
+- Default import remains browser-safe
+- Full backward compatibility with v1.7.x
+
+---
+
 ## [1.7.0] — 2026-01-21
 
 ### Added — Browser-Safe Entrypoint + Conditional Exports

package/README.md

@@ -1,6 +1,6 @@
 # NexArt Code Mode Runtime SDK
 
-**Version: 1.7.0 (Protocol v1.2.0)**
+**Version: 1.8.0 (Protocol v1.2.0)**
 
 ╔══════════════════════════════════════════════════════════════════════════════╗
 ║  @nexart/codemode-sdk — Canonical Execution Surface                          ║
@@ -9,7 +9,7 @@
 ║                                                                              ║
 ║  Protocol: nexart                                                            ║
 ║  Engine: codemode                                                            ║
-║  SDK Version: 1.7.0                                                          ║
+║  SDK Version: 1.8.0                                                          ║
 ║  Protocol Version: 1.2.0                                                     ║
 ║  Phase: 3                                                                    ║
 ║  Enforcement: HARD                                                           ║
@@ -17,12 +17,90 @@
 
 ---
 
-## Commercial Licensing
+## For AI Coding Agents (Replit / Lovable / Claude Code)
 
-> **Commercial usage of NexArt Protocol requires a license.**
-> **Enforcement is not active yet.**
+**ALWAYS use `createRuntime({ seed, strict: true })` for deterministic execution.**
 
-The SDK is currently provided under the MIT License for all usage. A future version may introduce commercial licensing requirements. See [LICENSE.md](./LICENSE.md) for details.
+```typescript
+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.
+  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
+
+// Verify determinism
+console.log(runtime.digest());  // Stable hash for verification
+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.`
+
+---
+
+## Determinism Contract
+
+✅ **Guaranteed:**
+- Same `sdkVersion` + `seed` + `vars` → identical output
+- Cross-environment stable digest (browser, Node.js, CI)
+- Seeded PRNG via `runtime.random()` (Mulberry32)
+- Seeded noise via `runtime.noise()` (Perlin)
+
+❌ **Forbidden (blocked in strict mode):**
+- `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)
+
+---
+
+## Why Not Just Use a PRNG?
+
+| Feature | Plain PRNG | NexArt Runtime |
+|---------|-----------|----------------|
+| Seeded random | ✅ | ✅ |
+| Seeded noise | ❌ (separate lib) | ✅ built-in |
+| Strict mode (blocks entropy) | ❌ | ✅ |
+| Canonical state snapshot | ❌ | ✅ `getState()` |
+| Cross-env stable digest | ❌ | ✅ `digest()` |
+| VAR protocol (0-100 inputs) | ❌ | ✅ |
+| Replay/verification | Manual | Built-in |
+| Error messages for agents | ❌ | ✅ actionable |
+
+**The runtime provides a complete determinism layer, not just random numbers.**
+
+---
+
+## Environment Imports
+
+| Environment | Import Path |
+|-------------|-------------|
+| Browser / Vite / Next.js / React | `import { createRuntime } from "@nexart/codemode-sdk"` |
+| 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.
+
+---
+
+## License
+
+**Free for:**
+- Experiments and prototypes
+- Personal projects
+- Open-source projects
+
+**Commercial production deployments require a license.** See [LICENSING.md](./LICENSING.md) for details.
 
 ---
 
@@ -62,6 +140,54 @@ The answer is: "Whatever @nexart/codemode-sdk does — that is the protocol."
 
 ---
 
+## What's New in v1.8.0
+
+**Agent-First Runtime Authority Layer**
+
+This release introduces `createRuntime()` — an agent-first API designed for AI coding assistants to reliably execute deterministic code.
+
+### New Runtime API
+```typescript
+import { createRuntime } from "@nexart/codemode-sdk";
+
+const runtime = createRuntime({
+  seed: "my-seed",
+  vars: [50, 75],
+  strict: true,
+  mode: "static",
+  metadata: { artist: "demo" }
+});
+
+runtime.random();           // Deterministic PRNG
+runtime.randomInt(0, 100);  // Deterministic integer
+runtime.noise(x, y, z);     // Deterministic Perlin noise
+runtime.digest();           // Stable hash for verification
+runtime.getState();         // Canonical state snapshot
+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**

package/dist/core-index.d.ts

@@ -16,6 +16,6 @@ export { createEngine, } from './engine';
 /**
  * SDK Identity
  */
-export declare const SDK_VERSION = "1.7.0";
+export declare const SDK_VERSION = "1.8.0";
 export declare const SDK_NAME = "@nexart/codemode-sdk";
 //# sourceMappingURL=core-index.d.ts.map

package/dist/core-index.js

@@ -22,5 +22,5 @@ export { createEngine, } from './engine';
 /**
  * SDK Identity
  */
-export const SDK_VERSION = '1.7.0';
+export const SDK_VERSION = '1.8.0';
 export const SDK_NAME = '@nexart/codemode-sdk';

package/dist/entry/browser.d.ts

@@ -2,7 +2,7 @@
  * @nexart/codemode-sdk/browser — Browser-Safe Entry Point
  *
  * ╔══════════════════════════════════════════════════════════════════════════╗
- * ║  BROWSER-SAFE SDK ENTRY POINT (v1.7.0)                                   ║
+ * ║  BROWSER-SAFE SDK ENTRY POINT (v1.8.0)                                   ║
  * ║                                                                          ║
  * ║  This entrypoint exports ONLY browser-safe modules.                      ║
  * ║  It does NOT include static-engine or any Node.js dependencies.          ║
@@ -10,6 +10,8 @@
  * ║  Use this for Vite, React, Next.js, or any browser environment.          ║
  * ║                                                                          ║
  * ║  For Node.js/server: import from '@nexart/codemode-sdk/node'             ║
+ * ║                                                                          ║
+ * ║  AI AGENTS: Start with createRuntime({ seed, strict: true })             ║
  * ╚══════════════════════════════════════════════════════════════════════════╝
  */
 export type { RenderMode, RuntimeCanvas, EngineConfig, RenderResult, RunOptions, ProgressInfo, Engine, TimeVariables, ProtocolVariables, ProtocolMetadata, ExecuteCodeModeInput, ExecuteCodeModeResult, NexArtBuilderManifest, } from '../types';
@@ -21,7 +23,9 @@ export { runLoopMode, cancelLoopMode, } from '../loop-engine';
 export { validateCodeModeSource, } from '../execute';
 export { createEngine, } from '../engine';
 export { registerBuilderManifest, } from '../builder-manifest';
-export declare const SDK_VERSION = "1.7.0";
+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 declare const SDK_NAME = "@nexart/codemode-sdk";
 export declare const SDK_ENTRY = "browser";
 /**
@@ -33,5 +37,7 @@ export declare const SDK_ENTRY = "browser";
  * - Use runLoopMode() directly for animations
  * - For static rendering, use the server-side endpoint
  * - Or import from '@nexart/codemode-sdk/node' in SSR contexts
+ *
+ * AI AGENTS: Use createRuntime({ seed, strict: true }) for deterministic execution.
  */
 //# sourceMappingURL=browser.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../entry/browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,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,eAAO,MAAM,WAAW,UAAU,CAAC;AACnC,eAAO,MAAM,QAAQ,yBAAyB,CAAC;AAC/C,eAAO,MAAM,SAAS,YAAY,CAAC;AAEnC;;;;;;;;;GASG"}
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../entry/browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,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,eAAO,MAAM,WAAW,UAAU,CAAC;AACnC,eAAO,MAAM,QAAQ,yBAAyB,CAAC;AAC/C,eAAO,MAAM,SAAS,YAAY,CAAC;AAEnC;;;;;;;;;;;GAWG"}

package/dist/entry/browser.js

@@ -2,7 +2,7 @@
  * @nexart/codemode-sdk/browser — Browser-Safe Entry Point
  *
  * ╔══════════════════════════════════════════════════════════════════════════╗
- * ║  BROWSER-SAFE SDK ENTRY POINT (v1.7.0)                                   ║
+ * ║  BROWSER-SAFE SDK ENTRY POINT (v1.8.0)                                   ║
  * ║                                                                          ║
  * ║  This entrypoint exports ONLY browser-safe modules.                      ║
  * ║  It does NOT include static-engine or any Node.js dependencies.          ║
@@ -10,6 +10,8 @@
  * ║  Use this for Vite, React, Next.js, or any browser environment.          ║
  * ║                                                                          ║
  * ║  For Node.js/server: import from '@nexart/codemode-sdk/node'             ║
+ * ║                                                                          ║
+ * ║  AI AGENTS: Start with createRuntime({ seed, strict: true })             ║
  * ╚══════════════════════════════════════════════════════════════════════════╝
  */
 export { PROTOCOL_IDENTITY, DEFAULT_VARS, DEFAULT_CONFIG, } from '../types';
@@ -38,9 +40,13 @@ export { createEngine, } from '../engine';
 // ═══════════════════════════════════════════════════════════════════════════
 export { registerBuilderManifest, } from '../builder-manifest';
 // ═══════════════════════════════════════════════════════════════════════════
+// AGENT-FIRST RUNTIME — v1.8.0 (Browser-safe, no Node dependencies)
+// ═══════════════════════════════════════════════════════════════════════════
+export { createRuntime, NexArtRuntime, RUNTIME_VERSION, } from '../runtime';
+// ═══════════════════════════════════════════════════════════════════════════
 // SDK IDENTITY
 // ═══════════════════════════════════════════════════════════════════════════
-export const SDK_VERSION = '1.7.0';
+export const SDK_VERSION = '1.8.0';
 export const SDK_NAME = '@nexart/codemode-sdk';
 export const SDK_ENTRY = 'browser';
 /**
@@ -52,4 +58,6 @@ export const SDK_ENTRY = 'browser';
  * - Use runLoopMode() directly for animations
  * - For static rendering, use the server-side endpoint
  * - Or import from '@nexart/codemode-sdk/node' in SSR contexts
+ *
+ * AI AGENTS: Use createRuntime({ seed, strict: true }) for deterministic execution.
  */

package/dist/entry/node.d.ts

@@ -2,7 +2,7 @@
  * @nexart/codemode-sdk/node — Node.js Entry Point
  *
  * ╔══════════════════════════════════════════════════════════════════════════╗
- * ║  NODE.JS SDK ENTRY POINT (v1.7.0)                                        ║
+ * ║  NODE.JS SDK ENTRY POINT (v1.8.0)                                        ║
  * ║                                                                          ║
  * ║  This entrypoint exports Node.js-specific modules that require:          ║
  * ║  - canvas package (node-canvas)                                          ║
@@ -11,6 +11,8 @@
  * ║  Use this for server-side rendering, oracles, or CLI tools.              ║
  * ║                                                                          ║
  * ║  For browser/Vite: import from '@nexart/codemode-sdk/browser'            ║
+ * ║                                                                          ║
+ * ║  AI AGENTS: Start with createRuntime({ seed, strict: true })             ║
  * ╚══════════════════════════════════════════════════════════════════════════╝
  */
 export * from './browser';

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

@@ -1 +1 @@
-{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../entry/node.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;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"}
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../entry/node.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;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/node.js

@@ -2,7 +2,7 @@
  * @nexart/codemode-sdk/node — Node.js Entry Point
  *
  * ╔══════════════════════════════════════════════════════════════════════════╗
- * ║  NODE.JS SDK ENTRY POINT (v1.7.0)                                        ║
+ * ║  NODE.JS SDK ENTRY POINT (v1.8.0)                                        ║
  * ║                                                                          ║
  * ║  This entrypoint exports Node.js-specific modules that require:          ║
  * ║  - canvas package (node-canvas)                                          ║
@@ -11,6 +11,8 @@
  * ║  Use this for server-side rendering, oracles, or CLI tools.              ║
  * ║                                                                          ║
  * ║  For browser/Vite: import from '@nexart/codemode-sdk/browser'            ║
+ * ║                                                                          ║
+ * ║  AI AGENTS: Start with createRuntime({ seed, strict: true })             ║
  * ╚══════════════════════════════════════════════════════════════════════════╝
  */
 // ═══════════════════════════════════════════════════════════════════════════

package/dist/runtime.d.ts

@@ -0,0 +1,52 @@
+/**
+ * NexArt Code Mode SDK - Agent-First Runtime Authority Layer
+ * Version: 1.8.0 (Protocol v1.2.0)
+ *
+ * ╔══════════════════════════════════════════════════════════════════════════╗
+ * ║  AGENT-FIRST RUNTIME — DETERMINISTIC EXECUTION AUTHORITY                 ║
+ * ║                                                                          ║
+ * ║  This module provides a high-level runtime API designed for AI agents    ║
+ * ║  (Replit, Lovable, Claude Code) to reliably execute deterministic code.  ║
+ * ║                                                                          ║
+ * ║  Key Features:                                                           ║
+ * ║  - Deterministic PRNG: runtime.random() (seeded Mulberry32)              ║
+ * ║  - Deterministic noise: runtime.noise(x, y?, z?) (seeded Perlin)         ║
+ * ║  - Strict mode: Throws on Math.random, Date.now, performance.now         ║
+ * ║  - Digest: Stable hash for verification and replay                       ║
+ * ║  - State snapshot: Canonical state for bundles                           ║
+ * ║                                                                          ║
+ * ║  BROWSER-SAFE: No Node.js dependencies. Works in Vite/Next/React.        ║
+ * ╚══════════════════════════════════════════════════════════════════════════╝
+ */
+export declare const RUNTIME_VERSION = "1.8.0";
+export interface RuntimeOptions {
+    seed: string | number;
+    vars?: number[];
+    strict?: boolean;
+    mode?: 'static' | 'loop';
+    metadata?: Record<string, unknown>;
+}
+export interface RuntimeState {
+    sdkVersion: string;
+    seed: number;
+    vars: number[];
+    mode: 'static' | 'loop';
+    metadata?: Record<string, unknown>;
+}
+export interface NexArtRuntime {
+    random(): number;
+    randomInt(min: number, max: number): number;
+    randomRange(min: number, max: number): number;
+    noise(x: number, y?: number, z?: number): number;
+    run<T>(fn: () => T): T;
+    digest(): string;
+    getState(): RuntimeState;
+    getSeed(): number;
+    readonly strict: boolean;
+}
+export declare function createRuntime(options: RuntimeOptions): NexArtRuntime;
+export declare const NexArtRuntime: {
+    create: typeof createRuntime;
+    VERSION: string;
+};
+//# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,eAAO,MAAM,eAAe,UAAU,CAAC;AAEvC,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

@@ -0,0 +1,219 @@
+/**
+ * NexArt Code Mode SDK - Agent-First Runtime Authority Layer
+ * Version: 1.8.0 (Protocol v1.2.0)
+ *
+ * ╔══════════════════════════════════════════════════════════════════════════╗
+ * ║  AGENT-FIRST RUNTIME — DETERMINISTIC EXECUTION AUTHORITY                 ║
+ * ║                                                                          ║
+ * ║  This module provides a high-level runtime API designed for AI agents    ║
+ * ║  (Replit, Lovable, Claude Code) to reliably execute deterministic code.  ║
+ * ║                                                                          ║
+ * ║  Key Features:                                                           ║
+ * ║  - Deterministic PRNG: runtime.random() (seeded Mulberry32)              ║
+ * ║  - Deterministic noise: runtime.noise(x, y?, z?) (seeded Perlin)         ║
+ * ║  - Strict mode: Throws on Math.random, Date.now, performance.now         ║
+ * ║  - Digest: Stable hash for verification and replay                       ║
+ * ║  - State snapshot: Canonical state for bundles                           ║
+ * ║                                                                          ║
+ * ║  BROWSER-SAFE: No Node.js dependencies. Works in Vite/Next/React.        ║
+ * ╚══════════════════════════════════════════════════════════════════════════╝
+ */
+export const RUNTIME_VERSION = '1.8.0';
+function hashSeed(seed) {
+    if (typeof seed === 'number') {
+        return Math.floor(seed) >>> 0;
+    }
+    let hash = 0;
+    for (let i = 0; i < seed.length; i++) {
+        const char = seed.charCodeAt(i);
+        hash = ((hash << 5) - hash) + char;
+        hash = hash >>> 0;
+    }
+    return hash || 1;
+}
+function createSeededRNG(seed) {
+    let a = seed >>> 0;
+    return () => {
+        a += 0x6D2B79F5;
+        let t = Math.imul(a ^ (a >>> 15), a | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+function createSeededNoise(seed) {
+    const permutation = [];
+    const rng = createSeededRNG(seed);
+    for (let i = 0; i < 256; i++) {
+        permutation[i] = i;
+    }
+    for (let i = 255; i > 0; i--) {
+        const j = Math.floor(rng() * (i + 1));
+        [permutation[i], permutation[j]] = [permutation[j], permutation[i]];
+    }
+    for (let i = 0; i < 256; i++) {
+        permutation[256 + i] = permutation[i];
+    }
+    const fade = (t) => t * t * t * (t * (t * 6 - 15) + 10);
+    const lerp = (a, b, t) => a + t * (b - a);
+    const grad = (hash, x, y, z) => {
+        const h = hash & 15;
+        const u = h < 8 ? x : y;
+        const v = h < 4 ? y : h === 12 || h === 14 ? x : z;
+        return ((h & 1) === 0 ? u : -u) + ((h & 2) === 0 ? v : -v);
+    };
+    return (x, y = 0, z = 0) => {
+        const X = Math.floor(x) & 255;
+        const Y = Math.floor(y) & 255;
+        const Z = Math.floor(z) & 255;
+        x -= Math.floor(x);
+        y -= Math.floor(y);
+        z -= Math.floor(z);
+        const u = fade(x);
+        const v = fade(y);
+        const w = fade(z);
+        const A = permutation[X] + Y;
+        const AA = permutation[A] + Z;
+        const AB = permutation[A + 1] + Z;
+        const B = permutation[X + 1] + Y;
+        const BA = permutation[B] + Z;
+        const BB = permutation[B + 1] + Z;
+        return (lerp(lerp(lerp(grad(permutation[AA], x, y, z), grad(permutation[BA], x - 1, y, z), u), lerp(grad(permutation[AB], x, y - 1, z), grad(permutation[BB], x - 1, y - 1, z), u), v), lerp(lerp(grad(permutation[AA + 1], x, y, z - 1), grad(permutation[BA + 1], x - 1, y, z - 1), u), lerp(grad(permutation[AB + 1], x, y - 1, z - 1), grad(permutation[BB + 1], x - 1, y - 1, z - 1), u), v), w) + 1) / 2;
+    };
+}
+function stableStringify(obj) {
+    if (obj === null)
+        return 'null';
+    if (obj === undefined)
+        return 'undefined';
+    if (typeof obj !== 'object')
+        return JSON.stringify(obj);
+    if (Array.isArray(obj)) {
+        return '[' + obj.map(stableStringify).join(',') + ']';
+    }
+    const keys = Object.keys(obj).sort();
+    const pairs = keys.map(k => `${JSON.stringify(k)}:${stableStringify(obj[k])}`);
+    return '{' + pairs.join(',') + '}';
+}
+function fnv1aHash(str) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < str.length; i++) {
+        hash ^= str.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    const h1 = (hash >>> 0).toString(16).padStart(8, '0');
+    let hash2 = 0x811c9dc5;
+    for (let i = str.length - 1; i >= 0; i--) {
+        hash2 ^= str.charCodeAt(i);
+        hash2 = Math.imul(hash2, 0x01000193);
+    }
+    const h2 = (hash2 >>> 0).toString(16).padStart(8, '0');
+    return h1 + h2;
+}
+export function createRuntime(options) {
+    const numericSeed = hashSeed(options.seed);
+    const vars = options.vars ?? [];
+    const mode = options.mode ?? 'static';
+    const strict = options.strict ?? false;
+    const metadata = options.metadata;
+    if (vars.length > 10) {
+        throw new Error(`[NexArt Runtime] vars array must have 0-10 elements, got ${vars.length}`);
+    }
+    for (let i = 0; i < vars.length; i++) {
+        if (typeof vars[i] !== 'number' || !Number.isFinite(vars[i])) {
+            throw new Error(`[NexArt Runtime] vars[${i}] must be a finite number`);
+        }
+        if (vars[i] < 0 || vars[i] > 100) {
+            throw new Error(`[NexArt Runtime] vars[${i}] must be in range 0-100, got ${vars[i]}`);
+        }
+    }
+    const paddedVars = [...vars];
+    while (paddedVars.length < 10) {
+        paddedVars.push(0);
+    }
+    const rng = createSeededRNG(numericSeed);
+    const noiseFunc = createSeededNoise(numericSeed);
+    const state = {
+        sdkVersion: RUNTIME_VERSION,
+        seed: numericSeed,
+        vars: paddedVars,
+        mode,
+        ...(metadata !== undefined && { metadata }),
+    };
+    function random() {
+        return rng();
+    }
+    function randomInt(min, max) {
+        const range = max - min + 1;
+        return Math.floor(rng() * range) + min;
+    }
+    function randomRange(min, max) {
+        return rng() * (max - min) + min;
+    }
+    function noise(x, y, z) {
+        return noiseFunc(x, y ?? 0, z ?? 0);
+    }
+    function run(fn) {
+        if (!strict) {
+            return fn();
+        }
+        const originalMathRandom = Math.random;
+        const originalDateNow = Date.now;
+        const hasPerformance = typeof performance !== 'undefined' && performance !== null;
+        const originalPerformanceNow = hasPerformance ? performance.now : undefined;
+        const throwMathRandom = () => {
+            throw new Error('NEXART_STRICT: Non-deterministic API used: Math.random. Use runtime.random() instead.');
+        };
+        const throwDateNow = () => {
+            throw new Error('NEXART_STRICT: Non-deterministic API used: Date.now. Pass time as an input or use deterministic counters.');
+        };
+        const throwPerformanceNow = () => {
+            throw new Error('NEXART_STRICT: Non-deterministic API used: performance.now.');
+        };
+        try {
+            Math.random = throwMathRandom;
+            Date.now = throwDateNow;
+            if (hasPerformance && originalPerformanceNow) {
+                performance.now = throwPerformanceNow;
+            }
+            return fn();
+        }
+        finally {
+            Math.random = originalMathRandom;
+            Date.now = originalDateNow;
+            if (hasPerformance && originalPerformanceNow) {
+                performance.now = originalPerformanceNow;
+            }
+        }
+    }
+    function digest() {
+        const input = stableStringify({
+            sdkVersion: RUNTIME_VERSION,
+            seed: numericSeed,
+            vars: paddedVars,
+            mode,
+            ...(metadata !== undefined && { metadata }),
+        });
+        return fnv1aHash(input);
+    }
+    function getState() {
+        return { ...state, vars: [...state.vars] };
+    }
+    function getSeed() {
+        return numericSeed;
+    }
+    return Object.freeze({
+        random,
+        randomInt,
+        randomRange,
+        noise,
+        run,
+        digest,
+        getState,
+        getSeed,
+        strict,
+    });
+}
+export const NexArtRuntime = {
+    create: createRuntime,
+    VERSION: RUNTIME_VERSION,
+};

package/examples/basic.ts

@@ -0,0 +1,61 @@
+/**
+ * @nexart/codemode-sdk — Basic Example
+ * 
+ * Demonstrates the agent-first runtime API for deterministic execution.
+ * 
+ * Run: npm run example:basic
+ */
+
+import { createRuntime } from '../runtime';
+
+console.log('╔══════════════════════════════════════════════════════════════╗');
+console.log('║  NexArt Code Mode SDK — Basic Example                        ║');
+console.log('╚══════════════════════════════════════════════════════════════╝');
+console.log();
+
+const runtime = createRuntime({
+  seed: 'demo-seed-42',
+  vars: [50, 75, 25],
+  strict: true,
+  mode: 'static',
+  metadata: { artist: 'demo', project: 'example' }
+});
+
+console.log('Runtime State:');
+console.log(JSON.stringify(runtime.getState(), null, 2));
+console.log();
+
+console.log('Digest:', runtime.digest());
+console.log('Seed (numeric):', runtime.getSeed());
+console.log('Strict mode:', runtime.strict);
+console.log();
+
+console.log('Deterministic random values:');
+const randoms: number[] = [];
+for (let i = 0; i < 5; i++) {
+  const val = runtime.random();
+  randoms.push(val);
+  console.log(`  random() #${i + 1}: ${val.toFixed(8)}`);
+}
+console.log();
+
+console.log('Deterministic noise values:');
+for (let i = 0; i < 5; i++) {
+  const x = i * 0.5;
+  const val = runtime.noise(x, 0.5);
+  console.log(`  noise(${x}, 0.5): ${val.toFixed(8)}`);
+}
+console.log();
+
+console.log('Running code in strict mode...');
+const result = runtime.run(() => {
+  let sum = 0;
+  for (let i = 0; i < 10; i++) {
+    sum += runtime.random();
+  }
+  return sum;
+});
+console.log(`  Sum of 10 random values: ${result.toFixed(8)}`);
+console.log();
+
+console.log('✅ Basic example completed successfully!');

package/examples/preflight-test.ts

@@ -0,0 +1,275 @@
+/**
+ * @nexart/codemode-sdk — Preflight Release Tests
+ * 
+ * Extended verification tests for v1.8.0 release validation.
+ * Tests strict mode restoration, error messages, and cross-env digest parity.
+ * 
+ * Run: npx tsx examples/preflight-test.ts
+ */
+
+import { createRuntime, RUNTIME_VERSION } from '../runtime';
+
+console.log('╔══════════════════════════════════════════════════════════════╗');
+console.log('║  NexArt Code Mode SDK — Preflight Release Tests              ║');
+console.log(`║  Version: ${RUNTIME_VERSION.padEnd(52)}║`);
+console.log('╚══════════════════════════════════════════════════════════════╝');
+console.log();
+
+let passCount = 0;
+let failCount = 0;
+
+function test(name: string, fn: () => boolean): void {
+  try {
+    const result = fn();
+    if (result) {
+      console.log(`✅ PASS: ${name}`);
+      passCount++;
+    } else {
+      console.log(`❌ FAIL: ${name}`);
+      failCount++;
+    }
+  } catch (error: any) {
+    console.log(`❌ FAIL: ${name} — ${error.message}`);
+    failCount++;
+  }
+}
+
+console.log('TEST GROUP 1: Strict Mode Restoration on Throw');
+console.log('─'.repeat(60));
+
+test('Strict mode restores Math.random after user code throws', () => {
+  const runtime = createRuntime({ seed: 12345, strict: true });
+  const originalMathRandom = Math.random;
+  
+  try {
+    runtime.run(() => {
+      throw new Error('User code explosion');
+    });
+  } catch {
+    // Expected
+  }
+  
+  const restored = Math.random === originalMathRandom;
+  if (!restored) {
+    console.log('   ⚠️  Math.random was NOT restored after throw');
+  }
+  return restored;
+});
+
+test('Strict mode restores Date.now after user code throws', () => {
+  const runtime = createRuntime({ seed: 12345, strict: true });
+  const originalDateNow = Date.now;
+  
+  try {
+    runtime.run(() => {
+      throw new Error('User code explosion');
+    });
+  } catch {
+    // Expected
+  }
+  
+  const restored = Date.now === originalDateNow;
+  if (!restored) {
+    console.log('   ⚠️  Date.now was NOT restored after throw');
+  }
+  return restored;
+});
+
+test('Strict mode restores performance.now after user code throws', () => {
+  const runtime = createRuntime({ seed: 12345, strict: true });
+  const hasPerformance = typeof performance !== 'undefined' && performance !== null;
+  
+  if (!hasPerformance) {
+    console.log('   ℹ️  performance object not available, skipping');
+    return true;
+  }
+  
+  const originalPerformanceNow = performance.now;
+  
+  try {
+    runtime.run(() => {
+      throw new Error('User code explosion');
+    });
+  } catch {
+    // Expected
+  }
+  
+  const restored = performance.now === originalPerformanceNow;
+  if (!restored) {
+    console.log('   ⚠️  performance.now was NOT restored after throw');
+  }
+  return restored;
+});
+
+console.log();
+console.log('TEST GROUP 2: Strict Mode Error Messages');
+console.log('─'.repeat(60));
+
+test('Math.random error message is actionable', () => {
+  const runtime = createRuntime({ seed: 12345, strict: true });
+  
+  try {
+    runtime.run(() => Math.random());
+    return false;
+  } catch (error: any) {
+    const expected = 'NEXART_STRICT: Non-deterministic API used: Math.random. Use runtime.random() instead.';
+    const match = error.message === expected;
+    if (!match) {
+      console.log(`   Expected: "${expected}"`);
+      console.log(`   Got:      "${error.message}"`);
+    }
+    return match;
+  }
+});
+
+test('Date.now error message is actionable', () => {
+  const runtime = createRuntime({ seed: 12345, strict: true });
+  
+  try {
+    runtime.run(() => Date.now());
+    return false;
+  } catch (error: any) {
+    const expected = 'NEXART_STRICT: Non-deterministic API used: Date.now. Pass time as an input or use deterministic counters.';
+    const match = error.message === expected;
+    if (!match) {
+      console.log(`   Expected: "${expected}"`);
+      console.log(`   Got:      "${error.message}"`);
+    }
+    return match;
+  }
+});
+
+test('performance.now error message is actionable', () => {
+  const runtime = createRuntime({ seed: 12345, strict: true });
+  const hasPerformance = typeof performance !== 'undefined' && performance !== null;
+  
+  if (!hasPerformance) {
+    console.log('   ℹ️  performance object not available, skipping');
+    return true;
+  }
+  
+  try {
+    runtime.run(() => performance.now());
+    return false;
+  } catch (error: any) {
+    const expected = 'NEXART_STRICT: Non-deterministic API used: performance.now.';
+    const match = error.message === expected;
+    if (!match) {
+      console.log(`   Expected: "${expected}"`);
+      console.log(`   Got:      "${error.message}"`);
+    }
+    return match;
+  }
+});
+
+console.log();
+console.log('TEST GROUP 3: Digest Determinism');
+console.log('─'.repeat(60));
+
+test('Digest is stable across multiple calls', () => {
+  const config = { seed: 'stable-digest-test', vars: [10, 20, 30], mode: 'static' as const };
+  const runtime1 = createRuntime(config);
+  const runtime2 = createRuntime(config);
+  
+  const digest1 = runtime1.digest();
+  const digest2 = runtime2.digest();
+  
+  if (digest1 !== digest2) {
+    console.log(`   Digest 1: ${digest1}`);
+    console.log(`   Digest 2: ${digest2}`);
+  }
+  return digest1 === digest2;
+});
+
+test('Digest changes when seed changes', () => {
+  const runtime1 = createRuntime({ seed: 'seed-a', vars: [10, 20, 30] });
+  const runtime2 = createRuntime({ seed: 'seed-b', vars: [10, 20, 30] });
+  
+  return runtime1.digest() !== runtime2.digest();
+});
+
+test('Digest changes when vars change', () => {
+  const runtime1 = createRuntime({ seed: 'same-seed', vars: [10, 20, 30] });
+  const runtime2 = createRuntime({ seed: 'same-seed', vars: [10, 20, 31] });
+  
+  return runtime1.digest() !== runtime2.digest();
+});
+
+test('Digest changes when mode changes', () => {
+  const runtime1 = createRuntime({ seed: 'same-seed', vars: [10, 20, 30], mode: 'static' });
+  const runtime2 = createRuntime({ seed: 'same-seed', vars: [10, 20, 30], mode: 'loop' });
+  
+  return runtime1.digest() !== runtime2.digest();
+});
+
+test('Digest is 16-char hex string', () => {
+  const runtime = createRuntime({ seed: 'format-test' });
+  const digest = runtime.digest();
+  const isValidFormat = /^[0-9a-f]{16}$/.test(digest);
+  if (!isValidFormat) {
+    console.log(`   Digest format invalid: "${digest}"`);
+  }
+  return isValidFormat;
+});
+
+console.log();
+console.log('TEST GROUP 4: PRNG Determinism');
+console.log('─'.repeat(60));
+
+test('Same seed produces identical random sequence', () => {
+  const seq1: number[] = [];
+  const seq2: number[] = [];
+  
+  const runtime1 = createRuntime({ seed: 'prng-test' });
+  const runtime2 = createRuntime({ seed: 'prng-test' });
+  
+  for (let i = 0; i < 10; i++) {
+    seq1.push(runtime1.random());
+    seq2.push(runtime2.random());
+  }
+  
+  return seq1.every((v, i) => v === seq2[i]);
+});
+
+test('Different seeds produce different sequences', () => {
+  const runtime1 = createRuntime({ seed: 'seed-x' });
+  const runtime2 = createRuntime({ seed: 'seed-y' });
+  
+  return runtime1.random() !== runtime2.random();
+});
+
+test('Noise is deterministic for same inputs', () => {
+  const runtime1 = createRuntime({ seed: 'noise-test' });
+  const runtime2 = createRuntime({ seed: 'noise-test' });
+  
+  const n1 = runtime1.noise(1.5, 2.5, 3.5);
+  const n2 = runtime2.noise(1.5, 2.5, 3.5);
+  
+  return n1 === n2;
+});
+
+console.log();
+console.log('TEST GROUP 5: Known Digest Values');
+console.log('─'.repeat(60));
+
+const knownConfig = { seed: 'known-digest-oracle', vars: [50, 50, 50, 50, 50, 50, 50, 50, 50, 50], mode: 'static' as const };
+const knownRuntime = createRuntime(knownConfig);
+const oracleDigest = knownRuntime.digest();
+console.log(`Oracle digest for cross-env verification: ${oracleDigest}`);
+
+test('Oracle digest format valid', () => {
+  return /^[0-9a-f]{16}$/.test(oracleDigest);
+});
+
+console.log();
+console.log('═'.repeat(60));
+console.log(`RESULTS: ${passCount} passed, ${failCount} failed`);
+console.log('═'.repeat(60));
+
+if (failCount > 0) {
+  console.log('❌ PREFLIGHT FAILED - DO NOT SHIP');
+  process.exit(1);
+} else {
+  console.log('✅ PREFLIGHT PASSED - READY TO SHIP');
+  process.exit(0);
+}

package/examples/verify.ts

@@ -0,0 +1,151 @@
+/**
+ * @nexart/codemode-sdk — Verification Example
+ * 
+ * Demonstrates determinism verification and strict mode error handling.
+ * 
+ * Run: npm run example:verify
+ */
+
+import { createRuntime } from '../runtime';
+
+console.log('╔══════════════════════════════════════════════════════════════╗');
+console.log('║  NexArt Code Mode SDK — Verification Example                 ║');
+console.log('╚══════════════════════════════════════════════════════════════╝');
+console.log();
+
+function generateRandomSequence(seed: string | number, vars: number[], count: number): number[] {
+  const runtime = createRuntime({ seed, vars, strict: true });
+  const values: number[] = [];
+  for (let i = 0; i < count; i++) {
+    values.push(runtime.random());
+  }
+  return values;
+}
+
+console.log('TEST 1: Same seed + vars = same output');
+console.log('─'.repeat(50));
+
+const seq1 = generateRandomSequence('test-seed', [50, 25], 5);
+const seq2 = generateRandomSequence('test-seed', [50, 25], 5);
+
+console.log('Run 1:', seq1.map(v => v.toFixed(6)).join(', '));
+console.log('Run 2:', seq2.map(v => v.toFixed(6)).join(', '));
+
+const identical = seq1.every((v, i) => v === seq2[i]);
+console.log(`Result: ${identical ? '✅ PASS' : '❌ FAIL'} — sequences are ${identical ? 'identical' : 'different'}`);
+console.log();
+
+console.log('TEST 2: Same seed + vars = same digest');
+console.log('─'.repeat(50));
+
+const runtime1 = createRuntime({ seed: 'digest-test', vars: [10, 20, 30] });
+const runtime2 = createRuntime({ seed: 'digest-test', vars: [10, 20, 30] });
+
+const digest1 = runtime1.digest();
+const digest2 = runtime2.digest();
+
+console.log('Digest 1:', digest1);
+console.log('Digest 2:', digest2);
+
+const digestsMatch = digest1 === digest2;
+console.log(`Result: ${digestsMatch ? '✅ PASS' : '❌ FAIL'} — digests are ${digestsMatch ? 'identical' : 'different'}`);
+console.log();
+
+console.log('TEST 3: Different vars = different digest');
+console.log('─'.repeat(50));
+
+const runtime3 = createRuntime({ seed: 'digest-test', vars: [10, 20, 30] });
+const runtime4 = createRuntime({ seed: 'digest-test', vars: [10, 20, 31] });
+
+const digest3 = runtime3.digest();
+const digest4 = runtime4.digest();
+
+console.log('Digest (vars [10,20,30]):', digest3);
+console.log('Digest (vars [10,20,31]):', digest4);
+
+const digestsDiffer = digest3 !== digest4;
+console.log(`Result: ${digestsDiffer ? '✅ PASS' : '❌ FAIL'} — digests are ${digestsDiffer ? 'different' : 'identical'}`);
+console.log();
+
+console.log('TEST 4: Strict mode blocks Math.random');
+console.log('─'.repeat(50));
+
+const strictRuntime = createRuntime({ seed: 12345, strict: true });
+
+let strictErrorCaught = false;
+let errorMessage = '';
+
+try {
+  strictRuntime.run(() => {
+    return Math.random();
+  });
+} catch (error: any) {
+  strictErrorCaught = true;
+  errorMessage = error.message;
+}
+
+console.log('Called Math.random() in strict run...');
+console.log(`Error caught: ${strictErrorCaught}`);
+if (strictErrorCaught) {
+  console.log(`Error message: "${errorMessage}"`);
+}
+
+const expectedMessage = 'NEXART_STRICT: Non-deterministic API used: Math.random. Use runtime.random() instead.';
+const correctError = errorMessage === expectedMessage;
+console.log(`Result: ${strictErrorCaught && correctError ? '✅ PASS' : '❌ FAIL'} — strict mode ${strictErrorCaught ? 'blocked' : 'did not block'} Math.random`);
+console.log();
+
+console.log('TEST 5: Strict mode blocks Date.now');
+console.log('─'.repeat(50));
+
+let dateErrorCaught = false;
+let dateErrorMessage = '';
+
+try {
+  strictRuntime.run(() => {
+    return Date.now();
+  });
+} catch (error: any) {
+  dateErrorCaught = true;
+  dateErrorMessage = error.message;
+}
+
+console.log('Called Date.now() in strict run...');
+console.log(`Error caught: ${dateErrorCaught}`);
+if (dateErrorCaught) {
+  console.log(`Error message: "${dateErrorMessage}"`);
+}
+
+const expectedDateMessage = 'NEXART_STRICT: Non-deterministic API used: Date.now. Pass time as an input or use deterministic counters.';
+const correctDateError = dateErrorMessage === expectedDateMessage;
+console.log(`Result: ${dateErrorCaught && correctDateError ? '✅ PASS' : '❌ FAIL'} — strict mode ${dateErrorCaught ? 'blocked' : 'did not block'} Date.now`);
+console.log();
+
+console.log('TEST 6: Non-strict mode allows Math.random');
+console.log('─'.repeat(50));
+
+const nonStrictRuntime = createRuntime({ seed: 12345, strict: false });
+
+let nonStrictResult: number | null = null;
+let nonStrictError = false;
+
+try {
+  nonStrictResult = nonStrictRuntime.run(() => {
+    return Math.random();
+  });
+} catch {
+  nonStrictError = true;
+}
+
+console.log('Called Math.random() in non-strict run...');
+console.log(`Error thrown: ${nonStrictError}`);
+console.log(`Result value: ${nonStrictResult}`);
+console.log(`Result: ${!nonStrictError && nonStrictResult !== null ? '✅ PASS' : '❌ FAIL'} — non-strict mode ${!nonStrictError ? 'allowed' : 'blocked'} Math.random`);
+console.log();
+
+const allPassed = identical && digestsMatch && digestsDiffer && strictErrorCaught && correctError && dateErrorCaught && correctDateError && !nonStrictError;
+console.log('═'.repeat(50));
+console.log(allPassed ? '✅ All verification tests passed!' : '❌ Some tests failed');
+console.log('═'.repeat(50));
+
+process.exit(allPassed ? 0 : 1);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nexart/codemode-sdk",
-  "version": "1.7.0",
-  "description": "NexArt Code Mode SDK - Canonical execution engine for deterministic generative art",
+  "version": "1.8.0",
+  "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",
   "types": "./dist/entry/browser.d.ts",
@@ -35,15 +35,19 @@
   },
   "files": [
     "dist",
+    "examples",
     "README.md",
     "CHANGELOG.md",
     "CODE_MODE_PROTOCOL.md",
     "LICENSE.md",
+    "LICENSING.md",
     "builder.manifest.schema.json"
   ],
   "scripts": {
     "build": "tsc",
     "test": "npx tsx smoke-test.ts",
+    "example:basic": "npx tsx examples/basic.ts",
+    "example:verify": "npx tsx examples/verify.ts",
     "prepublishOnly": "npm run build && npm run test"
   },
   "keywords": [
@@ -52,9 +56,21 @@
     "nft",
     "p5js",
     "deterministic",
+    "reproducible",
+    "verifiable",
+    "replay",
+    "canonical",
+    "simulation",
+    "procedural",
+    "generative",
+    "seed",
+    "prng",
+    "noise",
     "codemode",
     "browser",
-    "node"
+    "node",
+    "ai-agent",
+    "strict-mode"
   ],
   "author": "NexArt",
   "license": "MIT",