@nexart/codemode-sdk 1.7.0 → 1.8.1

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!');