@nexart/codemode-sdk 1.8.0 → 1.8.2

package/dist/static-engine.js

@@ -1,157 +0,0 @@
-/**
- * NexArt Code Mode Runtime SDK - Static Engine
- * Protocol: v1.2.0 (Phase 3) — HARD ENFORCEMENT
- *
- * Static mode renderer: executes setup() only, captures single PNG.
- * Does NOT execute draw() - per NexArt Execution Specification v1.
- *
- * 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 { DEFAULT_CONFIG } from './types';
-import { createP5Runtime, injectTimeVariables, injectProtocolVariables } from './p5-runtime';
-import { FORBIDDEN_APIS, createSafeMath } from './execution-sandbox';
-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
- */
-async 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)
-    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;
-    const width = config.width ?? DEFAULT_CONFIG.width;
-    const height = config.height ?? DEFAULT_CONFIG.height;
-    try {
-        onProgress?.({
-            phase: 'setup',
-            percent: 0,
-            message: 'Initializing canvas...',
-        });
-        // Create runtime canvas (browser or Node)
-        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)
-        injectTimeVariables(p, {
-            frameCount: 0,
-            t: 0,
-            time: 0,
-            tGlobal: 0,
-            totalFrames: 1, // Static mode has 1 frame
-        });
-        // Inject protocol variables (VAR[0..9])
-        injectProtocolVariables(p, vars);
-        onProgress?.({
-            phase: 'setup',
-            percent: 10,
-            message: 'Parsing code...',
-        });
-        // Extract setup() function only - draw() is NOT executed in Static Mode
-        const setupMatch = code.match(/function\s+setup\s*\(\s*\)\s*\{([\s\S]*?)\}(?=\s*function|\s*$)/);
-        const setupCode = setupMatch ? setupMatch[1].trim() : code;
-        // Validate - no forbidden patterns
-        const forbiddenPatterns = ['setTimeout', 'setInterval', 'requestAnimationFrame'];
-        for (const pattern of forbiddenPatterns) {
-            if (code.includes(pattern)) {
-                throw new Error(`Forbidden async timing function: ${pattern}`);
-            }
-        }
-        onProgress?.({
-            phase: 'rendering',
-            percent: 30,
-            message: 'Executing setup()...',
-        });
-        // 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: returnImageData ? 'Capturing ImageData...' : 'Capturing 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');
-        });
-        onProgress?.({
-            phase: 'complete',
-            percent: 100,
-            message: 'Complete',
-        });
-        onComplete({
-            type: 'image',
-            blob,
-        });
-    }
-    catch (error) {
-        const err = error instanceof Error ? error : new Error(String(error));
-        onError?.(err);
-    }
-}

package/dist/types.d.ts

@@ -1,191 +0,0 @@
-/**
- * NexArt Code Mode Runtime SDK - Types
- * 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.
- */
-/**
- * Protocol Constants
- * These define the locked protocol identity.
- */
-export declare const PROTOCOL_IDENTITY: {
-    readonly protocol: "nexart";
-    readonly engine: "codemode";
-    readonly protocolVersion: "1.2.0";
-    readonly phase: 3;
-    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;
-    height?: number;
-    duration?: number;
-    fps?: number;
-}
-/**
- * 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: RuntimeCanvas) => void;
-    onProgress?: (progress: ProgressInfo) => void;
-    onComplete: (result: RenderResult) => void;
-    onError?: (error: Error) => void;
-    returnImageData?: boolean;
-}
-export interface ProgressInfo {
-    phase: 'setup' | 'rendering' | 'encoding' | 'complete';
-    frame?: number;
-    totalFrames?: number;
-    percent: number;
-    message: string;
-}
-export interface Engine {
-    run: (options: RunOptions) => Promise<void>;
-    stop: () => void;
-    getConfig: () => Readonly<EngineConfig>;
-}
-export interface TimeVariables {
-    frameCount: number;
-    t: number;
-    time: number;
-    tGlobal: number;
-    totalFrames: number;
-}
-/**
- * Protocol Variables (VAR[0..9])
- * First-class protocol inputs for deterministic rendering.
- * Used by SoundArt, Shapes, Noise, and ByX collections.
- *
- * Rules (SDK v1.0.2, Protocol v1.0.0):
- * - Input array can have 0-10 elements (protocol error if > 10)
- * - All values MUST be finite numbers (protocol error if not)
- * - Values MUST be in range 0-100 (protocol error if out of range, NO clamping)
- * - Runtime VAR is ALWAYS 10 elements (padded with zeros for consistency)
- * - Read-only inside sketches (write attempts throw protocol error)
- * - Default: all zeros if not provided
- */
-export interface ProtocolVariables {
-    VAR: readonly [number, number, number, number, number, number, number, number, number, number];
-}
-/**
- * Default protocol variables (all zeros)
- */
-export declare const DEFAULT_VARS: ProtocolVariables;
-export declare const DEFAULT_CONFIG: {
-    readonly width: 1950;
-    readonly height: 2400;
-    readonly duration: 2;
-    readonly fps: 30;
-    readonly minDuration: 1;
-    readonly maxDuration: 4;
-};
-/**
- * Protocol Metadata
- * Attached to every execution result for verification.
- */
-export interface ProtocolMetadata {
-    protocol: 'nexart';
-    engine: 'codemode';
-    protocolVersion: '1.2.0';
-    phase: 3;
-    deterministic: true;
-    seed: number;
-    vars: number[];
-    width: number;
-    height: number;
-    mode: RenderMode;
-    totalFrames?: number;
-}
-/**
- * Canonical Execution Input
- * The single entry point for all Code Mode execution.
- */
-export interface ExecuteCodeModeInput {
-    source: string;
-    width: number;
-    height: number;
-    seed: number;
-    vars?: number[];
-    mode: RenderMode;
-    totalFrames?: number;
-}
-/**
- * Canonical Execution Result
- * Every execution produces this structure.
- */
-export interface ExecuteCodeModeResult {
-    image?: Blob;
-    video?: Blob;
-    frames?: ImageData[];
-    metadata: ProtocolMetadata;
-}
-/**
- * Builder Manifest (v1.6.0)
- *
- * Passive, declarative metadata for builder attribution.
- * This is data-only with no logic, rewards, or enforcement attached.
- *
- * Rules:
- * - Registration is optional
- * - Missing or invalid manifest does NOT throw
- * - No network calls, no telemetry, no analytics
- * - Does NOT affect execution behavior or determinism
- * - Used for future attribution and ecosystem discovery
- */
-export interface NexArtBuilderManifest {
-    protocol: 'nexart';
-    manifestVersion: string;
-    app?: {
-        name?: string;
-        url?: string;
-        description?: string;
-        contact?: string;
-    };
-    sdk?: {
-        package?: string;
-        version?: string;
-        execution?: string;
-    };
-    renderer?: {
-        package?: string;
-        version?: string;
-        mode?: 'preview' | 'canonical';
-    };
-    features?: Record<string, boolean>;
-    declaration?: {
-        usesOfficialSdk?: boolean;
-        noRuntimeModification?: boolean;
-        noProtocolBypass?: boolean;
-    };
-    timestamp?: string;
-}
-//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;GAGG;AACH,eAAO,MAAM,iBAAiB;;;;;;CAMpB,CAAC;AAEX,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE3C;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,iBAAiB,CAAC;AAE9C,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,UAAU,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GACpB;IACE,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,IAAI,CAAC;CACZ,GACD;IACE,IAAI,EAAE,OAAO,CAAC;IACd,SAAS,EAAE,SAAS,CAAC;CACtB,GACD;IACE,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,IAAI,CAAC;IACX,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEN,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,IAAI,CAAC;IAC5C,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,YAAY,KAAK,IAAI,CAAC;IAC9C,UAAU,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,CAAC;IAC3C,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACjC,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,OAAO,GAAG,WAAW,GAAG,UAAU,GAAG,UAAU,CAAC;IACvD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,MAAM;IACrB,GAAG,EAAE,CAAC,OAAO,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,SAAS,EAAE,MAAM,QAAQ,CAAC,YAAY,CAAC,CAAC;CACzC;AAED,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,CAAC,EAAE,MAAM,CAAC;IACV,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;CAChG;AAED;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,iBAE1B,CAAC;AAEF,eAAO,MAAM,cAAc;;;;;;;CAOjB,CAAC;AAEX;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,QAAQ,CAAC;IACnB,MAAM,EAAE,UAAU,CAAC;IACnB,eAAe,EAAE,OAAO,CAAC;IACzB,KAAK,EAAE,CAAC,CAAC;IACT,aAAa,EAAE,IAAI,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,UAAU,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,IAAI,EAAE,UAAU,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,KAAK,CAAC,EAAE,IAAI,CAAC;IACb,KAAK,CAAC,EAAE,IAAI,CAAC;IACb,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC;IACrB,QAAQ,EAAE,gBAAgB,CAAC;CAC5B;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,QAAQ,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,GAAG,CAAC,EAAE;QACJ,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;IACF,GAAG,CAAC,EAAE;QACJ,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,CAAC;IACF,QAAQ,CAAC,EAAE;QACT,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,IAAI,CAAC,EAAE,SAAS,GAAG,WAAW,CAAC;KAChC,CAAC;IACF,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,WAAW,CAAC,EAAE;QACZ,eAAe,CAAC,EAAE,OAAO,CAAC;QAC1B,qBAAqB,CAAC,EAAE,OAAO,CAAC;QAChC,gBAAgB,CAAC,EAAE,OAAO,CAAC;KAC5B,CAAC;IACF,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB"}

package/dist/types.js

@@ -1,32 +0,0 @@
-/**
- * NexArt Code Mode Runtime SDK - Types
- * 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.
- */
-/**
- * Protocol Constants
- * These define the locked protocol identity.
- */
-export const PROTOCOL_IDENTITY = {
-    protocol: 'nexart',
-    engine: 'codemode',
-    protocolVersion: '1.2.0',
-    phase: 3,
-    deterministic: true,
-};
-/**
- * Default protocol variables (all zeros)
- */
-export const DEFAULT_VARS = {
-    VAR: Object.freeze([0, 0, 0, 0, 0, 0, 0, 0, 0, 0])
-};
-export const DEFAULT_CONFIG = {
-    width: 1950,
-    height: 2400,
-    duration: 2,
-    fps: 30,
-    minDuration: 1,
-    maxDuration: 4,
-};