@nexart/codemode-sdk 1.8.1 → 1.8.3

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

@@ -1 +1 @@
-{"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"}
+{"version":3,"file":"static-engine.d.ts","sourceRoot":"","sources":["../../../static-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAgB,MAAM,SAAS,CAAC;AAkDtE,wBAAsB,aAAa,CACjC,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,UAAU,GAClB,OAAO,CAAC,IAAI,CAAC,CA6Hf"}

package/dist/sdk/codemode/static-engine.js

@@ -15,17 +15,32 @@
  * 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);
+let nodeCanvasModule = null;
+async function getNodeCanvas() {
+    if (nodeCanvasModule)
+        return nodeCanvasModule;
+    if (typeof window === 'undefined') {
+        try {
+            const { createRequire } = await import('module');
+            const require = createRequire(import.meta.url);
+            nodeCanvasModule = require('canvas');
+            return nodeCanvasModule;
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
 /**
  * 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) {
+async function createRuntimeCanvas(width, height) {
     // Browser environment
     if (typeof document !== 'undefined' && typeof document.createElement === 'function') {
         const canvas = document.createElement('canvas');
@@ -34,14 +49,12 @@ function createRuntimeCanvas(width, 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.');
+    const nodeCanvas = await getNodeCanvas();
+    if (nodeCanvas && nodeCanvas.createCanvas) {
+        return nodeCanvas.createCanvas(width, height);
     }
+    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, returnImageData } = options;
@@ -54,7 +67,7 @@ export async function runStaticMode(config, options) {
             message: 'Initializing canvas...',
         });
         // Create runtime canvas (browser or Node)
-        const canvas = createRuntimeCanvas(width, height);
+        const canvas = await 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)

package/dist/sdk/codemode/types.d.ts

@@ -1,6 +1,6 @@
 /**
  * NexArt Code Mode Runtime SDK - Types
- * Version: 1.6.0 (Protocol v1.2.0)
+ * See version.ts for SDK version (single source of truth)
  *
  * Type definitions for the Code Mode runtime engine.
  * This is the canonical type surface for @nexart/codemode-sdk.
@@ -8,6 +8,7 @@
 /**
  * Protocol Constants
  * These define the locked protocol identity.
+ * Imports from version.ts (single source of truth).
  */
 export declare const PROTOCOL_IDENTITY: {
     readonly protocol: "nexart";

package/dist/sdk/codemode/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/sdk/codemode/types.js

@@ -1,19 +1,21 @@
 /**
  * NexArt Code Mode Runtime SDK - Types
- * Version: 1.6.0 (Protocol v1.2.0)
+ * See version.ts for SDK version (single source of truth)
  *
  * Type definitions for the Code Mode runtime engine.
  * This is the canonical type surface for @nexart/codemode-sdk.
  */
+import { PROTOCOL_VERSION, PROTOCOL_PHASE } from './version';
 /**
  * Protocol Constants
  * These define the locked protocol identity.
+ * Imports from version.ts (single source of truth).
  */
 export const PROTOCOL_IDENTITY = {
     protocol: 'nexart',
     engine: 'codemode',
-    protocolVersion: '1.2.0',
-    phase: 3,
+    protocolVersion: PROTOCOL_VERSION,
+    phase: PROTOCOL_PHASE,
     deterministic: true,
 };
 /**

package/dist/sdk/codemode/version.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @nexart/codemode-sdk — Single Source of Truth for Version Constants
+ *
+ * All version exports across the SDK MUST import from this module.
+ * This prevents version drift between package.json, runtime exports, and documentation.
+ *
+ * To update: Change values here and run `npm run build`.
+ * See package.json for the canonical npm version.
+ */
+/** SDK version - must match package.json version */
+export declare const SDK_VERSION = "1.8.3";
+/** Protocol version - defines runtime semantics and determinism guarantees */
+export declare const PROTOCOL_VERSION = "1.2.0";
+/** Protocol phase - phase 3 = stable, production-ready */
+export declare const PROTOCOL_PHASE = 3;
+/** Combined version string for display */
+export declare const VERSION_STRING = "v1.8.3 (Protocol v1.2.0)";
+//# sourceMappingURL=version.d.ts.map

package/dist/sdk/codemode/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../../version.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,oDAAoD;AACpD,eAAO,MAAM,WAAW,UAAU,CAAC;AAEnC,8EAA8E;AAC9E,eAAO,MAAM,gBAAgB,UAAU,CAAC;AAExC,0DAA0D;AAC1D,eAAO,MAAM,cAAc,IAAI,CAAC;AAEhC,0CAA0C;AAC1C,eAAO,MAAM,cAAc,6BAAoD,CAAC"}

package/dist/sdk/codemode/version.js

@@ -0,0 +1,17 @@
+/**
+ * @nexart/codemode-sdk — Single Source of Truth for Version Constants
+ *
+ * All version exports across the SDK MUST import from this module.
+ * This prevents version drift between package.json, runtime exports, and documentation.
+ *
+ * To update: Change values here and run `npm run build`.
+ * See package.json for the canonical npm version.
+ */
+/** SDK version - must match package.json version */
+export const SDK_VERSION = '1.8.3';
+/** Protocol version - defines runtime semantics and determinism guarantees */
+export const PROTOCOL_VERSION = '1.2.0';
+/** Protocol phase - phase 3 = stable, production-ready */
+export const PROTOCOL_PHASE = 3;
+/** Combined version string for display */
+export const VERSION_STRING = `v${SDK_VERSION} (Protocol v${PROTOCOL_VERSION})`;

package/examples/agent-quickstart.ts

@@ -0,0 +1,159 @@
+/**
+ * @nexart/codemode-sdk — Agent Quickstart Example
+ * See package.json for SDK version
+ * 
+ * This example demonstrates the RECOMMENDED approach for AI coding agents.
+ * 
+ * Key principles:
+ * - Use createRuntime() — the modern, agent-first API
+ * - Always use strict: true to catch determinism violations
+ * - Never use Math.random(), Date.now(), or other non-deterministic APIs
+ * - Use runtime.random(), runtime.noise() for all randomness
+ * - Use runtime.digest() for verification
+ * 
+ * This example requires NO canvas, NO p5, and is browser-safe.
+ */
+
+import { createRuntime } from "../entry/browser";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// STEP 1: Create a deterministic runtime
+// ─────────────────────────────────────────────────────────────────────────────
+
+const runtime = createRuntime({
+  seed: "agent-quickstart-demo",  // Any string or number
+  vars: [50, 75, 25, 0, 0, 0, 0, 0, 0, 0],  // VAR[0..9] inputs (0-100 each)
+  strict: true,  // ALWAYS use strict: true — throws on non-deterministic APIs
+  mode: "static",  // "static" = single frame, "loop" = animation
+  metadata: { example: "agent-quickstart" }  // Optional metadata for digest
+});
+
+console.log("=== Agent Quickstart Example ===\n");
+
+// ─────────────────────────────────────────────────────────────────────────────
+// STEP 2: Use deterministic APIs
+// ─────────────────────────────────────────────────────────────────────────────
+
+// Deterministic random values (Mulberry32 PRNG)
+const randomValues = [
+  runtime.random(),           // [0, 1) — deterministic float
+  runtime.random(),           // Next value in sequence
+  runtime.randomInt(0, 100),  // Deterministic integer in range [0, 100]
+  runtime.randomInt(1, 6),    // Like rolling a die
+  runtime.randomRange(10, 20) // Deterministic float in range [10, 20]
+];
+
+console.log("Deterministic random values:");
+randomValues.forEach((val, i) => console.log(`  [${i}] ${val}`));
+console.log();
+
+// Deterministic noise (Perlin)
+const noiseValues = [
+  runtime.noise(0.1, 0.2),    // 2D Perlin noise
+  runtime.noise(0.5, 0.5),    // Different position
+  runtime.noise(1.0, 2.0, 3.0) // 3D Perlin noise
+];
+
+console.log("Deterministic noise values:");
+noiseValues.forEach((val, i) => console.log(`  [${i}] ${val}`));
+console.log();
+
+// ─────────────────────────────────────────────────────────────────────────────
+// STEP 3: Execute code with strict enforcement
+// ─────────────────────────────────────────────────────────────────────────────
+
+// runtime.run() executes code with strict mode enforcement
+// If any non-deterministic API is called, it throws an actionable error
+const result = runtime.run(() => {
+  // This code is safe — uses only deterministic APIs
+  const positions: Array<{x: number, y: number}> = [];
+  for (let i = 0; i < 5; i++) {
+    positions.push({
+      x: runtime.random() * 100,
+      y: runtime.random() * 100
+    });
+  }
+  return positions;
+});
+
+console.log("Generated positions (deterministic):");
+result.forEach((pos, i) => console.log(`  [${i}] x=${pos.x.toFixed(2)}, y=${pos.y.toFixed(2)}`));
+console.log();
+
+// ─────────────────────────────────────────────────────────────────────────────
+// STEP 4: Get state snapshot and digest for verification
+// ─────────────────────────────────────────────────────────────────────────────
+
+const state = runtime.getState();
+const digest = runtime.digest();
+
+console.log("State snapshot:");
+console.log(`  sdkVersion: "${state.sdkVersion}"`);
+console.log(`  seed: ${state.seed}`);
+console.log(`  vars: [${state.vars.join(", ")}]`);
+console.log(`  mode: "${state.mode}"`);
+console.log();
+
+console.log("Verification digest:");
+console.log(`  ${digest}`);
+console.log();
+
+// ─────────────────────────────────────────────────────────────────────────────
+// STEP 5: Verify determinism (same inputs → same outputs)
+// ─────────────────────────────────────────────────────────────────────────────
+
+// Create a second runtime with identical inputs
+const runtime2 = createRuntime({
+  seed: "agent-quickstart-demo",
+  vars: [50, 75, 25, 0, 0, 0, 0, 0, 0, 0],
+  strict: true,
+  mode: "static",
+  metadata: { example: "agent-quickstart" }
+});
+
+// Generate the same sequence
+for (let i = 0; i < randomValues.length; i++) {
+  if (i < 2) runtime2.random();
+  else if (i === 2) runtime2.randomInt(0, 100);
+  else if (i === 3) runtime2.randomInt(1, 6);
+  else runtime2.randomRange(10, 20);
+}
+
+// Generate the same noise values
+runtime2.noise(0.1, 0.2);
+runtime2.noise(0.5, 0.5);
+runtime2.noise(1.0, 2.0, 3.0);
+
+// Run the same code
+runtime2.run(() => {
+  for (let i = 0; i < 5; i++) {
+    runtime2.random();
+    runtime2.random();
+  }
+});
+
+const digest2 = runtime2.digest();
+
+console.log("Determinism verification:");
+console.log(`  Runtime 1 digest: ${digest}`);
+console.log(`  Runtime 2 digest: ${digest2}`);
+console.log(`  Match: ${digest === digest2 ? "✅ PASS" : "❌ FAIL"}`);
+console.log();
+
+// ─────────────────────────────────────────────────────────────────────────────
+// WHAT NOT TO DO — These would throw in strict mode:
+// ─────────────────────────────────────────────────────────────────────────────
+
+console.log("=== Common Mistakes (DO NOT DO THIS) ===\n");
+console.log("❌ Math.random()     → Use runtime.random()");
+console.log("❌ Date.now()        → Pass time as input or use frame counters");
+console.log("❌ performance.now() → Use deterministic timing");
+console.log("❌ new Date()        → Pass time as input");
+console.log();
+
+// Example of what strict mode catches:
+// runtime.run(() => {
+//   Math.random();  // Throws: NEXART_STRICT: Non-deterministic API used: Math.random. Use runtime.random() instead.
+// });
+
+console.log("=== Example Complete ===");

package/examples/preflight-test.ts

@@ -1,7 +1,7 @@
 /**
  * @nexart/codemode-sdk — Preflight Release Tests
  * 
- * Extended verification tests for v1.8.0 release validation.
+ * Extended verification tests for v1.8.3 release validation.
  * Tests strict mode restoration, error messages, and cross-env digest parity.
  * 
  * Run: npx tsx examples/preflight-test.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nexart/codemode-sdk",
-  "version": "1.8.1",
+  "version": "1.8.3",
   "description": "NexArt Code Mode SDK - Deterministic, reproducible, verifiable generative art runtime. Agent-first design for AI coding assistants.",
   "type": "module",
   "main": "./dist/entry/browser.js",
@@ -48,6 +48,7 @@
     "test": "npx tsx smoke-test.ts",
     "example:basic": "npx tsx examples/basic.ts",
     "example:verify": "npx tsx examples/verify.ts",
+    "example:agent": "npx tsx examples/agent-quickstart.ts",
     "prepublishOnly": "npm run build && npm run test"
   },
   "keywords": [

package/dist/builder-manifest.d.ts

@@ -1,79 +0,0 @@
-/**
- * NexArt Code Mode SDK - Builder Manifest
- * Version: 1.6.0 (Protocol v1.2.0)
- *
- * ╔══════════════════════════════════════════════════════════════════════════╗
- * ║  BUILDER MANIFEST — PASSIVE ATTRIBUTION (WRITE-ONLY)                     ║
- * ║                                                                          ║
- * ║  The Builder Manifest is a declaration of intent, not a capability.      ║
- * ║  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)                          ║
- * ║                                                                          ║
- * ║  There is:                                                               ║
- * ║    - No SDK API to read manifests                                        ║
- * ║    - No validation                                                       ║
- * ║    - No attribution logic                                                ║
- * ║    - No tracking, analytics, or network calls                            ║
- * ║                                                                          ║
- * ║  Execution behavior is identical with or without a manifest.             ║
- * ╚══════════════════════════════════════════════════════════════════════════╝
- */
-import type { NexArtBuilderManifest } from './types';
-/**
- * Register a builder manifest for attribution.
- *
- * This is optional and does not affect execution behavior.
- * The manifest is stored in-memory only and is not:
- * - Serialized to disk
- * - Sent over the network
- * - Logged to console
- * - Used for validation or enforcement
- *
- * @param manifest - Optional builder manifest. Pass undefined to clear.
- *
- * @example
- * ```typescript
- * import { registerBuilderManifest } from "@nexart/codemode-sdk";
- *
- * registerBuilderManifest({
- *   protocol: "nexart",
- *   manifestVersion: "0.1",
- *   app: { name: "My App", url: "https://myapp.com" }
- * });
- * ```
- */
-export declare function registerBuilderManifest(manifest?: NexArtBuilderManifest): void;
-/**
- * Get the currently registered builder manifest.
- *
- * ╔══════════════════════════════════════════════════════════════════════════╗
- * ║  INTERNAL FUNCTION — NOT EXPORTED TO SDK CONSUMERS                       ║
- * ║                                                                          ║
- * ║  This function exists only for internal SDK execution context.           ║
- * ║  It is NOT part of the public API and must NOT be exported from index.   ║
- * ║  Runtime code and sketch code cannot access this function.               ║
- * ╚══════════════════════════════════════════════════════════════════════════╝
- *
- * @internal
- */
-export declare function getBuilderManifest(): NexArtBuilderManifest | null;
-/**
- * Clear the registered builder manifest.
- *
- * ╔══════════════════════════════════════════════════════════════════════════╗
- * ║  INTERNAL FUNCTION — NOT EXPORTED TO SDK CONSUMERS                       ║
- * ║                                                                          ║
- * ║  This function exists only for internal SDK execution context.           ║
- * ║  It is NOT part of the public API and must NOT be exported from index.   ║
- * ║  Runtime code and sketch code cannot access this function.               ║
- * ╚══════════════════════════════════════════════════════════════════════════╝
- *
- * @internal
- */
-export declare function clearBuilderManifest(): void;
-//# sourceMappingURL=builder-manifest.d.ts.map

package/dist/builder-manifest.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"builder-manifest.d.ts","sourceRoot":"","sources":["../builder-manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAKrD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,CAAC,EAAE,qBAAqB,GAAG,IAAI,CAiB9E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,IAAI,qBAAqB,GAAG,IAAI,CAEjE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C"}

package/dist/builder-manifest.js

@@ -1,97 +0,0 @@
-/**
- * NexArt Code Mode SDK - Builder Manifest
- * Version: 1.6.0 (Protocol v1.2.0)
- *
- * ╔══════════════════════════════════════════════════════════════════════════╗
- * ║  BUILDER MANIFEST — PASSIVE ATTRIBUTION (WRITE-ONLY)                     ║
- * ║                                                                          ║
- * ║  The Builder Manifest is a declaration of intent, not a capability.      ║
- * ║  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)                          ║
- * ║                                                                          ║
- * ║  There is:                                                               ║
- * ║    - No SDK API to read manifests                                        ║
- * ║    - No validation                                                       ║
- * ║    - No attribution logic                                                ║
- * ║    - No tracking, analytics, or network calls                            ║
- * ║                                                                          ║
- * ║  Execution behavior is identical with or without a manifest.             ║
- * ╚══════════════════════════════════════════════════════════════════════════╝
- */
-/** Internal storage - not accessible to SDK consumers */
-let currentManifest = null;
-/**
- * Register a builder manifest for attribution.
- *
- * This is optional and does not affect execution behavior.
- * The manifest is stored in-memory only and is not:
- * - Serialized to disk
- * - Sent over the network
- * - Logged to console
- * - Used for validation or enforcement
- *
- * @param manifest - Optional builder manifest. Pass undefined to clear.
- *
- * @example
- * ```typescript
- * import { registerBuilderManifest } from "@nexart/codemode-sdk";
- *
- * registerBuilderManifest({
- *   protocol: "nexart",
- *   manifestVersion: "0.1",
- *   app: { name: "My App", url: "https://myapp.com" }
- * });
- * ```
- */
-export function registerBuilderManifest(manifest) {
-    if (!manifest) {
-        currentManifest = null;
-        return;
-    }
-    if (manifest.protocol !== 'nexart') {
-        currentManifest = null;
-        return;
-    }
-    if (typeof manifest.manifestVersion !== 'string') {
-        currentManifest = null;
-        return;
-    }
-    currentManifest = manifest;
-}
-/**
- * Get the currently registered builder manifest.
- *
- * ╔══════════════════════════════════════════════════════════════════════════╗
- * ║  INTERNAL FUNCTION — NOT EXPORTED TO SDK CONSUMERS                       ║
- * ║                                                                          ║
- * ║  This function exists only for internal SDK execution context.           ║
- * ║  It is NOT part of the public API and must NOT be exported from index.   ║
- * ║  Runtime code and sketch code cannot access this function.               ║
- * ╚══════════════════════════════════════════════════════════════════════════╝
- *
- * @internal
- */
-export function getBuilderManifest() {
-    return currentManifest;
-}
-/**
- * Clear the registered builder manifest.
- *
- * ╔══════════════════════════════════════════════════════════════════════════╗
- * ║  INTERNAL FUNCTION — NOT EXPORTED TO SDK CONSUMERS                       ║
- * ║                                                                          ║
- * ║  This function exists only for internal SDK execution context.           ║
- * ║  It is NOT part of the public API and must NOT be exported from index.   ║
- * ║  Runtime code and sketch code cannot access this function.               ║
- * ╚══════════════════════════════════════════════════════════════════════════╝
- *
- * @internal
- */
-export function clearBuilderManifest() {
-    currentManifest = null;
-}

package/dist/core-index.d.ts

@@ -1,21 +0,0 @@
-/**
- * @nexart/codemode-sdk v1.4.0 — Core Exports
- *
- * Canonical execution engine for NexArt Code Mode.
- * This is the single source of truth for Code Mode semantics.
- *
- * Protocol: v1.2.0 (Phase 3)
- * 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.8.0";
-export declare const SDK_NAME = "@nexart/codemode-sdk";
-//# sourceMappingURL=core-index.d.ts.map

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

@@ -1 +0,0 @@
-{"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

@@ -1,26 +0,0 @@
-/**
- * @nexart/codemode-sdk v1.4.0 — Core Exports
- *
- * Canonical execution engine for NexArt Code Mode.
- * This is the single source of truth for Code Mode semantics.
- *
- * Protocol: v1.2.0 (Phase 3)
- * 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.8.0';
-export const SDK_NAME = '@nexart/codemode-sdk';

package/dist/engine.d.ts

@@ -1,24 +0,0 @@
-/**
- * NexArt Code Mode Runtime SDK
- * Version: 0.1.0
- *
- * 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)
- *   });
- */
-import type { Engine, EngineConfig } from './types';
-/**
- * Create a NexArt Code Mode rendering engine.
- *
- * @param config - Engine configuration
- * @returns Engine instance
- */
-export declare function createEngine(config: EngineConfig): Engine;
-export type { Engine, EngineConfig, RunOptions, RenderResult, ProgressInfo } from './types';
-export { DEFAULT_CONFIG } from './types';
-//# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

@@ -1 +0,0 @@
-{"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"}