@nexart/codemode-sdk 1.4.0 → 1.5.0

package/README.md

@@ -1,6 +1,6 @@
 # NexArt Code Mode Runtime SDK
 
-**Version: 1.4.0 (Protocol v1.2.0)**
+**Version: 1.5.0 (Protocol v1.2.0)**
 
 ╔══════════════════════════════════════════════════════════════════════════════╗
 ║  @nexart/codemode-sdk — Canonical Code Mode Authority                        ║
@@ -10,7 +10,7 @@
 ║                                                                              ║
 ║  Protocol: nexart                                                            ║
 ║  Engine: codemode                                                            ║
-║  SDK Version: 1.4.0                                                          ║
+║  SDK Version: 1.5.0                                                          ║
 ║  Protocol Version: 1.2.0                                                     ║
 ║  Phase: 3                                                                    ║
 ║  Enforcement: HARD                                                           ║
@@ -54,7 +54,17 @@ The answer is: "Whatever @nexart/codemode-sdk does — that is the protocol."
 
 ---
 
-## What's New in v1.4.0 (Protocol v1.2.0)
+## What's New in v1.5.0
+
+**Critical Fix — NPM Package Sync**
+
+- **Restored seeded Mulberry32 PRNG** for `random()`, `randomSeed()`, `randomGaussian()`
+- **Restored seeded Perlin noise** for `noise()`, `noiseSeed()`
+- Full sync between SDK source and npm package
+
+The v1.4.0 npm package had an outdated runtime that used `Math.random()` directly. This release restores determinism.
+
+## v1.4.0 (Protocol v1.2.0)
 
 **Phase 3 — Pixel & Graphics**
 

package/dist/engine.d.ts

@@ -1,24 +1,46 @@
 /**
- * NexArt Code Mode Runtime SDK
- * Version: 1.4.0 (Protocol v1.2.0)
+ * NexArt Code Mode Runtime SDK - Canonical Execution Entry Point
  *
- * Main entry point for the Code Mode runtime engine.
- *
- * Usage:
- *   const engine = createEngine({ mode: 'static' });
- *   engine.run({
- *     code: 'function setup() { background(255); ellipse(width/2, height/2, 100); }',
- *     onComplete: (result) => console.log(result.blob)
- *   });
+ * ╔══════════════════════════════════════════════════════════════════════════╗
+ * ║  CODE MODE PROTOCOL v1.2.0 (Phase 3) — CANONICAL ENTRY POINT             ║
+ * ║                                                                          ║
+ * ║  This is the ONLY official way to execute Code Mode.                     ║
+ * ║  All implementations (NexArt, ByX, external) MUST use this function.     ║
+ * ║                                                                          ║
+ * ║  Authority: @nexart/codemode-sdk                                         ║
+ * ╚══════════════════════════════════════════════════════════════════════════╝
  */
-import type { Engine, EngineConfig } from './types';
+import { ExecuteCodeModeInput, ExecuteCodeModeResult } from './types';
 /**
- * Create a NexArt Code Mode rendering engine.
+ * executeCodeMode — Canonical Code Mode Execution Entry Point
+ *
+ * This is the ONLY official way to execute Code Mode.
+ * All implementations MUST use this function.
+ *
+ * @param input - Execution parameters
+ * @returns Promise<ExecuteCodeModeResult> - Execution result with protocol metadata
  *
- * @param config - Engine configuration
- * @returns Engine instance
+ * @example
+ * ```typescript
+ * const result = await executeCodeMode({
+ *   source: `function setup() { background(255); ellipse(width/2, height/2, 100); }`,
+ *   width: 1950,
+ *   height: 2400,
+ *   seed: 12345,
+ *   vars: [50, 75, 0, 0, 0, 0, 0, 0, 0, 0],
+ *   mode: 'static'
+ * });
+ *
+ * console.log(result.metadata.protocolVersion); // '1.2.0'
+ * console.log(result.image); // PNG Blob
+ * ```
+ */
+export declare function executeCodeMode(input: ExecuteCodeModeInput): Promise<ExecuteCodeModeResult>;
+/**
+ * Validate code without executing
  */
-export declare function createEngine(config: EngineConfig): Engine;
-export type { Engine, EngineConfig, RunOptions, RenderResult, ProgressInfo } from './types';
-export { DEFAULT_CONFIG } from './types';
+export declare function validateCodeModeSource(source: string, mode: 'static' | 'loop'): {
+    valid: boolean;
+    errors: string[];
+};
 //# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,YAAY,EAAc,MAAM,SAAS,CAAC;AAKhE;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CA+CzD;AAGD,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC5F,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EAKtB,MAAM,SAAS,CAAC;AA4MjB;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,oBAAoB,GAC1B,OAAO,CAAC,qBAAqB,CAAC,CAqBhC;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAuCpH"}

package/dist/engine.js

@@ -1,67 +1,268 @@
 /**
- * NexArt Code Mode Runtime SDK
- * Version: 1.4.0 (Protocol v1.2.0)
+ * NexArt Code Mode Runtime SDK - Canonical Execution Entry Point
  *
- * Main entry point for the Code Mode runtime engine.
- *
- * Usage:
- *   const engine = createEngine({ mode: 'static' });
- *   engine.run({
- *     code: 'function setup() { background(255); ellipse(width/2, height/2, 100); }',
- *     onComplete: (result) => console.log(result.blob)
- *   });
+ * ╔══════════════════════════════════════════════════════════════════════════╗
+ * ║  CODE MODE PROTOCOL v1.2.0 (Phase 3) — CANONICAL ENTRY POINT             ║
+ * ║                                                                          ║
+ * ║  This is the ONLY official way to execute Code Mode.                     ║
+ * ║  All implementations (NexArt, ByX, external) MUST use this function.     ║
+ * ║                                                                          ║
+ * ║  Authority: @nexart/codemode-sdk                                         ║
+ * ╚══════════════════════════════════════════════════════════════════════════╝
  */
-import { DEFAULT_CONFIG } from './types';
 import { runStaticMode } from './static-engine';
-import { runLoopMode, cancelLoopMode } from './loop-engine';
+import { runLoopMode } from './loop-engine';
+import { PROTOCOL_IDENTITY, DEFAULT_CONFIG, } from './types';
 /**
- * Create a NexArt Code Mode rendering engine.
+ * Validate and normalize VAR array to 10 elements.
  *
- * @param config - Engine configuration
- * @returns Engine instance
+ * Rules (SDK v1.0.2, Protocol v1.0.0):
+ * - VAR is OPTIONAL: omit or pass [] for empty (defaults to all zeros)
+ * - VAR input length MUST be 0-10 elements (protocol error if > 10)
+ * - VAR values MUST be finite numbers (protocol error if not)
+ * - VAR values MUST be in range 0-100 (protocol error if out of range, NO clamping)
+ * - VAR is read-only inside sketches
+ * - Output is ALWAYS 10 elements (padded with zeros) for protocol consistency
  */
-export function createEngine(config) {
-    const resolvedConfig = {
-        mode: config.mode,
-        width: config.width ?? DEFAULT_CONFIG.width,
-        height: config.height ?? DEFAULT_CONFIG.height,
-        duration: config.duration ?? DEFAULT_CONFIG.duration,
-        fps: config.fps ?? DEFAULT_CONFIG.fps,
-    };
-    let isRunning = false;
-    const run = async (options) => {
-        if (isRunning) {
-            throw new Error('Engine is already running. Call stop() first.');
+function normalizeVars(vars) {
+    if (!vars || !Array.isArray(vars)) {
+        console.log('[CodeMode] No vars provided, using defaults [0,0,0,0,0,0,0,0,0,0]');
+        return [0, 0, 0, 0, 0, 0, 0, 0, 0, 0];
+    }
+    if (vars.length > 10) {
+        throw new Error(`[Code Mode Protocol Error] VAR array must have at most 10 elements, got ${vars.length}`);
+    }
+    const result = [];
+    for (let i = 0; i < vars.length; i++) {
+        const v = vars[i];
+        if (typeof v !== 'number' || !Number.isFinite(v)) {
+            throw new Error(`[Code Mode Protocol Error] VAR[${i}] must be a finite number, got ${typeof v === 'number' ? v : typeof v}`);
         }
-        isRunning = true;
-        try {
-            if (resolvedConfig.mode === 'static') {
-                await runStaticMode(resolvedConfig, options);
-            }
-            else if (resolvedConfig.mode === 'loop') {
-                await runLoopMode(resolvedConfig, options);
-            }
-            else {
-                throw new Error(`Unknown mode: ${resolvedConfig.mode}`);
-            }
+        if (v < 0 || v > 100) {
+            throw new Error(`[Code Mode Protocol Error] VAR[${i}] = ${v} is out of range. Values must be 0-100.`);
+        }
+        result.push(v);
+    }
+    // Pad with zeros to always have 10 elements for protocol consistency
+    while (result.length < 10) {
+        result.push(0);
+    }
+    return result;
+}
+/**
+ * Validate execution input
+ */
+function validateInput(input) {
+    if (!input.source || typeof input.source !== 'string') {
+        throw new Error('[Code Mode Protocol Error] source is required and must be a string');
+    }
+    if (typeof input.width !== 'number' || input.width <= 0) {
+        throw new Error('[Code Mode Protocol Error] width must be a positive number');
+    }
+    if (typeof input.height !== 'number' || input.height <= 0) {
+        throw new Error('[Code Mode Protocol Error] height must be a positive number');
+    }
+    if (typeof input.seed !== 'number') {
+        throw new Error('[Code Mode Protocol Error] seed is required and must be a number');
+    }
+    if (input.mode !== 'static' && input.mode !== 'loop') {
+        throw new Error('[Code Mode Protocol Error] mode must be "static" or "loop"');
+    }
+    if (input.mode === 'loop') {
+        if (typeof input.totalFrames !== 'number' || input.totalFrames <= 0) {
+            throw new Error('[Code Mode Protocol Error] totalFrames is required for loop mode and must be a positive number');
         }
-        finally {
-            isRunning = false;
+    }
+    // Validate forbidden patterns per CODE_MODE_PROTOCOL.md
+    const forbiddenPatterns = [
+        // Async timing (breaks determinism)
+        { pattern: /setTimeout\s*\(/, name: 'setTimeout' },
+        { pattern: /setInterval\s*\(/, name: 'setInterval' },
+        { pattern: /requestAnimationFrame\s*\(/, name: 'requestAnimationFrame' },
+        // Time-based entropy (breaks determinism)
+        { pattern: /Date\.now\s*\(/, name: 'Date.now() — use time variable instead' },
+        { pattern: /new\s+Date\s*\(/, name: 'new Date() — use time variable instead' },
+        // Unseeded random (use random() instead)
+        { pattern: /Math\.random\s*\(/, name: 'Math.random() — use random() instead (seeded)' },
+        // External IO (breaks determinism)
+        { pattern: /fetch\s*\(/, name: 'fetch() — external IO forbidden' },
+        { pattern: /XMLHttpRequest/, name: 'XMLHttpRequest — external IO forbidden' },
+        // Canvas is pre-initialized
+        { pattern: /createCanvas\s*\(/, name: 'createCanvas() — canvas is pre-initialized' },
+        // DOM manipulation forbidden
+        { pattern: /document\./, name: 'DOM access — document.* forbidden' },
+        { pattern: /window\./, name: 'DOM access — window.* forbidden' },
+        // External imports forbidden
+        { pattern: /\bimport\s+/, name: 'import — external imports forbidden' },
+        { pattern: /\brequire\s*\(/, name: 'require() — external imports forbidden' },
+    ];
+    for (const { pattern, name } of forbiddenPatterns) {
+        if (pattern.test(input.source)) {
+            throw new Error(`[Code Mode Protocol Error] Forbidden pattern: ${name}`);
         }
-    };
-    const stop = () => {
-        if (resolvedConfig.mode === 'loop') {
-            cancelLoopMode();
+    }
+    // Loop mode specific validation
+    if (input.mode === 'loop') {
+        if (!/function\s+draw\s*\(\s*\)/.test(input.source)) {
+            throw new Error('[Code Mode Protocol Error] Loop mode requires a draw() function');
         }
-        isRunning = false;
-    };
-    const getConfig = () => {
-        return { ...resolvedConfig };
+        if (/noLoop\s*\(\s*\)/.test(input.source)) {
+            throw new Error('[Code Mode Protocol Error] noLoop() is forbidden in Loop mode');
+        }
+    }
+}
+/**
+ * Create protocol metadata for the execution result
+ */
+function createMetadata(input, vars) {
+    return {
+        ...PROTOCOL_IDENTITY,
+        seed: input.seed,
+        vars,
+        width: input.width,
+        height: input.height,
+        mode: input.mode,
+        ...(input.mode === 'loop' && input.totalFrames ? { totalFrames: input.totalFrames } : {}),
     };
+}
+/**
+ * Execute Code Mode in Static mode - delegates to static-engine.ts
+ */
+async function executeStatic(input, vars) {
+    console.log('[CodeMode] Rendered via @nexart/codemode-sdk (Protocol v1.2.0)');
+    console.log('[CodeMode] Execution: Static mode — delegating to static-engine');
+    return new Promise((resolve, reject) => {
+        runStaticMode({
+            mode: 'static',
+            width: input.width,
+            height: input.height,
+        }, {
+            code: input.source,
+            seed: input.seed,
+            vars: vars,
+            onComplete: (result) => {
+                resolve({
+                    image: result.blob,
+                    metadata: createMetadata(input, vars),
+                });
+            },
+            onError: (error) => {
+                reject(error);
+            },
+        });
+    });
+}
+/**
+ * Execute Code Mode in Loop mode - delegates to loop-engine.ts
+ */
+async function executeLoop(input, vars) {
+    console.log('[CodeMode] Rendered via @nexart/codemode-sdk (Protocol v1.2.0)');
+    console.log(`[CodeMode] Execution: Loop mode — delegating to loop-engine (${input.totalFrames} frames)`);
+    const fps = DEFAULT_CONFIG.fps;
+    const duration = (input.totalFrames || 60) / fps;
+    return new Promise((resolve, reject) => {
+        runLoopMode({
+            mode: 'loop',
+            width: input.width,
+            height: input.height,
+            duration: duration,
+            fps: fps,
+        }, {
+            code: input.source,
+            seed: input.seed,
+            vars: vars,
+            onComplete: (result) => {
+                resolve({
+                    video: result.blob,
+                    metadata: createMetadata(input, vars),
+                });
+            },
+            onError: (error) => {
+                reject(error);
+            },
+        });
+    });
+}
+/**
+ * executeCodeMode — Canonical Code Mode Execution Entry Point
+ *
+ * This is the ONLY official way to execute Code Mode.
+ * All implementations MUST use this function.
+ *
+ * @param input - Execution parameters
+ * @returns Promise<ExecuteCodeModeResult> - Execution result with protocol metadata
+ *
+ * @example
+ * ```typescript
+ * const result = await executeCodeMode({
+ *   source: `function setup() { background(255); ellipse(width/2, height/2, 100); }`,
+ *   width: 1950,
+ *   height: 2400,
+ *   seed: 12345,
+ *   vars: [50, 75, 0, 0, 0, 0, 0, 0, 0, 0],
+ *   mode: 'static'
+ * });
+ *
+ * console.log(result.metadata.protocolVersion); // '1.2.0'
+ * console.log(result.image); // PNG Blob
+ * ```
+ */
+export async function executeCodeMode(input) {
+    // Validate input
+    validateInput(input);
+    // Normalize VAR values
+    const vars = normalizeVars(input.vars);
+    // Log protocol execution
+    console.log('[CodeMode] ════════════════════════════════════════════════');
+    console.log('[CodeMode] Protocol v1.2.0 — Phase 3 — HARD Enforcement');
+    console.log(`[CodeMode] Mode: ${input.mode}`);
+    console.log(`[CodeMode] Seed: ${input.seed}`);
+    console.log(`[CodeMode] VAR: [${vars.join(', ')}]`);
+    console.log('[CodeMode] ════════════════════════════════════════════════');
+    // Execute based on mode
+    if (input.mode === 'static') {
+        return executeStatic(input, vars);
+    }
+    else {
+        return executeLoop(input, vars);
+    }
+}
+/**
+ * Validate code without executing
+ */
+export function validateCodeModeSource(source, mode) {
+    const errors = [];
+    // Same forbidden patterns as validateInput per CODE_MODE_PROTOCOL.md
+    const forbiddenPatterns = [
+        { pattern: /setTimeout\s*\(/, name: 'setTimeout' },
+        { pattern: /setInterval\s*\(/, name: 'setInterval' },
+        { pattern: /requestAnimationFrame\s*\(/, name: 'requestAnimationFrame' },
+        { pattern: /Date\.now\s*\(/, name: 'Date.now() — use time variable instead' },
+        { pattern: /new\s+Date\s*\(/, name: 'new Date() — use time variable instead' },
+        { pattern: /Math\.random\s*\(/, name: 'Math.random() — use random() instead (seeded)' },
+        { pattern: /fetch\s*\(/, name: 'fetch() — external IO forbidden' },
+        { pattern: /XMLHttpRequest/, name: 'XMLHttpRequest — external IO forbidden' },
+        { pattern: /createCanvas\s*\(/, name: 'createCanvas() — canvas is pre-initialized' },
+        { pattern: /document\./, name: 'DOM access — document.* forbidden' },
+        { pattern: /window\./, name: 'DOM access — window.* forbidden' },
+        { pattern: /\bimport\s+/, name: 'import — external imports forbidden' },
+        { pattern: /\brequire\s*\(/, name: 'require() — external imports forbidden' },
+    ];
+    for (const { pattern, name } of forbiddenPatterns) {
+        if (pattern.test(source)) {
+            errors.push(`Forbidden pattern: ${name}`);
+        }
+    }
+    if (mode === 'loop') {
+        if (!/function\s+draw\s*\(\s*\)/.test(source)) {
+            errors.push('Loop mode requires a draw() function');
+        }
+        if (/noLoop\s*\(\s*\)/.test(source)) {
+            errors.push('noLoop() is forbidden in Loop mode');
+        }
+    }
     return {
-        run,
-        stop,
-        getConfig,
+        valid: errors.length === 0,
+        errors,
     };
 }
-export { DEFAULT_CONFIG } from './types';

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 /**
  * NexArt Code Mode Runtime SDK
- * Version: 1.4.0 (Protocol v1.2.0)
+ * Version: 1.5.0 (Protocol v1.2.0)
  *
  * ╔══════════════════════════════════════════════════════════════════════════╗
  * ║  @nexart/codemode-sdk — Canonical Code Mode Authority                    ║
@@ -10,7 +10,7 @@
  * ║                                                                          ║
  * ║  Protocol: nexart                                                        ║
  * ║  Engine: codemode                                                        ║
- * ║  SDK Version: 1.4.0                                                      ║
+ * ║  SDK Version: 1.5.0                                                      ║
  * ║  Protocol Version: 1.2.0                                                 ║
  * ║  Phase: 3                                                                ║
  * ║  Enforcement: HARD                                                       ║
@@ -18,25 +18,26 @@
  *
  * @example
  * ```typescript
- * import { createEngine } from '@nexart/codemode-sdk';
+ * import { executeCodeMode } from '@nexart/codemode-sdk';
  *
- * const engine = createEngine({ mode: 'static' });
- *
- * engine.run({
- *   code: `
+ * const result = await executeCodeMode({
+ *   source: `
  *     function setup() {
  *       background(255);
  *       fill(0);
  *       ellipse(width/2, height/2, 100);
  *     }
  *   `,
- *   onComplete: (result) => {
- *     console.log('Rendered:', result.type, result.blob.size, 'bytes');
- *   }
+ *   mode: 'static',
+ *   width: 1950,
+ *   height: 2400,
+ *   seed: 12345,
+ *   vars: [50, 50, 50, 50, 50, 50, 50, 50, 50, 50]
  * });
+ * console.log('Rendered:', result.blob.size, 'bytes');
  * ```
  */
-export { createEngine } from './engine';
-export type { Engine, EngineConfig, RunOptions, RenderResult, ProgressInfo, RenderMode, TimeVariables, } from './types';
+export { executeCodeMode, validateCodeModeSource } from './engine';
+export type { ExecuteCodeModeInput, ExecuteCodeModeResult, ProtocolMetadata, RenderResult, TimeVariables, } from './types';
 export { DEFAULT_CONFIG, PROTOCOL_IDENTITY } from './types';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,YAAY,EACV,MAAM,EACN,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,aAAa,GACd,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,EAAE,eAAe,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AACnE,YAAY,EACV,oBAAoB,EACpB,qBAAqB,EACrB,gBAAgB,EAChB,YAAY,EACZ,aAAa,GACd,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -1,6 +1,6 @@
 /**
  * NexArt Code Mode Runtime SDK
- * Version: 1.4.0 (Protocol v1.2.0)
+ * Version: 1.5.0 (Protocol v1.2.0)
  *
  * ╔══════════════════════════════════════════════════════════════════════════╗
  * ║  @nexart/codemode-sdk — Canonical Code Mode Authority                    ║
@@ -10,7 +10,7 @@
  * ║                                                                          ║
  * ║  Protocol: nexart                                                        ║
  * ║  Engine: codemode                                                        ║
- * ║  SDK Version: 1.4.0                                                      ║
+ * ║  SDK Version: 1.5.0                                                      ║
  * ║  Protocol Version: 1.2.0                                                 ║
  * ║  Phase: 3                                                                ║
  * ║  Enforcement: HARD                                                       ║
@@ -18,23 +18,24 @@
  *
  * @example
  * ```typescript
- * import { createEngine } from '@nexart/codemode-sdk';
+ * import { executeCodeMode } from '@nexart/codemode-sdk';
  *
- * const engine = createEngine({ mode: 'static' });
- *
- * engine.run({
- *   code: `
+ * const result = await executeCodeMode({
+ *   source: `
  *     function setup() {
  *       background(255);
  *       fill(0);
  *       ellipse(width/2, height/2, 100);
  *     }
  *   `,
- *   onComplete: (result) => {
- *     console.log('Rendered:', result.type, result.blob.size, 'bytes');
- *   }
+ *   mode: 'static',
+ *   width: 1950,
+ *   height: 2400,
+ *   seed: 12345,
+ *   vars: [50, 50, 50, 50, 50, 50, 50, 50, 50, 50]
  * });
+ * console.log('Rendered:', result.blob.size, 'bytes');
  * ```
  */
-export { createEngine } from './engine';
+export { executeCodeMode, validateCodeModeSource } from './engine';
 export { DEFAULT_CONFIG, PROTOCOL_IDENTITY } from './types';

package/dist/loop-engine.d.ts

@@ -1,13 +1,17 @@
 /**
  * NexArt Code Mode Runtime SDK - Loop Engine
- * Version: 1.4.0 (Protocol v1.2.0)
+ * Protocol: v1.2.0 (Phase 3) — HARD ENFORCEMENT
  *
  * Loop mode renderer: frame-authoritative, stateless execution.
  * - Executes setup() once
  * - Executes draw() once per frame
  * - Clears canvas before each frame (transparent)
+ * - Resets blend mode to NORMAL before each frame
  * - Injects normalized time variables
  * - No canvas persistence between frames
+ *
+ * Determinism Guarantee:
+ * Same code + same seed + same VARs = identical frame sequence
  */
 import type { EngineConfig, RunOptions } from './types';
 export declare function cancelLoopMode(): void;

package/dist/loop-engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loop-engine.d.ts","sourceRoot":"","sources":["../loop-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAA+B,MAAM,SAAS,CAAC;AAMrF,wBAAgB,cAAc,IAAI,IAAI,CAErC;AAED,wBAAsB,WAAW,CAC/B,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,UAAU,GAClB,OAAO,CAAC,IAAI,CAAC,CA4Lf"}
+{"version":3,"file":"loop-engine.d.ts","sourceRoot":"","sources":["../loop-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAA+B,MAAM,SAAS,CAAC;AAMrF,wBAAgB,cAAc,IAAI,IAAI,CAErC;AAED,wBAAsB,WAAW,CAC/B,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,UAAU,GAClB,OAAO,CAAC,IAAI,CAAC,CAuMf"}

package/dist/loop-engine.js

@@ -1,22 +1,26 @@
 /**
  * NexArt Code Mode Runtime SDK - Loop Engine
- * Version: 1.4.0 (Protocol v1.2.0)
+ * Protocol: v1.2.0 (Phase 3) — HARD ENFORCEMENT
  *
  * Loop mode renderer: frame-authoritative, stateless execution.
  * - Executes setup() once
  * - Executes draw() once per frame
  * - Clears canvas before each frame (transparent)
+ * - Resets blend mode to NORMAL before each frame
  * - Injects normalized time variables
  * - No canvas persistence between frames
+ *
+ * Determinism Guarantee:
+ * Same code + same seed + same VARs = identical frame sequence
  */
 import { DEFAULT_CONFIG } from './types';
-import { createP5Runtime } from './p5-runtime';
+import { createP5Runtime, injectProtocolVariables } from './p5-runtime';
 let isCancelled = false;
 export function cancelLoopMode() {
     isCancelled = true;
 }
 export async function runLoopMode(config, options) {
-    const { code, onPreview, onProgress, onComplete, onError } = options;
+    const { code, seed, vars, onPreview, onProgress, onComplete, onError } = options;
     const width = config.width ?? DEFAULT_CONFIG.width;
     const height = config.height ?? DEFAULT_CONFIG.height;
     const duration = Math.max(DEFAULT_CONFIG.minDuration, Math.min(DEFAULT_CONFIG.maxDuration, config.duration ?? DEFAULT_CONFIG.duration));
@@ -33,8 +37,10 @@ export async function runLoopMode(config, options) {
         const canvas = document.createElement('canvas');
         canvas.width = width;
         canvas.height = height;
-        // Create p5 runtime
-        const p = createP5Runtime(canvas, width, height);
+        // Create p5 runtime with optional seed for determinism
+        const p = createP5Runtime(canvas, width, height, { seed });
+        // Inject protocol variables (VAR[0..9])
+        injectProtocolVariables(p, vars);
         // Validate code
         const hasDrawFunction = /function\s+draw\s*\(\s*\)/.test(code);
         if (!hasDrawFunction) {
@@ -64,16 +70,18 @@ export async function runLoopMode(config, options) {
         if (!drawCode) {
             throw new Error('Loop Mode requires a draw() function with content.');
         }
-        // Create wrapped functions with p5 context and time variables
-        const wrappedSetup = new Function('p', 'frameCount', 't', 'time', 'tGlobal', `with(p) { ${setupCode} }`);
-        const wrappedDraw = new Function('p', 'frameCount', 't', 'time', 'tGlobal', `with(p) { ${drawCode} }`);
+        // Inject totalFrames into runtime
+        p.totalFrames = totalFrames;
+        // Create wrapped functions with p5 context, time variables, VAR, and totalFrames
+        const wrappedSetup = new Function('p', 'frameCount', 't', 'time', 'tGlobal', 'VAR', 'totalFrames', `with(p) { ${setupCode} }`);
+        const wrappedDraw = new Function('p', 'frameCount', 't', 'time', 'tGlobal', 'VAR', 'totalFrames', `with(p) { ${drawCode} }`);
         onProgress?.({
             phase: 'setup',
             percent: 10,
             message: 'Executing setup()...',
         });
-        // Execute setup() once with time = 0
-        wrappedSetup(p, 0, 0, 0, 0);
+        // Execute setup() once with time = 0, VAR, and totalFrames
+        wrappedSetup(p, 0, 0, 0, 0, p.VAR, totalFrames);
         // Capture frames
         const frames = [];
         onProgress?.({
@@ -93,12 +101,15 @@ export async function runLoopMode(config, options) {
             const time = t * duration;
             // Update p5 runtime frameCount
             p.frameCount = frame;
-            // CRITICAL: Clear canvas before each draw() call
+            // CRITICAL: Reset canvas state before each draw() call
             // This enforces stateless, frame-authoritative rendering
-            // Preserves artist-defined backgrounds (if they call background() in draw)
+            // 1. Clear canvas (transparent)
             p.clear();
-            // Execute draw() with time variables
-            wrappedDraw(p, frame, t, time, t);
+            // 2. Reset blend mode to NORMAL (Protocol v1.1 requirement)
+            // Prevents blend mode state from persisting across frames
+            p.blendMode('NORMAL');
+            // Execute draw() with time variables, VAR, and totalFrames
+            wrappedDraw(p, frame, t, time, t, p.VAR, totalFrames);
             // Capture frame as PNG blob
             const blob = await new Promise((resolve, reject) => {
                 canvas.toBlob((b) => b ? resolve(b) : reject(new Error(`Failed to capture frame ${frame}`)), 'image/png');