@nexart/codemode-sdk 1.6.0 → 1.8.0

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,27 +1,53 @@
 {
   "name": "@nexart/codemode-sdk",
-  "version": "1.6.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/core-index.js",
-  "types": "./dist/core-index.d.ts",
+  "main": "./dist/entry/browser.js",
+  "types": "./dist/entry/browser.d.ts",
   "exports": {
     ".": {
+      "browser": {
+        "types": "./dist/entry/browser.d.ts",
+        "import": "./dist/entry/browser.js"
+      },
+      "node": {
+        "types": "./dist/entry/node.d.ts",
+        "import": "./dist/entry/node.js"
+      },
+      "default": {
+        "types": "./dist/entry/browser.d.ts",
+        "import": "./dist/entry/browser.js"
+      }
+    },
+    "./browser": {
+      "types": "./dist/entry/browser.d.ts",
+      "import": "./dist/entry/browser.js"
+    },
+    "./node": {
+      "types": "./dist/entry/node.d.ts",
+      "import": "./dist/entry/node.js"
+    },
+    "./core": {
       "types": "./dist/core-index.d.ts",
       "import": "./dist/core-index.js"
     }
   },
   "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": [
@@ -30,7 +56,21 @@
     "nft",
     "p5js",
     "deterministic",
-    "codemode"
+    "reproducible",
+    "verifiable",
+    "replay",
+    "canonical",
+    "simulation",
+    "procedural",
+    "generative",
+    "seed",
+    "prng",
+    "noise",
+    "codemode",
+    "browser",
+    "node",
+    "ai-agent",
+    "strict-mode"
   ],
   "author": "NexArt",
   "license": "MIT",