@nexart/codemode-sdk 1.1.0 → 1.1.1

package/README.md

@@ -104,7 +104,8 @@ The SDK enforces the **NexArt Code Mode Protocol v1.0.0** for reproducible, mint
 ## Installation
 
 ```bash
-npm install @nexart/codemode-sdk
+# Copy the sdk/codemode folder to your project
+cp -r sdk/codemode your-project/lib/codemode
 ```
 
 ---
@@ -152,7 +153,7 @@ console.log(result.image);                    // PNG Blob
 | `width` | `number` | ✅ | Canvas width in pixels |
 | `height` | `number` | ✅ | Canvas height in pixels |
 | `seed` | `number` | ✅ | Seed for deterministic randomness |
-| `vars` | `number[]` | ❌ | VAR values (0-10 elements, 0-100 range), missing indices return 0 |
+| `vars` | `number[]` | ❌ | VAR[0..9] values (0-100), defaults to all zeros |
 | `mode` | `'static' \| 'loop'` | ✅ | Execution mode |
 | `totalFrames` | `number` | ⚠️ | Required for loop mode |
 
@@ -181,7 +182,63 @@ interface ExecuteCodeModeResult {
 
 ---
 
-## Protocol Variables (VAR[0..9]) — Protocol v1.0.0
+## Legacy API
+
+> ⚠️ **Note**: The `createEngine()` API is still supported but new implementations should use `executeCodeMode()`.
+
+### `createEngine(config: EngineConfig): Engine`
+
+Create a rendering engine instance.
+
+```typescript
+import { createEngine } from './codemode';
+
+const engine = createEngine({
+  mode: 'static',      // 'static' | 'loop'
+  width: 1950,         // Optional, default: 1950
+  height: 2400,        // Optional, default: 2400
+  duration: 2,         // Loop mode only, 1-4 seconds
+  fps: 30,             // Loop mode only, default: 30
+});
+```
+
+### `engine.run(options: RunOptions): Promise<void>`
+
+Execute code and produce output.
+
+```typescript
+await engine.run({
+  code: `
+    function setup() {
+      background(255);
+      fill(0);
+      // Use VAR for external control
+      let size = map(VAR[0], 0, 100, 50, 200);
+      ellipse(width/2, height/2, size);
+    }
+  `,
+  seed: 12345,              // Optional: seed for deterministic randomness
+  vars: [50, 75, 0, 0, 0, 0, 0, 0, 0, 0],  // Optional: VAR[0..9] values (0-100)
+  onPreview: (canvas) => {
+    // Optional: called with canvas after first frame
+  },
+  onProgress: (info) => {
+    // Optional: progress updates
+    console.log(info.message, info.percent + '%');
+  },
+  onComplete: (result) => {
+    // Required: called with final result
+    console.log(result.type); // 'image' | 'video'
+    console.log(result.blob); // Blob
+  },
+  onError: (error) => {
+    // Optional: called on error
+    console.error(error);
+  },
+});
+```
+
+### Protocol Variables (VAR[0..9]) — Protocol v1.0.0
 
 Protocol variables are first-class inputs that control artwork parameters.
 
@@ -199,7 +256,20 @@ Protocol variables are first-class inputs that control artwork parameters.
 | Default | All zeros | If not provided |
 
 ```typescript
-// Access in sketch code (missing indices return 0)
+// Pass values when running (0-10 elements)
+await engine.run({
+  code: myCode,
+  vars: [80, 50, 25],  // VAR[0]=80, VAR[1]=50, VAR[2]=25, VAR[3..9]=0
+  onComplete: (result) => { /* ... */ },
+});
+
+// Or omit entirely (all zeros)
+await engine.run({
+  code: myCode,
+  onComplete: (result) => { /* ... */ },
+});
+
+// Access in sketch code
 function setup() {
   let density = map(VAR[0], 0, 100, 10, 200);
   let speed = map(VAR[1], 0, 100, 0.5, 5);
@@ -215,6 +285,14 @@ function setup() {
 - Values MUST be in range 0-100 (throws if out of range)
 - Same code + same seed + same VARs = identical output
 
+### `engine.stop(): void`
+
+Cancel a running render (Loop mode only).
+
+### `engine.getConfig(): EngineConfig`
+
+Get the resolved engine configuration.
+
 ---
 
 ## Execution Rules
@@ -270,6 +348,76 @@ Additionally in Loop Mode:
 
 ---
 
+## Example: Static Mode
+
+```typescript
+import { createEngine } from './codemode';
+
+const engine = createEngine({ mode: 'static' });
+
+await engine.run({
+  code: `
+    function setup() {
+      background(30);
+      noStroke();
+      for (let i = 0; i < 100; i++) {
+        fill(random(255), random(255), random(255));
+        ellipse(random(width), random(height), 50);
+      }
+    }
+  `,
+  onComplete: (result) => {
+    // result.type === 'image'
+    // result.blob is a PNG Blob
+    const url = URL.createObjectURL(result.blob);
+    document.body.innerHTML = `<img src="${url}" />`;
+  },
+});
+```
+
+---
+
+## Example: Loop Mode
+
+```typescript
+import { createEngine } from './codemode';
+
+const engine = createEngine({
+  mode: 'loop',
+  duration: 2,  // 2 second loop
+});
+
+await engine.run({
+  code: `
+    function setup() {
+      // Called once
+    }
+    
+    function draw() {
+      background(30);
+      
+      // t goes from 0 to 1 over the loop duration
+      let x = width/2 + cos(t * TWO_PI) * 200;
+      let y = height/2 + sin(t * TWO_PI) * 200;
+      
+      fill(255);
+      ellipse(x, y, 80);
+    }
+  `,
+  onProgress: (info) => {
+    console.log(info.message);
+  },
+  onComplete: (result) => {
+    // result.type === 'video'
+    // result.blob is an MP4 Blob
+    const url = URL.createObjectURL(result.blob);
+    document.body.innerHTML = `<video src="${url}" autoplay loop />`;
+  },
+});
+```
+
+---
+
 ## Supported Functions
 
 The SDK includes a minimal p5.js-like runtime with:
@@ -310,21 +458,38 @@ All of the following are accepted by `fill()`, `stroke()`, `background()`:
 
 ---
 
-## Frozen Execution Guarantees — v1.0.0
+## Video Encoding
 
-The following guarantees are LOCKED and will not change in v1.x:
+Loop Mode requires server-side video encoding. The SDK calls:
 
-| Guarantee | Description |
-|-----------|-------------|
-| Determinism | Same code + same seed + same VARs = identical output |
-| Static Mode | `setup()` only, single PNG output |
-| Loop Mode | Frame-authoritative, `draw()` per frame, MP4 output |
-| Time Semantics | `t` ∈ [0,1), `frameCount` ∈ [0,totalFrames), `time` in seconds |
-| Random | Seeded Mulberry32 PRNG via `random()` |
-| Noise | Seeded Perlin noise via `noise()` |
-| Canvas | Pre-initialized, no `createCanvas()` |
-| VAR | Exactly 10 read-only protocol variables |
-| Forbidden Patterns | 13 patterns rejected (see above) |
+```
+POST /api/encode-loop
+```
+
+Ensure your server has this endpoint available (NexArt provides this).
+
+---
+
+## Files
+
+```
+sdk/codemode/
+├── index.ts         # Main export
+├── engine.ts        # createEngine entry point
+├── types.ts         # TypeScript types
+├── static-engine.ts # Static mode implementation
+├── loop-engine.ts   # Loop mode implementation
+├── p5-runtime.ts    # p5.js-like runtime
+└── README.md        # This file
+```
+
+---
+
+## License
+
+MIT License
+
+Copyright (c) 2024 NexArt
 
 ---
 
@@ -373,50 +538,27 @@ try {
 
 ---
 
-## Video Encoding
-
-Loop Mode requires server-side video encoding. The SDK calls:
-
-```
-POST /api/encode-loop
-```
-
-Ensure your server has this endpoint available (NexArt provides this).
-
----
-
-## Files
-
-```
-@nexart/codemode-sdk/
-├── index.ts         # Main export
-├── engine.ts        # createEngine entry point
-├── execute.ts       # Canonical executeCodeMode API
-├── types.ts         # TypeScript types
-├── static-engine.ts # Static mode implementation
-├── loop-engine.ts   # Loop mode implementation
-├── p5-runtime.ts    # p5.js-like runtime
-└── README.md        # This file
-```
-
----
-
-## Changelog
-
-**1.0.2** — VAR is now optional (0-10 elements). Missing indices return 0. Out-of-range throws.
-
-**1.0.1** — Protocol Lock formalized. VAR specification clarified. CHANGELOG added.
-
-**1.0.0** — Protocol Lock. Phase 1 execution surface HARD LOCKED. executeCodeMode() canonical API.
+## Frozen Execution Guarantees — v1.0.0
 
-**0.1.1** — Fixed beginShape / vertex / endShape rendering bug.
+The following guarantees are LOCKED and will not change in v1.x:
 
-**0.1.0** — Initial release.
+| Guarantee | Description |
+|-----------|-------------|
+| Determinism | Same code + same seed + same VARs = identical output |
+| Static Mode | `setup()` only, single PNG output |
+| Loop Mode | Frame-authoritative, `draw()` per frame, MP4 output |
+| Time Semantics | `t` ∈ [0,1), `frameCount` ∈ [0,totalFrames), `time` in seconds |
+| Random | Seeded Mulberry32 PRNG via `random()` |
+| Noise | Seeded Perlin noise via `noise()` |
+| Canvas | Pre-initialized, no `createCanvas()` |
+| VAR | Exactly 10 read-only protocol variables |
+| Forbidden Patterns | 13 patterns rejected (see above) |
 
 ---
 
-## License
-
-MIT License
+## Future Work (Phase 2+)
 
-Copyright (c) 2024 NexArt
+- GSL v1 SDK (protocol layer) — separate package
+- Extended p5.js compatibility
+- WebGL rendering support
+- GIF output option

package/dist/core-index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @nexart/codemode-sdk v1.1.0 — Core Exports
+ *
+ * Canonical execution engine for NexArt Code Mode.
+ * This is the single source of truth for Code Mode semantics.
+ *
+ * Protocol: v1.0.0 (LOCKED)
+ * Enforcement: HARD
+ */
+export { executeCodeMode, validateCodeModeSource, } from './execute';
+export { type RenderMode, type TimeVariables, type ProtocolMetadata, type EngineConfig, type RenderResult, type RunOptions, type ProgressInfo, type Engine, type ExecuteCodeModeInput, type ExecuteCodeModeResult, PROTOCOL_IDENTITY, DEFAULT_VARS, DEFAULT_CONFIG, } from './types';
+export { createP5Runtime, injectTimeVariables, createProtocolVAR, VAR_COUNT, VAR_MIN, VAR_MAX, CODE_MODE_PROTOCOL_VERSION, CODE_MODE_PROTOCOL_PHASE, CODE_MODE_ENFORCEMENT, type P5Runtime, type P5RuntimeConfig, } from './p5-runtime';
+export { runStaticMode, } from './static-engine';
+export { runLoopMode, cancelLoopMode, } from './loop-engine';
+export { createEngine, } from './engine';
+/**
+ * SDK Identity
+ */
+export declare const SDK_VERSION = "1.1.1";
+export declare const SDK_NAME = "@nexart/codemode-sdk";
+//# sourceMappingURL=core-index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"core-index.d.ts","sourceRoot":"","sources":["../core-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EACL,eAAe,EACf,sBAAsB,GACvB,MAAM,WAAW,CAAC;AAGnB,OAAO,EACL,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,MAAM,EACX,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,iBAAiB,EACjB,YAAY,EACZ,cAAc,GACf,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,iBAAiB,EACjB,SAAS,EACT,OAAO,EACP,OAAO,EACP,0BAA0B,EAC1B,wBAAwB,EACxB,qBAAqB,EACrB,KAAK,SAAS,EACd,KAAK,eAAe,GACrB,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,aAAa,GACd,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,WAAW,EACX,cAAc,GACf,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,YAAY,GACb,MAAM,UAAU,CAAC;AAElB;;GAEG;AACH,eAAO,MAAM,WAAW,UAAU,CAAC;AACnC,eAAO,MAAM,QAAQ,yBAAyB,CAAC"}

package/dist/core-index.js

@@ -0,0 +1,26 @@
+/**
+ * @nexart/codemode-sdk v1.1.0 — Core Exports
+ *
+ * Canonical execution engine for NexArt Code Mode.
+ * This is the single source of truth for Code Mode semantics.
+ *
+ * Protocol: v1.0.0 (LOCKED)
+ * Enforcement: HARD
+ */
+// Core execution
+export { executeCodeMode, validateCodeModeSource, } from './execute';
+// Protocol types
+export { PROTOCOL_IDENTITY, DEFAULT_VARS, DEFAULT_CONFIG, } from './types';
+// Runtime
+export { createP5Runtime, injectTimeVariables, createProtocolVAR, VAR_COUNT, VAR_MIN, VAR_MAX, CODE_MODE_PROTOCOL_VERSION, CODE_MODE_PROTOCOL_PHASE, CODE_MODE_ENFORCEMENT, } from './p5-runtime';
+// Static engine
+export { runStaticMode, } from './static-engine';
+// Loop engine
+export { runLoopMode, cancelLoopMode, } from './loop-engine';
+// Engine utilities
+export { createEngine, } from './engine';
+/**
+ * SDK Identity
+ */
+export const SDK_VERSION = '1.1.1';
+export const SDK_NAME = '@nexart/codemode-sdk';

package/dist/execute.d.ts

@@ -0,0 +1,46 @@
+/**
+ * NexArt Code Mode Runtime SDK - Canonical Execution Entry Point
+ *
+ * ╔══════════════════════════════════════════════════════════════════════════╗
+ * ║  CODE MODE PROTOCOL v1.0.0 (Phase 1) — 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 { ExecuteCodeModeInput, ExecuteCodeModeResult } from './types';
+/**
+ * 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.0.0'
+ * console.log(result.image); // PNG Blob
+ * ```
+ */
+export declare function executeCodeMode(input: ExecuteCodeModeInput): Promise<ExecuteCodeModeResult>;
+/**
+ * Validate code without executing
+ */
+export declare function validateCodeModeSource(source: string, mode: 'static' | 'loop'): {
+    valid: boolean;
+    errors: string[];
+};
+//# sourceMappingURL=execute.d.ts.map

package/dist/execute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../execute.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/execute.js

@@ -0,0 +1,268 @@
+/**
+ * NexArt Code Mode Runtime SDK - Canonical Execution Entry Point
+ *
+ * ╔══════════════════════════════════════════════════════════════════════════╗
+ * ║  CODE MODE PROTOCOL v1.0.0 (Phase 1) — 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 { runStaticMode } from './static-engine';
+import { runLoopMode } from './loop-engine';
+import { PROTOCOL_IDENTITY, DEFAULT_CONFIG, } from './types';
+/**
+ * Validate and normalize VAR array to 10 elements.
+ *
+ * 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
+ */
+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}`);
+        }
+        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');
+        }
+    }
+    // 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}`);
+        }
+    }
+    // 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');
+        }
+        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.0.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.0.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.0.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.0.0 — Phase 1 — 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 {
+        valid: errors.length === 0,
+        errors,
+    };
+}