@nexart/codemode-sdk 1.6.0 → 1.8.0

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

@@ -0,0 +1,191 @@
+/**
+ * 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/sdk/codemode/types.d.ts.map

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

package/dist/sdk/codemode/types.js

@@ -0,0 +1,32 @@
+/**
+ * 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,
+};

package/dist/shared/noiseSnapshot.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Noise Snapshot Types
+ *
+ * This module defines the canonical NoiseSnapshot interface used by the Code Mode runtime.
+ * All noise parameters are normalized to deterministic, reproducible values.
+ *
+ * Architecture:
+ *   NoiseState (UI) → NoiseSnapshot (normalized) → N.* globals → Code Mode Runtime
+ */
+/**
+ * Blend modes for combining Perlin and Cellular noise
+ */
+export type NoiseBlendMode = 'perlin_only' | 'blend' | 'warp' | 'interleave';
+/**
+ * Raw noise parameters from the UI
+ */
+export interface NoiseParams {
+    blendMode: NoiseBlendMode;
+    scale: number;
+    octaves: number;
+    persistence: number;
+    lacunarity: number;
+    cellDensity: number;
+    cellDistortion: number;
+    seed: number;
+    backgroundColor: string;
+    noiseColor: string;
+    zoomLevel: number;
+}
+/**
+ * Normalized snapshot for Code Mode injection
+ * All values are designed for deterministic rendering
+ */
+export interface NoiseSnapshot {
+    scale: number;
+    octaves: number;
+    persistence: number;
+    lacunarity: number;
+    cellDensity: number;
+    cellDistortion: number;
+    blendMode: NoiseBlendMode;
+    bgR: number;
+    bgG: number;
+    bgB: number;
+    noiseR: number;
+    noiseG: number;
+    noiseB: number;
+    seed: number;
+    zoomLevel: number;
+}
+/**
+ * Create a NoiseSnapshot from raw NoiseParams
+ */
+export declare function createNoiseSnapshot(params: NoiseParams): NoiseSnapshot;
+/**
+ * Validate and clamp noise snapshot values
+ */
+export declare function validateNoiseSnapshot(snapshot: NoiseSnapshot): NoiseSnapshot;
+//# sourceMappingURL=noiseSnapshot.d.ts.map

package/dist/shared/noiseSnapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"noiseSnapshot.d.ts","sourceRoot":"","sources":["../../../../shared/noiseSnapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,aAAa,GAAG,OAAO,GAAG,MAAM,GAAG,YAAY,CAAC;AAE7E;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,cAAc,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAE5B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IAGnB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IAGvB,SAAS,EAAE,cAAc,CAAC;IAG1B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IAGf,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB;AAmBD;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,WAAW,GAAG,aAAa,CAqBtE;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,aAAa,GAAG,aAAa,CAmB5E"}

package/dist/shared/noiseSnapshot.js

@@ -0,0 +1,72 @@
+/**
+ * Noise Snapshot Types
+ *
+ * This module defines the canonical NoiseSnapshot interface used by the Code Mode runtime.
+ * All noise parameters are normalized to deterministic, reproducible values.
+ *
+ * Architecture:
+ *   NoiseState (UI) → NoiseSnapshot (normalized) → N.* globals → Code Mode Runtime
+ */
+/**
+ * Parse a hex color string to RGB values
+ */
+function hexToRgb(hex) {
+    if (!hex || !hex.startsWith('#') || hex.length !== 7) {
+        return [255, 255, 255];
+    }
+    try {
+        const r = parseInt(hex.slice(1, 3), 16);
+        const g = parseInt(hex.slice(3, 5), 16);
+        const b = parseInt(hex.slice(5, 7), 16);
+        return [r, g, b];
+    }
+    catch {
+        return [255, 255, 255];
+    }
+}
+/**
+ * Create a NoiseSnapshot from raw NoiseParams
+ */
+export function createNoiseSnapshot(params) {
+    const [bgR, bgG, bgB] = hexToRgb(params.backgroundColor);
+    const [noiseR, noiseG, noiseB] = hexToRgb(params.noiseColor);
+    return {
+        scale: params.scale,
+        octaves: Math.floor(params.octaves),
+        persistence: params.persistence,
+        lacunarity: params.lacunarity,
+        cellDensity: params.cellDensity,
+        cellDistortion: params.cellDistortion,
+        blendMode: params.blendMode,
+        bgR,
+        bgG,
+        bgB,
+        noiseR,
+        noiseG,
+        noiseB,
+        seed: params.seed,
+        zoomLevel: params.zoomLevel,
+    };
+}
+/**
+ * Validate and clamp noise snapshot values
+ */
+export function validateNoiseSnapshot(snapshot) {
+    const clamp = (v, min, max) => Math.max(min, Math.min(max, v));
+    return {
+        ...snapshot,
+        scale: clamp(snapshot.scale, 0.001, 0.1),
+        octaves: clamp(Math.floor(snapshot.octaves), 1, 8),
+        persistence: clamp(snapshot.persistence, 0.1, 1.0),
+        lacunarity: clamp(snapshot.lacunarity, 1.0, 3.0),
+        cellDensity: clamp(snapshot.cellDensity, 0.1, 1.0),
+        cellDistortion: clamp(snapshot.cellDistortion, 0.1, 2.0),
+        bgR: clamp(snapshot.bgR, 0, 255),
+        bgG: clamp(snapshot.bgG, 0, 255),
+        bgB: clamp(snapshot.bgB, 0, 255),
+        noiseR: clamp(snapshot.noiseR, 0, 255),
+        noiseG: clamp(snapshot.noiseG, 0, 255),
+        noiseB: clamp(snapshot.noiseB, 0, 255),
+        zoomLevel: clamp(snapshot.zoomLevel, 0.1, 2.0),
+    };
+}

package/dist/shared/soundSnapshot.d.ts

@@ -0,0 +1,94 @@
+/**
+ * SoundSnapshot - Canonical sound data interface for Code Mode integration
+ *
+ * This is the single source of truth for sound-derived parameters.
+ * All values are normalized to 0-100 range for consistency.
+ *
+ * Usage:
+ *   - Sound analysis produces SoundSnapshot
+ *   - Code Mode receives it as read-only S.* globals
+ *   - SoundArt styles become Code Mode sketches using S.*
+ */
+export interface SoundSnapshot {
+    volume: number;
+    amplitude: number;
+    dynamicRange: number;
+    brightness: number;
+    bass: number;
+    mid: number;
+    treble: number;
+    harmonicity: number;
+    aggression: number;
+    attack: number;
+    rhythmicity: number;
+    silence: number;
+    hue: number;
+    chroma: number;
+    length: number;
+    t: number;
+    frame?: number;
+    totalFrames?: number;
+}
+/**
+ * Create an empty/default SoundSnapshot with neutral values
+ */
+export declare function createEmptySoundSnapshot(): SoundSnapshot;
+/**
+ * Clamp a value to 0-100 range
+ */
+export declare function clampPercent(value: number): number;
+/**
+ * Convert a 0-1 normalized value to 0-100 percentage
+ */
+export declare function toPercent(value: number): number;
+/**
+ * SoundFeatures type for compatibility with existing analysis code
+ */
+export interface SoundBands {
+    sub?: number;
+    bass: number;
+    lowMid: number;
+    highMid: number;
+    treble: number;
+}
+export interface FrameFeatures {
+    t0: number;
+    t1: number;
+    rms: number;
+    centroid: number;
+    bands: SoundBands;
+    aggression: number;
+    amplitude: number;
+    dynamicRange: number;
+    attack: number;
+    rhythmicity: number;
+    harmonicity: number;
+    silence: number;
+    tempoBpm?: number;
+}
+export interface SoundFeatures {
+    rms: number;
+    centroid: number;
+    bands: SoundBands;
+    durationSec: number;
+    seedHint?: number;
+    frames: FrameFeatures[];
+    averageBpm?: number;
+    featureVariances?: Record<string, number>;
+}
+/**
+ * Create a SoundSnapshot from SoundFeatures (analysis output)
+ *
+ * @param sound - Raw sound features from analysis
+ * @param frames - Frame features array
+ * @param windowMs - Time window to average (default 800ms for recent snapshot)
+ * @param frameIndex - Current frame index for loop mode
+ * @param totalFrames - Total frames for loop mode
+ */
+export declare function createSoundSnapshot(sound: SoundFeatures, frames?: FrameFeatures[], windowMs?: number, frameIndex?: number, totalFrames?: number): SoundSnapshot;
+/**
+ * Freeze a SoundSnapshot to make it immutable
+ * This is used when injecting into Code Mode to prevent modification
+ */
+export declare function freezeSoundSnapshot(snapshot: SoundSnapshot): Readonly<SoundSnapshot>;
+//# sourceMappingURL=soundSnapshot.d.ts.map

package/dist/shared/soundSnapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"soundSnapshot.d.ts","sourceRoot":"","sources":["../../../../shared/soundSnapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,aAAa;IAE5B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IAGrB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IAGf,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IAGf,WAAW,EAAE,MAAM,CAAC;IAGpB,OAAO,EAAE,MAAM,CAAC;IAGhB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IAGf,MAAM,EAAE,MAAM,CAAC;IACf,CAAC,EAAE,MAAM,CAAC;IAGV,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,wBAAgB,wBAAwB,IAAI,aAAa,CAmBxD;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,UAAU,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,UAAU,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC3C;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,aAAa,EACpB,MAAM,CAAC,EAAE,aAAa,EAAE,EACxB,QAAQ,GAAE,MAAY,EACtB,UAAU,CAAC,EAAE,MAAM,EACnB,WAAW,CAAC,EAAE,MAAM,GACnB,aAAa,CAsEf;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,aAAa,GAAG,QAAQ,CAAC,aAAa,CAAC,CAEpF"}

package/dist/shared/soundSnapshot.js

@@ -0,0 +1,128 @@
+/**
+ * SoundSnapshot - Canonical sound data interface for Code Mode integration
+ *
+ * This is the single source of truth for sound-derived parameters.
+ * All values are normalized to 0-100 range for consistency.
+ *
+ * Usage:
+ *   - Sound analysis produces SoundSnapshot
+ *   - Code Mode receives it as read-only S.* globals
+ *   - SoundArt styles become Code Mode sketches using S.*
+ */
+/**
+ * Create an empty/default SoundSnapshot with neutral values
+ */
+export function createEmptySoundSnapshot() {
+    return {
+        volume: 50,
+        amplitude: 50,
+        dynamicRange: 25,
+        brightness: 50,
+        bass: 30,
+        mid: 40,
+        treble: 30,
+        harmonicity: 50,
+        aggression: 30,
+        attack: 50,
+        rhythmicity: 40,
+        silence: 0,
+        hue: 50,
+        chroma: 50,
+        length: 50,
+        t: 0,
+    };
+}
+/**
+ * Clamp a value to 0-100 range
+ */
+export function clampPercent(value) {
+    return Math.max(0, Math.min(100, value));
+}
+/**
+ * Convert a 0-1 normalized value to 0-100 percentage
+ */
+export function toPercent(value) {
+    return clampPercent(value * 100);
+}
+/**
+ * Create a SoundSnapshot from SoundFeatures (analysis output)
+ *
+ * @param sound - Raw sound features from analysis
+ * @param frames - Frame features array
+ * @param windowMs - Time window to average (default 800ms for recent snapshot)
+ * @param frameIndex - Current frame index for loop mode
+ * @param totalFrames - Total frames for loop mode
+ */
+export function createSoundSnapshot(sound, frames, windowMs = 800, frameIndex, totalFrames) {
+    const framesArr = frames || sound.frames || [];
+    const bands = {
+        bass: sound.bands?.bass ?? 0.3,
+        lowMid: sound.bands?.lowMid ?? 0.25,
+        highMid: sound.bands?.highMid ?? 0.25,
+        treble: sound.bands?.treble ?? 0.2
+    };
+    // Get recent frames within window
+    const now = framesArr.length > 0
+        ? framesArr[framesArr.length - 1].t1 * 1000
+        : 0;
+    const windowStart = now - windowMs;
+    const recentFrames = framesArr.filter(f => f.t1 * 1000 >= windowStart);
+    const useFrames = recentFrames.length > 0 ? recentFrames : framesArr;
+    // Helper to extract and average frame values
+    const getFrameAvg = (key, def) => {
+        if (useFrames.length === 0)
+            return def;
+        const values = useFrames.map(f => f[key] ?? def);
+        return values.reduce((a, b) => a + b, 0) / values.length;
+    };
+    const getFrameSpan = (key, def) => {
+        if (useFrames.length < 2)
+            return 0;
+        const values = useFrames.map(f => f[key] ?? def);
+        return Math.max(...values) - Math.min(...values);
+    };
+    // Extract averaged values
+    const rmsNow = getFrameAvg('rms', sound.rms ?? 0);
+    const ampNow = getFrameAvg('amplitude', sound.rms ?? 0);
+    const attNow = getFrameAvg('attack', 0.5);
+    const harmNow = getFrameAvg('harmonicity', 0.5);
+    const aggrNow = getFrameAvg('aggression', 0.5);
+    const rhNow = getFrameAvg('rhythmicity', 0.4);
+    const silNow = getFrameAvg('silence', 0);
+    const dynNow = getFrameSpan('rms', sound.rms ?? 0);
+    const centNow = getFrameAvg('centroid', sound.centroid ?? 0.5);
+    // Apply perceptual scaling for loudness
+    const amplifiedRms = Math.pow(rmsNow, 0.33);
+    const amplifiedAmp = Math.pow(ampNow, 0.4);
+    // Calculate normalized time
+    const t = frameIndex !== undefined && totalFrames !== undefined
+        ? frameIndex / Math.max(1, totalFrames)
+        : (framesArr.length > 0 ? 1 : 0);
+    return {
+        volume: toPercent(amplifiedRms),
+        amplitude: toPercent(amplifiedAmp),
+        dynamicRange: toPercent(dynNow),
+        brightness: toPercent(centNow),
+        bass: toPercent(bands.bass),
+        mid: toPercent((bands.lowMid + bands.highMid) / 2),
+        treble: toPercent(bands.treble),
+        harmonicity: toPercent(harmNow),
+        aggression: toPercent(aggrNow),
+        attack: toPercent(attNow),
+        rhythmicity: toPercent(rhNow),
+        silence: toPercent(silNow),
+        hue: toPercent(centNow * 0.75 + aggrNow * 0.25),
+        chroma: toPercent(Math.min(1, Math.sqrt((bands.bass + bands.treble) / 2))),
+        length: Math.min(100, (sound.durationSec ?? 0) * 10),
+        t,
+        frame: frameIndex,
+        totalFrames,
+    };
+}
+/**
+ * Freeze a SoundSnapshot to make it immutable
+ * This is used when injecting into Code Mode to prevent modification
+ */
+export function freezeSoundSnapshot(snapshot) {
+    return Object.freeze({ ...snapshot });
+}

package/dist/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/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)