@nexart/codemode-sdk 1.5.1 → 1.6.0

package/CHANGELOG.md

@@ -4,6 +4,43 @@ All notable changes to @nexart/codemode-sdk will be documented in this file.
 
 ---
 
+## [1.6.0] — 2026-01-12
+
+### Added — Licensing & Builder Identity Scaffolding
+
+**Non-Breaking, Metadata-Only Release**
+
+This release introduces scaffolding for future licensing and builder identity features. All additions are informational only — no behavior changes, no enforcement, no runtime validation.
+
+#### Licensing (Informational Only)
+- **LICENSE.md**: Draft commercial licensing terms with enforcement NOT active
+- README section: "Commercial usage of NexArt Protocol requires a license. Enforcement is not active yet."
+
+#### Builder Manifest Schema (Optional)
+- **builder.manifest.schema.json**: JSON schema for optional builder attribution
+- Fields: `builder_id`, `project_name`, `contact`, `website`, `intended_use`
+- NOT validated, NOT loaded at runtime, NOT required
+
+#### Documentation
+- Positioned SDK as "canonical execution surface"
+- Explained determinism guarantees explicitly
+- Referenced real products (ByX, Frontierra)
+
+### Unchanged
+
+- No changes to execution or determinism
+- No changes to protocol version (remains v1.2.0)
+- No runtime validation or enforcement
+- No new required files or dependencies
+- Full backward compatibility with v1.5.x
+- Existing sketches run unchanged
+
+### Verification
+
+Run `npx tsx scripts/check-determinism.ts` — must pass before release.
+
+---
+
 ## [1.5.1] — 2026-01-05
 
 ### Added

package/LICENSE.md

@@ -0,0 +1,62 @@
+NexArt Code Mode SDK — License
+
+Version: 1.6.0
+Status: DRAFT — Enforcement Not Active
+
+⸻
+
+License Status
+
+The NexArt Code Mode SDK is currently released under the MIT License.
+
+At this time, all usage — including commercial usage — is permitted under the MIT License.
+
+This document also serves as advance notice of a future commercial licensing model that may apply to certain uses of the NexArt Protocol.
+
+⸻
+
+Future Commercial Licensing (Not Active)
+
+NexArt intends to introduce a separate commercial license for specific categories of usage in a future release.
+
+Planned commercial usage categories may include (non-exhaustive):
+	•	Minting NFTs for sale
+	•	Revenue-generating applications
+	•	Products or services that charge fees
+	•	Enterprise or business deployments
+
+Enforcement is NOT active.
+
+No license keys, validation, usage tracking, or commercial restrictions are currently implemented.
+
+Until enforcement is introduced in a future version, all usage remains governed solely by the MIT License below.
+
+⸻
+
+MIT License
+
+Copyright (c) 2024–2026 NexArt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the “Software”), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+⸻
+
+Contact
+
+For future commercial licensing inquiries: arrotu@artnames.io

package/README.md

@@ -1,16 +1,15 @@
 # NexArt Code Mode Runtime SDK
 
-**Version: 1.5.1 (Protocol v1.2.0)**
+**Version: 1.6.0 (Protocol v1.2.0)**
 
 ╔══════════════════════════════════════════════════════════════════════════════╗
-║  @nexart/codemode-sdk — Canonical Code Mode Authority                        ║
+║  @nexart/codemode-sdk — Canonical Execution Surface                          ║
 ║                                                                              ║
-║  This SDK defines the official Code Mode execution surface.                  ║
-║  All implementations (NexArt, ByX, external) MUST use this SDK.              ║
+║  This SDK IS the protocol. All implementations MUST use this SDK.            ║
 ║                                                                              ║
 ║  Protocol: nexart                                                            ║
 ║  Engine: codemode                                                            ║
-║  SDK Version: 1.5.1                                                          ║
+║  SDK Version: 1.6.0                                                          ║
 ║  Protocol Version: 1.2.0                                                     ║
 ║  Phase: 3                                                                    ║
 ║  Enforcement: HARD                                                           ║
@@ -18,6 +17,15 @@
 
 ---
 
+## Commercial Licensing
+
+> **Commercial usage of NexArt Protocol requires a license.**
+> **Enforcement is not active yet.**
+
+The SDK is currently provided under the MIT License for all usage. A future version may introduce commercial licensing requirements. See [LICENSE.md](./LICENSE.md) for details.
+
+---
+
 ## PROTOCOL LOCK — v1.x
 
 | Property | Value |
@@ -54,32 +62,85 @@ The answer is: "Whatever @nexart/codemode-sdk does — that is the protocol."
 
 ---
 
-## What's New in v1.5.1
+## What's New in v1.6.0
 
-**Builder Manifest — Passive Attribution (Write-Only)**
+**Licensing & Builder Identity Scaffolding (Metadata Only)**
 
-- `registerBuilderManifest(manifest?)` — Declare builder identity for future attribution
+This is a non-breaking, metadata-only release. No changes to execution or determinism.
 
-**The Builder Manifest is a declaration of intent, not a capability.**
+### Licensing (Informational Only)
+- Added `LICENSE.md` with draft commercial licensing terms
+- Enforcement is NOT active — all usage currently permitted under MIT
 
-The SDK does not expose any API to read or inspect manifests. This is:
-- **Declarative** — Write-only, no read API exposed
-- **Optional** — No errors if missing or invalid
-- **Non-enforced** — No validation logic
-- **Non-rewarding** — No incentives, no tracking
+### Builder Manifest Schema
+- Added `builder.manifest.schema.json` for optional builder attribution
+- Fields: `builder_id`, `project_name`, `contact`, `website`, `intended_use`
+- This file is **optional**, **not validated**, and **not loaded at runtime**
 
-There is NO SDK API to read manifests, NO validation, NO attribution logic, and NO tracking. Execution behavior is identical with or without a manifest registered.
+### Documentation
+- SDK positioned as "canonical execution surface"
+- Explicit determinism guarantees documented
+- Real product references (ByX, Frontierra)
 
-```typescript
-import { registerBuilderManifest } from '@nexart/codemode-sdk';
+---
 
-registerBuilderManifest({
-  protocol: 'nexart',
-  manifestVersion: '0.1',
-  app: { name: 'My App', url: 'https://myapp.com' }
-});
+## Determinism Guarantees
+
+**The NexArt Code Mode SDK guarantees deterministic output.**
+
+Given identical inputs:
+- Same `source` code
+- Same `seed`
+- Same `vars` array
+- Same `width` and `height`
+- Same `mode`
+
+The SDK will produce **byte-for-byte identical output** across all executions.
+
+### What Breaks Determinism
+
+The following actions will break determinism and are **blocked** by the SDK:
+
+| Pattern | Reason | Enforcement |
+|---------|--------|-------------|
+| `Math.random()` | Unseeded randomness | BLOCKED |
+| `Date.now()` | Time-based entropy | BLOCKED |
+| `new Date()` | Time-based entropy | BLOCKED |
+| `performance.now()` | Timing entropy | BLOCKED |
+| `crypto.getRandomValues()` | Crypto randomness | BLOCKED |
+| `fetch()` | External IO | BLOCKED |
+| External imports | Uncontrolled code | BLOCKED |
+
+Use `random()` (seeded) and `noise()` (seeded) for all randomness needs.
+
+### Oracle Verification
+
+Before any release, run the determinism check:
+
+```bash
+npx tsx scripts/check-determinism.ts
 ```
 
+This compares output against a known oracle hash. If the hash changes without a protocol version bump, the release is invalid.
+
+---
+
+## Products Using This SDK
+
+- **NexArt**: Primary generative art platform
+- **ByX**: Curated collection system
+- **Frontierra**: External builder integration
+
+---
+
+## v1.5.1
+
+**Builder Manifest — Passive Attribution (Write-Only)**
+
+- `registerBuilderManifest(manifest?)` — Declare builder identity for future attribution
+
+The Builder Manifest is a declaration of intent, not a capability. Write-only, optional, non-enforced.
+
 ---
 
 ## v1.4.0 (Protocol v1.2.0)

package/builder.manifest.schema.json

@@ -0,0 +1,62 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://nexart.art/schemas/builder.manifest.json",
+  "title": "NexArt Builder Manifest",
+  "description": "Optional metadata file for builder attribution. NOT validated, NOT required, NOT enforced.",
+  "type": "object",
+  "properties": {
+    "protocol": {
+      "type": "string",
+      "const": "nexart",
+      "description": "Protocol identifier (must be 'nexart')"
+    },
+    "manifest_version": {
+      "type": "string",
+      "description": "Version of this manifest schema",
+      "default": "1.0"
+    },
+    "builder_id": {
+      "type": "string",
+      "description": "Unique identifier for the builder (self-assigned)"
+    },
+    "project_name": {
+      "type": "string",
+      "description": "Name of the project or application"
+    },
+    "description": {
+      "type": "string",
+      "description": "Brief description of the project"
+    },
+    "contact": {
+      "type": "string",
+      "description": "Contact email or handle"
+    },
+    "website": {
+      "type": "string",
+      "format": "uri",
+      "description": "Project website URL"
+    },
+    "intended_use": {
+      "type": "string",
+      "enum": ["art", "game", "research", "commercial", "education", "other"],
+      "description": "Primary intended use case"
+    },
+    "sdk_version": {
+      "type": "string",
+      "description": "Version of @nexart/codemode-sdk being used"
+    },
+    "features": {
+      "type": "object",
+      "description": "Optional feature flags",
+      "additionalProperties": {
+        "type": "boolean"
+      }
+    },
+    "metadata": {
+      "type": "object",
+      "description": "Arbitrary additional metadata",
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": true
+}

package/dist/builder-manifest.d.ts

@@ -1,6 +1,6 @@
 /**
  * NexArt Code Mode SDK - Builder Manifest
- * Version: 1.5.1 (Protocol v1.2.0)
+ * Version: 1.6.0 (Protocol v1.2.0)
  *
  * ╔══════════════════════════════════════════════════════════════════════════╗
  * ║  BUILDER MANIFEST — PASSIVE ATTRIBUTION (WRITE-ONLY)                     ║

package/dist/builder-manifest.js

@@ -1,6 +1,6 @@
 /**
  * NexArt Code Mode SDK - Builder Manifest
- * Version: 1.5.1 (Protocol v1.2.0)
+ * Version: 1.6.0 (Protocol v1.2.0)
  *
  * ╔══════════════════════════════════════════════════════════════════════════╗
  * ║  BUILDER MANIFEST — PASSIVE ATTRIBUTION (WRITE-ONLY)                     ║

package/dist/execute.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../execute.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EAMtB,MAAM,SAAS,CAAC;AAsNjB;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,oBAAoB,GAC1B,OAAO,CAAC,qBAAqB,CAAC,CAmChC;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"}
+{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../execute.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EAMtB,MAAM,SAAS,CAAC;AAuNjB;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,oBAAoB,GAC1B,OAAO,CAAC,qBAAqB,CAAC,CAmChC;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

@@ -143,7 +143,8 @@ async function executeStatic(input, vars) {
             vars: vars,
             onComplete: (result) => {
                 resolve({
-                    image: result.blob,
+                    image: 'blob' in result ? result.blob : undefined,
+                    frames: 'imageData' in result ? [result.imageData] : undefined,
                     metadata: createMetadata(input, vars),
                 });
             },
@@ -174,7 +175,7 @@ async function executeLoop(input, vars) {
             vars: vars,
             onComplete: (result) => {
                 resolve({
-                    video: result.blob,
+                    video: 'blob' in result && result.type === 'video' ? result.blob : undefined,
                     metadata: createMetadata(input, vars),
                 });
             },
@@ -214,7 +215,7 @@ export async function executeCodeMode(input) {
     // Normalize VAR values
     const vars = normalizeVars(input.vars);
     // ╔═══════════════════════════════════════════════════════════════════════╗
-    // ║  BUILDER MANIFEST CONTEXT (v1.5.1)                                    ║
+    // ║  BUILDER MANIFEST CONTEXT (v1.6.0)                                    ║
     // ║                                                                       ║
     // ║  Internal context for builder attribution.                            ║
     // ║  This is NOT exposed to sketch code, NOT serialized, NOT logged.      ║

package/dist/execution-sandbox.d.ts

@@ -0,0 +1,107 @@
+/**
+ * NexArt Code Mode SDK - Execution Sandbox
+ * Version: 1.6.0 (Protocol v1.2.0)
+ *
+ * ╔══════════════════════════════════════════════════════════════════════════╗
+ * ║  EXECUTION BOUNDARY — HARD ENFORCEMENT                                   ║
+ * ║                                                                          ║
+ * ║  This module enforces determinism by blocking all external entropy       ║
+ * ║  sources at RUNTIME, not just via static pattern scanning.               ║
+ * ║                                                                          ║
+ * ║  Blocked APIs (throw [Code Mode Protocol Error]):                        ║
+ * ║  - Date, Date.now, Date.parse, new Date()                                ║
+ * ║  - performance, performance.now                                          ║
+ * ║  - process (Node.js)                                                     ║
+ * ║  - navigator                                                             ║
+ * ║  - globalThis                                                            ║
+ * ║  - crypto.getRandomValues                                                ║
+ * ║  - Math.random (use seeded random() instead)                             ║
+ * ║  - setTimeout, setInterval, requestAnimationFrame                        ║
+ * ║  - fetch, XMLHttpRequest                                                 ║
+ * ║  - document, window                                                      ║
+ * ║  - import, require                                                       ║
+ * ║                                                                          ║
+ * ║  All blocked symbols throw immediately on access — no silent undefined.  ║
+ * ╚══════════════════════════════════════════════════════════════════════════╝
+ */
+/**
+ * Forbidden APIs - these are injected into the execution scope to override globals
+ */
+export declare const FORBIDDEN_APIS: {
+    readonly Date: (...args: any[]) => never;
+    readonly performance: object;
+    readonly process: object;
+    readonly navigator: object;
+    readonly globalThis: object;
+    readonly crypto: object;
+    readonly setTimeout: (...args: any[]) => never;
+    readonly setInterval: (...args: any[]) => never;
+    readonly clearTimeout: (...args: any[]) => never;
+    readonly clearInterval: (...args: any[]) => never;
+    readonly requestAnimationFrame: (...args: any[]) => never;
+    readonly cancelAnimationFrame: (...args: any[]) => never;
+    readonly fetch: (...args: any[]) => never;
+    readonly XMLHttpRequest: (...args: any[]) => never;
+    readonly WebSocket: (...args: any[]) => never;
+    readonly document: object;
+    readonly window: object;
+    readonly self: object;
+    readonly top: object;
+    readonly parent: object;
+    readonly frames: object;
+    readonly location: object;
+    readonly history: object;
+    readonly localStorage: object;
+    readonly sessionStorage: object;
+    readonly indexedDB: object;
+    readonly caches: object;
+    readonly Notification: (...args: any[]) => never;
+    readonly Worker: (...args: any[]) => never;
+    readonly SharedWorker: (...args: any[]) => never;
+    readonly ServiceWorker: object;
+    readonly Blob: (...args: any[]) => never;
+    readonly File: (...args: any[]) => never;
+    readonly FileReader: (...args: any[]) => never;
+    readonly URL: (...args: any[]) => never;
+    readonly URLSearchParams: (...args: any[]) => never;
+    readonly Headers: (...args: any[]) => never;
+    readonly Request: (...args: any[]) => never;
+    readonly Response: (...args: any[]) => never;
+    readonly EventSource: (...args: any[]) => never;
+    readonly Image: (...args: any[]) => never;
+    readonly Audio: (...args: any[]) => never;
+    readonly Video: (...args: any[]) => never;
+    readonly eval: (...args: any[]) => never;
+    readonly Function: (...args: any[]) => never;
+};
+/**
+ * Create a safe Math object with random() blocked
+ */
+export declare function createSafeMath(): typeof Math;
+/**
+ * List of all forbidden API names for documentation
+ */
+export declare const FORBIDDEN_API_NAMES: string[];
+/**
+ * Build the complete sandbox context for sketch execution.
+ * This includes the p5 runtime plus all forbidden API stubs.
+ */
+export declare function buildSandboxContext(p5Runtime: Record<string, any>): Record<string, any>;
+/**
+ * Create a sandboxed function that executes user code with blocked globals.
+ *
+ * The function is constructed with:
+ * 1. All forbidden APIs as explicit parameters (override globals)
+ * 2. The p5 runtime as explicit parameters
+ * 3. A `with(context)` wrapper for additional safety
+ */
+export declare function createSandboxedExecutor(code: string, additionalParams?: string[]): Function;
+/**
+ * Execute user code in a sandboxed environment.
+ *
+ * @param code - The user sketch code to execute
+ * @param p5Runtime - The p5-like runtime object
+ * @param additionalContext - Additional context variables (frameCount, t, etc.)
+ */
+export declare function executeSandboxed(code: string, p5Runtime: Record<string, any>, additionalContext?: Record<string, any>): void;
+//# sourceMappingURL=execution-sandbox.d.ts.map

package/dist/execution-sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution-sandbox.d.ts","sourceRoot":"","sources":["../execution-sandbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAyDH;;GAEG;AACH,eAAO,MAAM,cAAc;6BAvD2B,GAAG,EAAE,KAAK,KAAK;;;;;;mCAAf,GAAG,EAAE,KAAK,KAAK;oCAAf,GAAG,EAAE,KAAK,KAAK;qCAAf,GAAG,EAAE,KAAK,KAAK;sCAAf,GAAG,EAAE,KAAK,KAAK;8CAAf,GAAG,EAAE,KAAK,KAAK;6CAAf,GAAG,EAAE,KAAK,KAAK;8BAAf,GAAG,EAAE,KAAK,KAAK;uCAAf,GAAG,EAAE,KAAK,KAAK;kCAAf,GAAG,EAAE,KAAK,KAAK;;;;;;;;;;;;;qCAAf,GAAG,EAAE,KAAK,KAAK;+BAAf,GAAG,EAAE,KAAK,KAAK;qCAAf,GAAG,EAAE,KAAK,KAAK;;6BAAf,GAAG,EAAE,KAAK,KAAK;6BAAf,GAAG,EAAE,KAAK,KAAK;mCAAf,GAAG,EAAE,KAAK,KAAK;4BAAf,GAAG,EAAE,KAAK,KAAK;wCAAf,GAAG,EAAE,KAAK,KAAK;gCAAf,GAAG,EAAE,KAAK,KAAK;gCAAf,GAAG,EAAE,KAAK,KAAK;iCAAf,GAAG,EAAE,KAAK,KAAK;oCAAf,GAAG,EAAE,KAAK,KAAK;8BAAf,GAAG,EAAE,KAAK,KAAK;8BAAf,GAAG,EAAE,KAAK,KAAK;8BAAf,GAAG,EAAE,KAAK,KAAK;6BAAf,GAAG,EAAE,KAAK,KAAK;iCAAf,GAAG,EAAE,KAAK,KAAK;CAqG3D,CAAC;AAEX;;GAEG;AACH,wBAAgB,cAAc,IAAI,OAAO,IAAI,CAU5C;AAED;;GAEG;AACH,eAAO,MAAM,mBAAmB,UAA8B,CAAC;AAE/D;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAavF;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,MAAM,EACZ,gBAAgB,GAAE,MAAM,EAAO,GAC9B,QAAQ,CAiBV;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC9B,iBAAiB,GAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAM,GAC1C,IAAI,CAsBN"}

package/dist/execution-sandbox.js

@@ -0,0 +1,207 @@
+/**
+ * NexArt Code Mode SDK - Execution Sandbox
+ * Version: 1.6.0 (Protocol v1.2.0)
+ *
+ * ╔══════════════════════════════════════════════════════════════════════════╗
+ * ║  EXECUTION BOUNDARY — HARD ENFORCEMENT                                   ║
+ * ║                                                                          ║
+ * ║  This module enforces determinism by blocking all external entropy       ║
+ * ║  sources at RUNTIME, not just via static pattern scanning.               ║
+ * ║                                                                          ║
+ * ║  Blocked APIs (throw [Code Mode Protocol Error]):                        ║
+ * ║  - Date, Date.now, Date.parse, new Date()                                ║
+ * ║  - performance, performance.now                                          ║
+ * ║  - process (Node.js)                                                     ║
+ * ║  - navigator                                                             ║
+ * ║  - globalThis                                                            ║
+ * ║  - crypto.getRandomValues                                                ║
+ * ║  - Math.random (use seeded random() instead)                             ║
+ * ║  - setTimeout, setInterval, requestAnimationFrame                        ║
+ * ║  - fetch, XMLHttpRequest                                                 ║
+ * ║  - document, window                                                      ║
+ * ║  - import, require                                                       ║
+ * ║                                                                          ║
+ * ║  All blocked symbols throw immediately on access — no silent undefined.  ║
+ * ╚══════════════════════════════════════════════════════════════════════════╝
+ */
+/**
+ * Create a throwing stub for a forbidden API
+ */
+function createForbiddenStub(name) {
+    const stub = function () {
+        throw new Error(`[Code Mode Protocol Error] Forbidden API: ${name}`);
+    };
+    return new Proxy(stub, {
+        get(_target, prop) {
+            if (prop === Symbol.toPrimitive || prop === 'toString' || prop === 'valueOf') {
+                return () => { throw new Error(`[Code Mode Protocol Error] Forbidden API: ${name}`); };
+            }
+            throw new Error(`[Code Mode Protocol Error] Forbidden API: ${name}.${String(prop)}`);
+        },
+        apply() {
+            throw new Error(`[Code Mode Protocol Error] Forbidden API: ${name}()`);
+        },
+        construct() {
+            throw new Error(`[Code Mode Protocol Error] Forbidden API: new ${name}()`);
+        },
+        set() {
+            throw new Error(`[Code Mode Protocol Error] Forbidden API: ${name} (assignment blocked)`);
+        },
+        has() {
+            return true;
+        }
+    });
+}
+/**
+ * Create a frozen object that throws on any property access
+ */
+function createForbiddenObject(name) {
+    return new Proxy({}, {
+        get(_target, prop) {
+            if (prop === Symbol.toPrimitive || prop === 'toString' || prop === 'valueOf') {
+                return () => { throw new Error(`[Code Mode Protocol Error] Forbidden API: ${name}`); };
+            }
+            throw new Error(`[Code Mode Protocol Error] Forbidden API: ${name}.${String(prop)}`);
+        },
+        set() {
+            throw new Error(`[Code Mode Protocol Error] Forbidden API: ${name} (assignment blocked)`);
+        },
+        has() {
+            return true;
+        },
+        apply() {
+            throw new Error(`[Code Mode Protocol Error] Forbidden API: ${name}()`);
+        },
+        construct() {
+            throw new Error(`[Code Mode Protocol Error] Forbidden API: new ${name}()`);
+        }
+    });
+}
+/**
+ * Forbidden APIs - these are injected into the execution scope to override globals
+ */
+export const FORBIDDEN_APIS = {
+    Date: createForbiddenStub('Date'),
+    performance: createForbiddenObject('performance'),
+    process: createForbiddenObject('process'),
+    navigator: createForbiddenObject('navigator'),
+    globalThis: createForbiddenObject('globalThis'),
+    crypto: createForbiddenObject('crypto'),
+    setTimeout: createForbiddenStub('setTimeout'),
+    setInterval: createForbiddenStub('setInterval'),
+    clearTimeout: createForbiddenStub('clearTimeout'),
+    clearInterval: createForbiddenStub('clearInterval'),
+    requestAnimationFrame: createForbiddenStub('requestAnimationFrame'),
+    cancelAnimationFrame: createForbiddenStub('cancelAnimationFrame'),
+    fetch: createForbiddenStub('fetch'),
+    XMLHttpRequest: createForbiddenStub('XMLHttpRequest'),
+    WebSocket: createForbiddenStub('WebSocket'),
+    document: createForbiddenObject('document'),
+    window: createForbiddenObject('window'),
+    self: createForbiddenObject('self'),
+    top: createForbiddenObject('top'),
+    parent: createForbiddenObject('parent'),
+    frames: createForbiddenObject('frames'),
+    location: createForbiddenObject('location'),
+    history: createForbiddenObject('history'),
+    localStorage: createForbiddenObject('localStorage'),
+    sessionStorage: createForbiddenObject('sessionStorage'),
+    indexedDB: createForbiddenObject('indexedDB'),
+    caches: createForbiddenObject('caches'),
+    Notification: createForbiddenStub('Notification'),
+    Worker: createForbiddenStub('Worker'),
+    SharedWorker: createForbiddenStub('SharedWorker'),
+    ServiceWorker: createForbiddenObject('ServiceWorker'),
+    Blob: createForbiddenStub('Blob'),
+    File: createForbiddenStub('File'),
+    FileReader: createForbiddenStub('FileReader'),
+    URL: createForbiddenStub('URL'),
+    URLSearchParams: createForbiddenStub('URLSearchParams'),
+    Headers: createForbiddenStub('Headers'),
+    Request: createForbiddenStub('Request'),
+    Response: createForbiddenStub('Response'),
+    EventSource: createForbiddenStub('EventSource'),
+    Image: createForbiddenStub('Image'),
+    Audio: createForbiddenStub('Audio'),
+    Video: createForbiddenStub('Video'),
+    eval: createForbiddenStub('eval'),
+    Function: createForbiddenStub('Function'),
+};
+/**
+ * Create a safe Math object with random() blocked
+ */
+export function createSafeMath() {
+    const safeMath = Object.create(Math);
+    Object.defineProperty(safeMath, 'random', {
+        get() {
+            throw new Error('[Code Mode Protocol Error] Forbidden API: Math.random() — use random() instead (seeded)');
+        },
+        configurable: false,
+        enumerable: true
+    });
+    return Object.freeze(safeMath);
+}
+/**
+ * List of all forbidden API names for documentation
+ */
+export const FORBIDDEN_API_NAMES = Object.keys(FORBIDDEN_APIS);
+/**
+ * Build the complete sandbox context for sketch execution.
+ * This includes the p5 runtime plus all forbidden API stubs.
+ */
+export function buildSandboxContext(p5Runtime) {
+    const safeMath = createSafeMath();
+    const context = {
+        ...FORBIDDEN_APIS,
+        Math: safeMath,
+    };
+    for (const key of Object.keys(p5Runtime)) {
+        context[key] = p5Runtime[key];
+    }
+    return context;
+}
+/**
+ * Create a sandboxed function that executes user code with blocked globals.
+ *
+ * The function is constructed with:
+ * 1. All forbidden APIs as explicit parameters (override globals)
+ * 2. The p5 runtime as explicit parameters
+ * 3. A `with(context)` wrapper for additional safety
+ */
+export function createSandboxedExecutor(code, additionalParams = []) {
+    const forbiddenParamNames = Object.keys(FORBIDDEN_APIS);
+    const allParams = [
+        'context',
+        'Math',
+        ...forbiddenParamNames,
+        ...additionalParams
+    ];
+    const wrappedCode = `
+    "use strict";
+    with(context) {
+      ${code}
+    }
+  `;
+    return new Function(...allParams, wrappedCode);
+}
+/**
+ * Execute user code in a sandboxed environment.
+ *
+ * @param code - The user sketch code to execute
+ * @param p5Runtime - The p5-like runtime object
+ * @param additionalContext - Additional context variables (frameCount, t, etc.)
+ */
+export function executeSandboxed(code, p5Runtime, additionalContext = {}) {
+    const safeMath = createSafeMath();
+    const fullContext = {
+        ...p5Runtime,
+        ...additionalContext,
+        Math: safeMath,
+        ...FORBIDDEN_APIS,
+    };
+    const forbiddenValues = Object.keys(FORBIDDEN_APIS).map(key => FORBIDDEN_APIS[key]);
+    const additionalParamNames = Object.keys(additionalContext);
+    const additionalValues = Object.values(additionalContext);
+    const executor = createSandboxedExecutor(code, additionalParamNames);
+    executor(fullContext, safeMath, ...forbiddenValues, ...additionalValues);
+}

package/dist/loop-engine.d.ts

@@ -12,6 +12,9 @@
  *
  * Determinism Guarantee:
  * Same code + same seed + same VARs = identical frame sequence
+ *
+ * Security:
+ * All external entropy sources are blocked at runtime via execution sandbox.
  */
 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;;;;;;;;;;;;;;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"}
+{"version":3,"file":"loop-engine.d.ts","sourceRoot":"","sources":["../loop-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAA+B,MAAM,SAAS,CAAC;AAOrF,wBAAgB,cAAc,IAAI,IAAI,CAErC;AAED,wBAAsB,WAAW,CAC/B,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,UAAU,GAClB,OAAO,CAAC,IAAI,CAAC,CA+Mf"}

package/dist/loop-engine.js

@@ -12,9 +12,13 @@
  *
  * Determinism Guarantee:
  * Same code + same seed + same VARs = identical frame sequence
+ *
+ * Security:
+ * All external entropy sources are blocked at runtime via execution sandbox.
  */
 import { DEFAULT_CONFIG } from './types';
 import { createP5Runtime, injectProtocolVariables } from './p5-runtime';
+import { FORBIDDEN_APIS, createSafeMath } from './execution-sandbox';
 let isCancelled = false;
 export function cancelLoopMode() {
     isCancelled = true;
@@ -72,16 +76,22 @@ export async function runLoopMode(config, options) {
         }
         // 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} }`);
+        // Create sandboxed execution context
+        // All forbidden APIs are injected as parameters to override globals
+        const safeMath = createSafeMath();
+        const forbiddenKeys = Object.keys(FORBIDDEN_APIS);
+        // Create wrapped functions with p5 context, time variables, VAR, totalFrames, and blocked globals
+        const wrappedSetup = new Function('p', 'frameCount', 't', 'time', 'tGlobal', 'VAR', 'totalFrames', 'Math', ...forbiddenKeys, `with(p) { ${setupCode} }`);
+        const wrappedDraw = new Function('p', 'frameCount', 't', 'time', 'tGlobal', 'VAR', 'totalFrames', 'Math', ...forbiddenKeys, `with(p) { ${drawCode} }`);
+        // Get forbidden values array for execution
+        const forbiddenValues = forbiddenKeys.map(k => FORBIDDEN_APIS[k]);
         onProgress?.({
             phase: 'setup',
             percent: 10,
             message: 'Executing setup()...',
         });
-        // Execute setup() once with time = 0, VAR, and totalFrames
-        wrappedSetup(p, 0, 0, 0, 0, p.VAR, totalFrames);
+        // Execute setup() once with time = 0, VAR, totalFrames, and sandboxed context
+        wrappedSetup(p, 0, 0, 0, 0, p.VAR, totalFrames, safeMath, ...forbiddenValues);
         // Capture frames
         const frames = [];
         onProgress?.({
@@ -108,8 +118,8 @@ export async function runLoopMode(config, options) {
             // 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);
+            // Execute draw() with time variables, VAR, totalFrames, and sandboxed context
+            wrappedDraw(p, frame, t, time, t, p.VAR, totalFrames, safeMath, ...forbiddenValues);
             // 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');

package/dist/p5-runtime.d.ts

@@ -49,7 +49,8 @@ export interface P5Runtime {
 export interface P5RuntimeConfig {
     seed?: number;
 }
-export declare function createP5Runtime(canvas: HTMLCanvasElement, width: number, height: number, config?: P5RuntimeConfig): P5Runtime;
+type RuntimeCanvas = HTMLCanvasElement;
+export declare function createP5Runtime(canvas: RuntimeCanvas, width: number, height: number, config?: P5RuntimeConfig): P5Runtime;
 export declare function injectTimeVariables(p: P5Runtime, time: TimeVariables): void;
 /**
  * VAR Protocol Constants (Phase 1 — Protocol v1.0.0)
@@ -70,4 +71,5 @@ export declare const VAR_MAX = 100;
  */
 export declare function createProtocolVAR(vars?: number[]): readonly number[];
 export declare function injectProtocolVariables(p: P5Runtime, vars?: number[]): void;
+export {};
 //# sourceMappingURL=p5-runtime.d.ts.map

package/dist/p5-runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"p5-runtime.d.ts","sourceRoot":"","sources":["../p5-runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,UAAU,CAAC;AAClD,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAC1C,eAAO,MAAM,qBAAqB,EAAG,MAAe,CAAC;AAErD,MAAM,WAAW,SAAS;IACxB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAmED,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,eAAe,CAC7B,MAAM,EAAE,iBAAiB,EACzB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,eAAe,GACvB,SAAS,CAq8BX;AAED,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,aAAa,GAAG,IAAI,CAM3E;AAED;;;GAGG;AACH,eAAO,MAAM,SAAS,KAAK,CAAC;AAC5B,eAAO,MAAM,OAAO,IAAI,CAAC;AACzB,eAAO,MAAM,OAAO,MAAM,CAAC;AAE3B;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,MAAM,EAAE,CAmCpE;AAED,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAE3E"}
+{"version":3,"file":"p5-runtime.d.ts","sourceRoot":"","sources":["../p5-runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,UAAU,CAAC;AAClD,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAC1C,eAAO,MAAM,qBAAqB,EAAG,MAAe,CAAC;AAErD,MAAM,WAAW,SAAS;IACxB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAmED,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,KAAK,aAAa,GAAG,iBAAiB,CAAC;AAEvC,wBAAgB,eAAe,CAC7B,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,eAAe,GACvB,SAAS,CAs8BX;AAED,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,aAAa,GAAG,IAAI,CAM3E;AAED;;;GAGG;AACH,eAAO,MAAM,SAAS,KAAK,CAAC;AAC5B,eAAO,MAAM,OAAO,IAAI,CAAC;AACzB,eAAO,MAAM,OAAO,MAAM,CAAC;AAE3B;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,MAAM,EAAE,CAmCpE;AAED,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAE3E"}

package/dist/p5-runtime.js

@@ -93,6 +93,8 @@ function createSeededNoise(seed = 0) {
 }
 export function createP5Runtime(canvas, width, height, config) {
     const ctx = canvas.getContext('2d', { willReadFrequently: true });
+    if (!ctx)
+        throw new Error('Failed to get 2D context');
     let currentFill = 'rgba(255, 255, 255, 1)';
     let currentStroke = 'rgba(0, 0, 0, 1)';
     let strokeEnabled = true;

package/dist/static-engine.d.ts

@@ -7,6 +7,13 @@
  *
  * Determinism Guarantee:
  * Same code + same seed + same VARs = identical PNG output
+ *
+ * Security:
+ * All external entropy sources are blocked at runtime via execution sandbox.
+ *
+ * Oracle Support:
+ * When returnImageData is true, returns raw ImageData for determinism hashing.
+ * Works in both browser (HTMLCanvasElement) and Node (canvas package) environments.
  */
 import type { EngineConfig, RunOptions } from './types';
 export declare function runStaticMode(config: EngineConfig, options: RunOptions): Promise<void>;

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

@@ -1 +1 @@
-{"version":3,"file":"static-engine.d.ts","sourceRoot":"","sources":["../static-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAgB,MAAM,SAAS,CAAC;AAItE,wBAAsB,aAAa,CACjC,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,UAAU,GAClB,OAAO,CAAC,IAAI,CAAC,CAmGf"}
+{"version":3,"file":"static-engine.d.ts","sourceRoot":"","sources":["../static-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAgB,MAAM,SAAS,CAAC;AAoCtE,wBAAsB,aAAa,CACjC,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,UAAU,GAClB,OAAO,CAAC,IAAI,CAAC,CA6Hf"}

package/dist/static-engine.js

@@ -7,11 +7,44 @@
  *
  * Determinism Guarantee:
  * Same code + same seed + same VARs = identical PNG output
+ *
+ * Security:
+ * All external entropy sources are blocked at runtime via execution sandbox.
+ *
+ * Oracle Support:
+ * When returnImageData is true, returns raw ImageData for determinism hashing.
+ * Works in both browser (HTMLCanvasElement) and Node (canvas package) environments.
  */
+import { createRequire } from 'module';
 import { DEFAULT_CONFIG } from './types';
 import { createP5Runtime, injectTimeVariables, injectProtocolVariables } from './p5-runtime';
+import { FORBIDDEN_APIS, createSafeMath } from './execution-sandbox';
+const require = createRequire(import.meta.url);
+/**
+ * Create a runtime canvas that works in both browser and Node environments.
+ * Browser: uses HTMLCanvasElement
+ * Node/Headless: uses `canvas` npm package
+ */
+function createRuntimeCanvas(width, height) {
+    // Browser environment
+    if (typeof document !== 'undefined' && typeof document.createElement === 'function') {
+        const canvas = document.createElement('canvas');
+        canvas.width = width;
+        canvas.height = height;
+        return canvas;
+    }
+    // Node / headless environment (oracle, CI)
+    try {
+        const { createCanvas } = require('canvas');
+        return createCanvas(width, height);
+    }
+    catch (err) {
+        throw new Error('[Code Mode Protocol Error] Headless canvas unavailable. ' +
+            'Install `canvas` for oracle execution.');
+    }
+}
 export async function runStaticMode(config, options) {
-    const { code, seed, vars, onPreview, onProgress, onComplete, onError } = options;
+    const { code, seed, vars, onPreview, onProgress, onComplete, onError, returnImageData } = options;
     const width = config.width ?? DEFAULT_CONFIG.width;
     const height = config.height ?? DEFAULT_CONFIG.height;
     try {
@@ -20,10 +53,8 @@ export async function runStaticMode(config, options) {
             percent: 0,
             message: 'Initializing canvas...',
         });
-        // Create offscreen canvas
-        const canvas = document.createElement('canvas');
-        canvas.width = width;
-        canvas.height = height;
+        // Create runtime canvas (browser or Node)
+        const canvas = createRuntimeCanvas(width, height);
         // Create p5 runtime with optional seed for determinism
         const p = createP5Runtime(canvas, width, height, { seed });
         // Inject time variables (static = frame 0, t = 0, totalFrames = 1)
@@ -56,18 +87,43 @@ export async function runStaticMode(config, options) {
             percent: 30,
             message: 'Executing setup()...',
         });
-        // Create wrapped setup function with p5 context and VAR
-        const wrappedSetup = new Function('p', 'frameCount', 't', 'time', 'tGlobal', 'VAR', `with(p) { ${setupCode} }`);
-        // Execute setup() only
-        wrappedSetup(p, 0, 0, 0, 0, p.VAR);
+        // Create sandboxed execution context
+        // All forbidden APIs are injected as parameters to override globals
+        const safeMath = createSafeMath();
+        const forbiddenKeys = Object.keys(FORBIDDEN_APIS);
+        // Create wrapped setup function with p5 context, VAR, and blocked globals
+        const wrappedSetup = new Function('p', 'frameCount', 't', 'time', 'tGlobal', 'VAR', 'Math', ...forbiddenKeys, `with(p) { ${setupCode} }`);
+        // Execute setup() only with sandboxed context
+        const forbiddenValues = forbiddenKeys.map(k => FORBIDDEN_APIS[k]);
+        wrappedSetup(p, 0, 0, 0, 0, p.VAR, safeMath, ...forbiddenValues);
         // Provide preview callback
         onPreview?.(canvas);
         onProgress?.({
             phase: 'encoding',
             percent: 70,
-            message: 'Capturing PNG...',
+            message: returnImageData ? 'Capturing ImageData...' : 'Capturing PNG...',
         });
-        // Capture as PNG
+        // Get 2D context for pixel access
+        const ctx = canvas.getContext('2d');
+        if (!ctx) {
+            throw new Error('Failed to acquire 2D context');
+        }
+        // Always capture pixel data first
+        const imageData = ctx.getImageData(0, 0, width, height);
+        // ORACLE / NODE PATH — MUST NOT TOUCH toBlob
+        if (returnImageData) {
+            onProgress?.({
+                phase: 'complete',
+                percent: 100,
+                message: 'Complete',
+            });
+            onComplete({
+                type: 'image',
+                imageData,
+            });
+            return; // Early return - never touch toBlob in oracle mode
+        }
+        // BROWSER / UI PATH ONLY
         const blob = await new Promise((resolve, reject) => {
             canvas.toBlob((b) => b ? resolve(b) : reject(new Error('Failed to capture PNG')), 'image/png');
         });
@@ -76,11 +132,10 @@ export async function runStaticMode(config, options) {
             percent: 100,
             message: 'Complete',
         });
-        const result = {
+        onComplete({
             type: 'image',
             blob,
-        };
-        onComplete(result);
+        });
     }
     catch (error) {
         const err = error instanceof Error ? error : new Error(String(error));

package/dist/types.d.ts

@@ -1,6 +1,6 @@
 /**
  * NexArt Code Mode Runtime SDK - Types
- * Version: 1.5.1 (Protocol v1.2.0)
+ * Version: 1.6.0 (Protocol v1.2.0)
  *
  * Type definitions for the Code Mode runtime engine.
  * This is the canonical type surface for @nexart/codemode-sdk.
@@ -17,6 +17,12 @@ export declare const PROTOCOL_IDENTITY: {
     readonly deterministic: true;
 };
 export type RenderMode = 'static' | 'loop';
+/**
+ * Runtime Canvas
+ * Abstraction for browser (HTMLCanvasElement) and Node (canvas package) environments.
+ * In Node, the `canvas` npm package provides an HTMLCanvasElement-compatible interface.
+ */
+export type RuntimeCanvas = HTMLCanvasElement;
 export interface EngineConfig {
     mode: RenderMode;
     width?: number;
@@ -24,20 +30,36 @@ export interface EngineConfig {
     duration?: number;
     fps?: number;
 }
-export interface RenderResult {
-    type: 'image' | 'video';
+/**
+ * Render Result (Discriminated Union)
+ *
+ * Static mode can return either:
+ * - blob: For display/download (PNG)
+ * - imageData: For oracle hashing (raw pixels)
+ *
+ * Video mode returns blob with frame/duration metadata.
+ */
+export type RenderResult = {
+    type: 'image';
+    blob: Blob;
+} | {
+    type: 'image';
+    imageData: ImageData;
+} | {
+    type: 'video';
     blob: Blob;
     frames?: number;
     duration?: number;
-}
+};
 export interface RunOptions {
     code: string;
     seed?: number;
     vars?: number[];
-    onPreview?: (canvas: HTMLCanvasElement) => void;
+    onPreview?: (canvas: RuntimeCanvas) => void;
     onProgress?: (progress: ProgressInfo) => void;
     onComplete: (result: RenderResult) => void;
     onError?: (error: Error) => void;
+    returnImageData?: boolean;
 }
 export interface ProgressInfo {
     phase: 'setup' | 'rendering' | 'encoding' | 'complete';
@@ -127,7 +149,7 @@ export interface ExecuteCodeModeResult {
     metadata: ProtocolMetadata;
 }
 /**
- * Builder Manifest (v1.5.1)
+ * Builder Manifest (v1.6.0)
  *
  * Passive, declarative metadata for builder attribution.
  * This is data-only with no logic, rewards, or enforcement attached.

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -1,6 +1,6 @@
 /**
  * NexArt Code Mode Runtime SDK - Types
- * Version: 1.5.1 (Protocol v1.2.0)
+ * Version: 1.6.0 (Protocol v1.2.0)
  *
  * Type definitions for the Code Mode runtime engine.
  * This is the canonical type surface for @nexart/codemode-sdk.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nexart/codemode-sdk",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "description": "NexArt Code Mode SDK - Canonical execution engine for deterministic generative art",
   "type": "module",
   "main": "./dist/core-index.js",
@@ -15,7 +15,9 @@
     "dist",
     "README.md",
     "CHANGELOG.md",
-    "CODE_MODE_PROTOCOL.md"
+    "CODE_MODE_PROTOCOL.md",
+    "LICENSE.md",
+    "builder.manifest.schema.json"
   ],
   "scripts": {
     "build": "tsc",