@nexart/ui-renderer 0.2.1 → 0.3.1

package/dist/preview/unified-renderer.js

@@ -0,0 +1,270 @@
+/**
+ * Unified Renderer - Handles background, primitive, and sketch elements
+ * Dispatches rendering per element type in order: background → primitive → sketch
+ * All elements render to the same canvas/context with shared timing
+ */
+import { compileBackgroundPreset, getPaletteColors } from '../presets/backgrounds';
+import { compilePrimitive } from '../presets/primitives';
+import { wrapSketch, validateSketchSafety } from '../presets/sketch-wrapper';
+import { createP5Runtime } from './code-renderer';
+function validateSketchElement(element) {
+    const { safe, warnings } = validateSketchSafety(element.code);
+    if (!safe) {
+        throw new Error(`Unsafe sketch code: ${warnings.join(', ')}`);
+    }
+    if (warnings.length > 0) {
+        console.warn('[SDK] Sketch warnings:', warnings);
+    }
+}
+function inferPalette(elements) {
+    for (const el of elements) {
+        if (el.type === 'background' && el.palette) {
+            return el.palette;
+        }
+    }
+    return 'offwhite-dark';
+}
+function extractFunctionBody(code, funcName) {
+    const pattern = new RegExp(`function\\s+${funcName}\\s*\\(\\s*\\)\\s*\\{`);
+    const match = code.match(pattern);
+    if (!match || match.index === undefined)
+        return '';
+    const startIndex = match.index + match[0].length;
+    let braceCount = 1;
+    let i = startIndex;
+    while (i < code.length && braceCount > 0) {
+        if (code[i] === '{')
+            braceCount++;
+        if (code[i] === '}')
+            braceCount--;
+        i++;
+    }
+    return code.slice(startIndex, i - 1).trim();
+}
+function extractDrawCode(code) {
+    const body = extractFunctionBody(code, 'draw');
+    return body || code.trim();
+}
+function extractSetupCode(code) {
+    return extractFunctionBody(code, 'setup');
+}
+function compileBackgroundElement(element, palette) {
+    const code = compileBackgroundPreset(element.preset, element.palette || palette, element.loop || { duration: 120 });
+    return {
+        setup: extractSetupCode(code),
+        draw: extractDrawCode(code),
+    };
+}
+function compilePrimitiveElement(element, foreground) {
+    const primitiveCode = compilePrimitive({
+        name: element.name,
+        count: element.count,
+        strokeWeight: element.strokeWeight,
+        motion: element.motion,
+        color: element.color,
+        opacity: element.opacity,
+    }, foreground);
+    return { setup: '', draw: primitiveCode };
+}
+function compileSketchElement(element) {
+    validateSketchElement(element);
+    const wrapped = wrapSketch({
+        code: element.code,
+        normalize: element.normalize !== false,
+    });
+    return {
+        setup: extractSetupCode(wrapped),
+        draw: extractDrawCode(wrapped),
+    };
+}
+export function renderUnifiedSystem(system, canvas, options = {}) {
+    const { showBadge = true, onPreview, onComplete, onError } = options;
+    canvas.width = system.width;
+    canvas.height = system.height;
+    const ctx = canvas.getContext('2d');
+    let animationId = null;
+    let isRunning = false;
+    let isDestroyed = false;
+    const palette = inferPalette(system.elements);
+    const colors = getPaletteColors(palette);
+    const totalFrames = system.loop?.duration ?? 120;
+    const sortedElements = [...system.elements].sort((a, b) => {
+        const order = { background: 0, primitive: 1, sketch: 2 };
+        return (order[a.type] ?? 3) - (order[b.type] ?? 3);
+    });
+    const backgroundElements = [];
+    const primitiveElements = [];
+    const sketchElements = [];
+    for (const element of sortedElements) {
+        switch (element.type) {
+            case 'background':
+                backgroundElements.push(compileBackgroundElement(element, palette));
+                break;
+            case 'primitive':
+                primitiveElements.push(compilePrimitiveElement(element, colors.foreground));
+                break;
+            case 'sketch':
+                sketchElements.push(compileSketchElement(element));
+                break;
+        }
+    }
+    const hasElements = system.elements.length > 0;
+    const hasRenderers = backgroundElements.length > 0 || primitiveElements.length > 0 || sketchElements.length > 0;
+    console.log('[UIRenderer] Compiled elements:', {
+        background: backgroundElements.length,
+        primitive: primitiveElements.length,
+        sketch: sketchElements.length,
+        backgroundDrawEmpty: backgroundElements.map(e => !e.draw.trim()),
+        primitiveDrawEmpty: primitiveElements.map(e => !e.draw.trim()),
+        sketchDrawEmpty: sketchElements.map(e => !e.draw.trim()),
+    });
+    if (hasElements && !hasRenderers) {
+        throw new Error('[UIRenderer] No renderers executed despite having elements');
+    }
+    const drawBadge = () => {
+        if (!showBadge)
+            return;
+        const text = '⚠️ Preview Renderer (Non-Canonical)';
+        ctx.font = '12px -apple-system, sans-serif';
+        const metrics = ctx.measureText(text);
+        const padding = 8;
+        const badgeWidth = metrics.width + padding * 2;
+        const badgeHeight = 24;
+        const x = system.width - badgeWidth - 10;
+        const y = 10;
+        ctx.fillStyle = 'rgba(255, 100, 100, 0.15)';
+        ctx.strokeStyle = 'rgba(255, 100, 100, 0.4)';
+        ctx.lineWidth = 1;
+        ctx.beginPath();
+        ctx.roundRect(x, y, badgeWidth, badgeHeight, 4);
+        ctx.fill();
+        ctx.stroke();
+        ctx.fillStyle = '#ff9999';
+        ctx.fillText(text, x + padding, y + 16);
+    };
+    const executeCode = (p, code, frame, t) => {
+        if (!code.trim())
+            return;
+        try {
+            const wrappedCode = new Function('p', 'frameCount', 't', 'time', 'tGlobal', `with(p) { ${code} }`);
+            wrappedCode(p, frame, t, t * (totalFrames / 30), t);
+        }
+        catch (err) {
+            console.error('[UIRenderer] Code execution error:', err);
+        }
+    };
+    const runSetup = (p) => {
+        let setupRan = false;
+        for (const el of backgroundElements) {
+            if (el.setup) {
+                executeCode(p, el.setup, 0, 0);
+                setupRan = true;
+            }
+        }
+        for (const el of primitiveElements) {
+            if (el.setup) {
+                executeCode(p, el.setup, 0, 0);
+                setupRan = true;
+            }
+        }
+        for (const el of sketchElements) {
+            if (el.setup) {
+                executeCode(p, el.setup, 0, 0);
+                setupRan = true;
+            }
+        }
+        if (!setupRan) {
+            p.strokeWeight(1.5);
+        }
+    };
+    const runDraw = (p, frame, t) => {
+        let elementsRendered = 0;
+        const hasBackground = backgroundElements.length > 0;
+        if (!hasBackground) {
+            p.background(colors.background);
+        }
+        for (const el of backgroundElements) {
+            if (el.draw) {
+                console.log('[UIRenderer] background rendered');
+                executeCode(p, el.draw, frame, t);
+                elementsRendered++;
+            }
+        }
+        for (const el of primitiveElements) {
+            if (el.draw) {
+                console.log('[UIRenderer] primitive rendered');
+                executeCode(p, el.draw, frame, t);
+                elementsRendered++;
+            }
+        }
+        for (const el of sketchElements) {
+            if (el.draw) {
+                console.log('[UIRenderer] sketch rendered');
+                executeCode(p, el.draw, frame, t);
+                elementsRendered++;
+            }
+        }
+        if (hasElements && elementsRendered === 0) {
+            throw new Error('[UIRenderer] Zero renderers executed in frame despite having elements');
+        }
+    };
+    const renderLoop = () => {
+        if (isDestroyed)
+            return;
+        try {
+            let frame = 0;
+            const p = createP5Runtime(canvas, system.width, system.height, system.seed);
+            runSetup(p);
+            const loop = () => {
+                if (!isRunning || isDestroyed)
+                    return;
+                const t = frame / totalFrames;
+                p.randomSeed(system.seed);
+                p.noiseSeed(system.seed);
+                runDraw(p, frame, t);
+                drawBadge();
+                frame = (frame + 1) % totalFrames;
+                animationId = requestAnimationFrame(loop);
+            };
+            isRunning = true;
+            animationId = requestAnimationFrame(loop);
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            onError?.(err);
+            throw err;
+        }
+    };
+    const render = () => {
+        if (isDestroyed)
+            return;
+        renderLoop();
+    };
+    const start = () => {
+        if (isDestroyed)
+            return;
+        stop();
+        renderLoop();
+    };
+    const stop = () => {
+        isRunning = false;
+        if (animationId !== null) {
+            cancelAnimationFrame(animationId);
+            animationId = null;
+        }
+    };
+    const destroy = () => {
+        isDestroyed = true;
+        stop();
+        ctx.clearRect(0, 0, system.width, system.height);
+    };
+    const renderer = {
+        render,
+        start,
+        stop,
+        destroy,
+        isCanonical: false,
+        isArchival: false,
+    };
+    return renderer;
+}

package/dist/system.d.ts

@@ -1,9 +1,13 @@
 /**
- * @nexart/ui-renderer v0.2.0 - System Creation & Validation
+ * @nexart/ui-renderer v0.4.0 - System Creation & Validation
  *
- * Declarative system authoring for NexArt Protocol.
+ * Opinionated generative design system with aesthetic guardrails.
+ * Supports background, primitive, and sketch element types.
  */
-import type { NexArtSystemInput, NexArtSystem, ValidationResult } from './types';
+import type { NexArtSystemInput, NexArtSystem, DeclarativeSystem, NexArtCodeSystem, UnifiedSystem, ValidationResult } from './types';
 export declare function validateSystem(input: NexArtSystemInput): ValidationResult;
 export declare function createSystem(input: NexArtSystemInput): NexArtSystem;
+export declare function isCodeModeSystem(system: NexArtSystem): system is NexArtCodeSystem;
+export declare function isUnifiedModeSystem(system: NexArtSystem): system is UnifiedSystem;
+export declare function isDeclarativeSystem(system: NexArtSystem): system is DeclarativeSystem;
 //# sourceMappingURL=system.d.ts.map

package/dist/system.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"system.d.ts","sourceRoot":"","sources":["../src/system.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,iBAAiB,EACjB,YAAY,EAEZ,gBAAgB,EAGjB,MAAM,SAAS,CAAC;AAoIjB,wBAAgB,cAAc,CAAC,KAAK,EAAE,iBAAiB,GAAG,gBAAgB,CA6BzE;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,YAAY,CA0BnE"}
+{"version":3,"file":"system.d.ts","sourceRoot":"","sources":["../src/system.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,iBAAiB,EACjB,YAAY,EAEZ,iBAAiB,EAEjB,gBAAgB,EAEhB,aAAa,EAGb,gBAAgB,EAKjB,MAAM,SAAS,CAAC;AAiTjB,wBAAgB,cAAc,CAAC,KAAK,EAAE,iBAAiB,GAAG,gBAAgB,CAiBzE;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,YAAY,CA6DnE;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,IAAI,gBAAgB,CAEjF;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,IAAI,aAAa,CAEjF;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,IAAI,iBAAiB,CAErF"}

package/dist/system.js

@@ -1,12 +1,97 @@
 /**
- * @nexart/ui-renderer v0.2.0 - System Creation & Validation
+ * @nexart/ui-renderer v0.4.0 - System Creation & Validation
  *
- * Declarative system authoring for NexArt Protocol.
+ * Opinionated generative design system with aesthetic guardrails.
+ * Supports background, primitive, and sketch element types.
  */
-const CURRENT_VERSION = '0.2';
+const CURRENT_VERSION = '0.4';
+function isCodeSystem(input) {
+    return 'type' in input && input.type === 'code';
+}
+function isUnifiedSystem(input) {
+    if (!('elements' in input) || !Array.isArray(input.elements)) {
+        return false;
+    }
+    const elements = input.elements;
+    return elements.length > 0 && elements.some((el) => el.type === 'background' || el.type === 'primitive' || el.type === 'sketch');
+}
+function isDeclarativeInput(input) {
+    return 'elements' in input && 'background' in input && Array.isArray(input.elements);
+}
 const VALID_ELEMENT_TYPES = ['dots', 'lines', 'waves', 'grid', 'flowField', 'orbits'];
 const VALID_MOTION_SOURCES = ['none', 'time', 'seed'];
 const VALID_TEXTURES = ['none', 'noise', 'grain'];
+const VALID_BACKGROUND_PRESETS = ['layered-waves', 'soft-noise-field', 'orbital-lines', 'flowing-stripes', 'minimal-grid'];
+const VALID_PRIMITIVE_NAMES = ['waves', 'dots', 'lines', 'grid', 'flow', 'orbits', 'circles', 'stripes'];
+const VALID_PALETTES = ['offwhite-dark', 'midnight', 'warm-neutral', 'ocean', 'sunset', 'forest'];
+function validateUnifiedElement(el, index) {
+    const errors = [];
+    const prefix = `Element[${index}]`;
+    if (!el.type) {
+        errors.push(`${prefix}: type is required`);
+        return errors;
+    }
+    switch (el.type) {
+        case 'background':
+            if (!el.preset || !VALID_BACKGROUND_PRESETS.includes(el.preset)) {
+                errors.push(`${prefix}: preset must be one of: ${VALID_BACKGROUND_PRESETS.join(', ')}`);
+            }
+            if (el.palette && !VALID_PALETTES.includes(el.palette)) {
+                errors.push(`${prefix}: palette must be one of: ${VALID_PALETTES.join(', ')}`);
+            }
+            if (el.loop) {
+                if (typeof el.loop.duration !== 'number' || el.loop.duration < 1 || el.loop.duration > 600) {
+                    errors.push(`${prefix}: loop.duration must be between 1 and 600`);
+                }
+            }
+            break;
+        case 'primitive':
+            if (!el.name || !VALID_PRIMITIVE_NAMES.includes(el.name)) {
+                errors.push(`${prefix}: name must be one of: ${VALID_PRIMITIVE_NAMES.join(', ')}`);
+            }
+            if (el.count !== undefined && (el.count < 1 || el.count > 100)) {
+                errors.push(`${prefix}: count must be between 1 and 100`);
+            }
+            if (el.opacity !== undefined && (el.opacity < 0 || el.opacity > 1)) {
+                errors.push(`${prefix}: opacity must be between 0 and 1`);
+            }
+            break;
+        case 'sketch':
+            if (!el.code || typeof el.code !== 'string' || el.code.trim().length === 0) {
+                errors.push(`${prefix}: code is required and must be a non-empty string`);
+            }
+            if (el.totalFrames !== undefined && (el.totalFrames < 1 || el.totalFrames > 600)) {
+                errors.push(`${prefix}: totalFrames must be between 1 and 600`);
+            }
+            break;
+        default:
+            errors.push(`${prefix}: type must be "background", "primitive", or "sketch"`);
+    }
+    return errors;
+}
+function validateUnifiedSystem(input) {
+    const errors = [];
+    if (!Array.isArray(input.elements) || input.elements.length === 0) {
+        errors.push('elements array is required and must not be empty');
+        return errors;
+    }
+    input.elements.forEach((el, i) => {
+        errors.push(...validateUnifiedElement(el, i));
+    });
+    if (input.width !== undefined && (input.width < 1 || input.width > 4096)) {
+        errors.push('width must be between 1 and 4096');
+    }
+    if (input.height !== undefined && (input.height < 1 || input.height > 4096)) {
+        errors.push('height must be between 1 and 4096');
+    }
+    if (!input.loop || typeof input.loop.duration !== 'number') {
+        errors.push('loop.duration is required for unified systems');
+    }
+    else if (input.loop.duration < 1 || input.loop.duration > 600) {
+        errors.push('loop.duration must be between 1 and 600');
+    }
+    return errors;
+}
 function validateBackground(bg) {
     const errors = [];
     if (!bg.color || typeof bg.color !== 'string') {
@@ -112,7 +197,40 @@ function validateMotion(motion) {
     }
     return errors;
 }
-export function validateSystem(input) {
+function validateCodeSystem(input) {
+    const errors = [];
+    if (input.type !== 'code') {
+        errors.push('type must be "code"');
+    }
+    if (!input.source || typeof input.source !== 'string') {
+        errors.push('source is required and must be a string');
+    }
+    if (input.source && input.source.trim().length === 0) {
+        errors.push('source cannot be empty');
+    }
+    if (!['static', 'loop'].includes(input.mode)) {
+        errors.push('mode must be "static" or "loop"');
+    }
+    if (typeof input.width !== 'number' || input.width < 1 || input.width > 4096) {
+        errors.push('width is required and must be between 1 and 4096');
+    }
+    if (typeof input.height !== 'number' || input.height < 1 || input.height > 4096) {
+        errors.push('height is required and must be between 1 and 4096');
+    }
+    if (input.mode === 'loop') {
+        if (typeof input.totalFrames !== 'number' || input.totalFrames < 1 || input.totalFrames > 600) {
+            errors.push('totalFrames is required for loop mode and must be between 1 and 600');
+        }
+        if (input.seed === undefined) {
+            errors.push('seed is required for loop mode to ensure determinism');
+        }
+    }
+    if (input.seed !== undefined && typeof input.seed !== 'number') {
+        errors.push('seed must be a number');
+    }
+    return errors;
+}
+function validateDeclarativeSystem(input) {
     const errors = [];
     if (typeof input.seed !== 'number') {
         errors.push('seed is required and must be a number');
@@ -134,6 +252,22 @@ export function validateSystem(input) {
     if (input.motion) {
         errors.push(...validateMotion(input.motion));
     }
+    return errors;
+}
+export function validateSystem(input) {
+    const errors = [];
+    if (isCodeSystem(input)) {
+        errors.push(...validateCodeSystem(input));
+    }
+    else if (isUnifiedSystem(input)) {
+        errors.push(...validateUnifiedSystem(input));
+    }
+    else if (isDeclarativeInput(input)) {
+        errors.push(...validateDeclarativeSystem(input));
+    }
+    else {
+        errors.push('Invalid system input: must be a code system, unified system, or declarative system');
+    }
     return {
         valid: errors.length === 0,
         errors,
@@ -144,22 +278,64 @@ export function createSystem(input) {
     if (!validation.valid) {
         throw new Error(`Invalid system: ${validation.errors.join('; ')}`);
     }
+    if (isCodeSystem(input)) {
+        const codeSystem = {
+            protocol: 'nexart',
+            systemType: 'code',
+            systemVersion: CURRENT_VERSION,
+            source: input.source,
+            mode: input.mode,
+            width: input.width,
+            height: input.height,
+            seed: input.seed ?? Math.floor(Math.random() * 2147483647),
+            totalFrames: input.totalFrames,
+            deterministic: true,
+            createdAt: new Date().toISOString(),
+        };
+        return codeSystem;
+    }
+    if (isUnifiedSystem(input)) {
+        const unifiedSystem = {
+            protocol: 'nexart',
+            systemType: 'unified',
+            systemVersion: CURRENT_VERSION,
+            seed: input.seed ?? Math.floor(Math.random() * 2147483647),
+            width: input.width ?? 800,
+            height: input.height ?? 800,
+            elements: input.elements,
+            loop: input.loop ?? { duration: 120 },
+            deterministic: true,
+            createdAt: new Date().toISOString(),
+        };
+        return unifiedSystem;
+    }
+    const declarativeInput = input;
     const system = {
         protocol: 'nexart',
-        systemVersion: input.version || CURRENT_VERSION,
-        seed: input.seed,
+        systemType: 'declarative',
+        systemVersion: declarativeInput.version || CURRENT_VERSION,
+        seed: declarativeInput.seed,
         background: {
-            color: input.background.color,
-            texture: input.background.texture || 'none',
-            ...(input.background.gradient && { gradient: input.background.gradient }),
+            color: declarativeInput.background.color,
+            texture: declarativeInput.background.texture || 'none',
+            ...(declarativeInput.background.gradient && { gradient: declarativeInput.background.gradient }),
         },
-        elements: input.elements.map((el) => ({
+        elements: declarativeInput.elements.map((el) => ({
             ...el,
             opacity: el.opacity ?? 1,
         })),
-        motion: input.motion || { source: 'none' },
+        motion: declarativeInput.motion || { source: 'none' },
         deterministic: true,
         createdAt: new Date().toISOString(),
     };
     return system;
 }
+export function isCodeModeSystem(system) {
+    return 'systemType' in system && system.systemType === 'code';
+}
+export function isUnifiedModeSystem(system) {
+    return 'systemType' in system && system.systemType === 'unified';
+}
+export function isDeclarativeSystem(system) {
+    return !('systemType' in system) || system.systemType === 'declarative';
+}

package/dist/types.d.ts

@@ -1,10 +1,107 @@
 /**
- * @nexart/ui-renderer v0.2.0 - Type Definitions
+ * @nexart/ui-renderer v0.4.0 - Type Definitions
  *
- * Declarative system authoring types for NexArt Protocol.
+ * Opinionated generative design system with aesthetic guardrails.
  * This SDK is non-canonical and for authoring/preview only.
  */
+export declare const SDK_VERSION = "0.4.0";
+export declare const AESTHETIC_DEFAULTS: {
+    readonly background: {
+        readonly r: 246;
+        readonly g: 245;
+        readonly b: 242;
+    };
+    readonly foreground: {
+        readonly r: 45;
+        readonly g: 45;
+        readonly b: 45;
+    };
+    readonly strokeWeight: {
+        readonly min: 0.5;
+        readonly max: 4;
+        readonly default: 1.5;
+    };
+    readonly density: {
+        readonly min: 3;
+        readonly max: 50;
+        readonly default: 12;
+    };
+    readonly motion: {
+        readonly speed: 0.5;
+        readonly easing: "sinusoidal";
+    };
+    readonly margins: {
+        readonly ratio: 0.08;
+    };
+    readonly loop: {
+        readonly defaultFrames: 120;
+    };
+};
+export type MotionSpeed = 'slow' | 'medium' | 'fast';
+export type StrokeWeightAuto = 'auto' | 'thin' | 'medium' | 'thick' | number;
+export interface LoopConfig {
+    duration: number;
+    fps?: number;
+}
+export type BackgroundPreset = 'layered-waves' | 'soft-noise-field' | 'orbital-lines' | 'flowing-stripes' | 'minimal-grid';
+export type ColorPalette = 'offwhite-dark' | 'midnight' | 'warm-neutral' | 'ocean' | 'sunset' | 'forest';
+export interface BackgroundElement {
+    type: 'background';
+    preset: BackgroundPreset;
+    palette?: ColorPalette;
+    loop?: LoopConfig;
+    seed?: number;
+}
+export type PrimitiveName = 'waves' | 'dots' | 'lines' | 'grid' | 'flow' | 'orbits' | 'circles' | 'stripes';
+export interface PrimitiveElement {
+    type: 'primitive';
+    name: PrimitiveName;
+    count?: number;
+    strokeWeight?: StrokeWeightAuto;
+    motion?: MotionSpeed;
+    color?: string;
+    opacity?: number;
+    loop?: LoopConfig;
+    seed?: number;
+}
+export interface SketchElement {
+    type: 'sketch';
+    code: string;
+    totalFrames?: number;
+    seed?: number;
+    normalize?: boolean;
+}
+export type UnifiedElement = BackgroundElement | PrimitiveElement | SketchElement;
+export interface UnifiedSystemInput {
+    version?: string;
+    seed?: number;
+    width?: number;
+    height?: number;
+    elements: UnifiedElement[];
+    loop?: LoopConfig;
+}
+export interface UnifiedSystem {
+    protocol: 'nexart';
+    systemType: 'unified';
+    systemVersion: string;
+    seed: number;
+    width: number;
+    height: number;
+    elements: UnifiedElement[];
+    loop: LoopConfig;
+    deterministic: true;
+    createdAt: string;
+}
 export type BackgroundTexture = 'none' | 'noise' | 'grain';
+export interface CodeSystem {
+    type: 'code';
+    source: string;
+    mode: 'static' | 'loop';
+    width: number;
+    height: number;
+    seed?: number;
+    totalFrames?: number;
+}
 export interface BackgroundConfig {
     color: string;
     gradient?: {
@@ -65,21 +162,23 @@ export interface OrbitsElement {
     color?: string;
     opacity?: number;
 }
-export type SystemElement = DotsElement | LinesElement | WavesElement | GridElement | FlowFieldElement | OrbitsElement;
+export type DeclarativeElement = DotsElement | LinesElement | WavesElement | GridElement | FlowFieldElement | OrbitsElement;
+export type SystemElement = DeclarativeElement;
 export type MotionSource = 'none' | 'time' | 'seed';
 export interface MotionConfig {
     source: MotionSource;
     speed?: number;
 }
-export interface NexArtSystemInput {
+export interface DeclarativeSystemInput {
     version?: string;
     seed: number;
     background: BackgroundConfig;
     elements: SystemElement[];
     motion?: MotionConfig;
 }
-export interface NexArtSystem {
+export interface DeclarativeSystem {
     protocol: 'nexart';
+    systemType: 'declarative';
     systemVersion: string;
     seed: number;
     background: BackgroundConfig;
@@ -88,9 +187,30 @@ export interface NexArtSystem {
     deterministic: boolean;
     createdAt: string;
 }
+export interface NexArtCodeSystem {
+    protocol: 'nexart';
+    systemType: 'code';
+    systemVersion: string;
+    source: string;
+    mode: 'static' | 'loop';
+    width: number;
+    height: number;
+    seed: number;
+    totalFrames?: number;
+    deterministic: boolean;
+    createdAt: string;
+}
+export type NexArtSystemInput = DeclarativeSystemInput | CodeSystem | UnifiedSystemInput;
+export type NexArtSystem = DeclarativeSystem | NexArtCodeSystem | UnifiedSystem;
 export interface PreviewOptions {
     mode?: 'static' | 'loop';
     showBadge?: boolean;
+    onPreview?: (canvas: HTMLCanvasElement) => void;
+    onComplete?: (result: {
+        type: 'image' | 'video';
+        blob: Blob;
+    }) => void;
+    onError?: (error: Error) => void;
 }
 export interface ValidationResult {
     valid: boolean;