@nexart/codemode-sdk 1.5.0 → 1.5.1

package/dist/noise-engine.js

@@ -0,0 +1,132 @@
+/**
+ * Noise → Code Mode Engine
+ *
+ * This is the orchestrator that runs Noise rendering through the Code Mode engine.
+ * It replaces the legacy p5.js-based NoiseCanvas with a protocol-compliant pipeline.
+ *
+ * Architecture:
+ *   1. NoiseParams from UI state
+ *   2. NoiseParams → NoiseSnapshot conversion
+ *   3. NoiseSnapshot injected as N.* globals into Code Mode
+ *   4. Noise sketch executed via Code Mode runtime
+ *   5. Result: PNG output (deterministic)
+ */
+import { createNoiseSnapshot, validateNoiseSnapshot } from '../../shared/noiseSnapshot';
+import { createP5Runtime } from './p5-runtime';
+import { createNoiseGlobals, injectNoiseGlobals } from './noise-bridge';
+import { getNoiseSketch } from './noise-sketches';
+/**
+ * Render noise via Code Mode runtime
+ *
+ * This is the main entry point for protocol-compliant noise rendering.
+ * All rendering goes through the Code Mode runtime for determinism.
+ */
+export async function renderNoiseViaCodeMode(options) {
+    const { params, canvas, config, onProgress } = options;
+    // Protocol enforcement logging
+    console.log('[Noise] Protocol enforcement: HARD | renderedVia: codemode');
+    onProgress?.(0.1);
+    // Create and validate snapshot
+    const rawSnapshot = createNoiseSnapshot(params);
+    const snapshot = validateNoiseSnapshot(rawSnapshot);
+    onProgress?.(0.2);
+    // Create N.* globals
+    const noiseGlobals = createNoiseGlobals(snapshot);
+    // Get the noise sketch
+    const sketchName = 'fractalNoise';
+    const sketchCode = getNoiseSketch(sketchName);
+    // Inject N.* globals into sketch
+    const injectedCode = injectNoiseGlobals(sketchCode, noiseGlobals);
+    onProgress?.(0.3);
+    // Set canvas dimensions
+    canvas.width = config.width;
+    canvas.height = config.height;
+    // Create P5 runtime with correct signature
+    const runtimeConfig = {
+        seed: config.seed,
+    };
+    const runtime = createP5Runtime(canvas, config.width, config.height, runtimeConfig);
+    onProgress?.(0.5);
+    // Build globals with all runtime functions and noise globals
+    const globals = {
+        ...runtime,
+        width: config.width,
+        height: config.height,
+    };
+    // Execute the sketch
+    try {
+        executeNoiseSketch(injectedCode, globals);
+        onProgress?.(0.9);
+        console.log('[Noise] Rendered via Code Mode runtime');
+        // Build metadata
+        const metadata = {
+            mode: 'Noise',
+            timestamp: new Date().toISOString(),
+            enforcement: 'hard',
+            renderedVia: 'codemode',
+            noiseParams: {
+                scale: snapshot.scale,
+                octaves: snapshot.octaves,
+                persistence: snapshot.persistence,
+                lacunarity: snapshot.lacunarity,
+                cellDensity: snapshot.cellDensity,
+                cellDistortion: snapshot.cellDistortion,
+                blendMode: snapshot.blendMode,
+            },
+            generationParams: {
+                seed: config.seed,
+                canvasSize: { width: config.width, height: config.height },
+            },
+        };
+        onProgress?.(1.0);
+        return {
+            mode: 'noise',
+            snapshot,
+            metadata,
+        };
+    }
+    catch (error) {
+        console.error('[Noise] Code Mode execution failed:', error);
+        throw error;
+    }
+}
+/**
+ * Execute a noise sketch string in the context of the runtime globals
+ */
+function executeNoiseSketch(code, globals) {
+    const globalNames = Object.keys(globals);
+    const globalValues = Object.values(globals);
+    // Wrap the sketch code to call setup()
+    const wrappedCode = `
+    ${code}
+    
+    // Execute setup (noise is static - single frame)
+    if (typeof setup === 'function') {
+      setup();
+    }
+  `;
+    // Create and execute the function
+    const sketchFunction = new Function(...globalNames, wrappedCode);
+    sketchFunction(...globalValues);
+}
+/**
+ * Compile noise params to a Code Mode system
+ * This produces a reproducible system definition
+ */
+export function compileNoiseSystem(params) {
+    const snapshot = validateNoiseSnapshot(createNoiseSnapshot(params));
+    const noiseGlobals = createNoiseGlobals(snapshot);
+    const sketchCode = injectNoiseGlobals(getNoiseSketch('fractalNoise'), noiseGlobals);
+    return {
+        sketchCode,
+        snapshot,
+        seed: params.seed,
+    };
+}
+/**
+ * Check if noise can be rendered via Code Mode
+ * (Always true - no legacy fallback)
+ */
+export function canRenderNoiseViaCodeMode() {
+    return true;
+}

package/dist/noise-sketches/fractalNoise.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Fractal Noise - Code Mode Sketch
+ *
+ * This sketch implements Perlin FBM and Cellular noise rendering
+ * through the Code Mode p5-runtime. Uses N.* globals for all parameters.
+ *
+ * Original: client/src/components/noise-canvas-simple.tsx
+ */
+export declare const FRACTAL_NOISE_SKETCH = "\n// Fractal Noise - Code Mode Sketch\n// Uses N.* noise globals and standard p5-like functions\n\nfunction setup() {\n  // Set seeded random for reproducibility\n  randomSeed(N.seed);\n  noiseSeed(N.seed);\n  \n  // Set background color\n  background(N.bgR, N.bgG, N.bgB);\n  \n  // Noise rendering parameters\n  const adjustedScale = N.scale * (1 / N.zoom) * 0.05;\n  const cellSize = 4; // Fixed for quality\n  \n  // Generate cellular points if needed\n  const numPoints = Math.floor(20 + N.cellDensity * 180);\n  const cellPoints = [];\n  for (let i = 0; i < numPoints; i++) {\n    cellPoints.push([random(0, width), random(0, height)]);\n  }\n  \n  // Helper: Perlin FBM (Fractional Brownian Motion)\n  function perlinFBM(x, y, scale) {\n    let value = 0;\n    let amplitude = 1;\n    let frequency = 1;\n    let maxValue = 0;\n    \n    const oct = Math.min(N.octaves, 6); // Cap for performance\n    \n    for (let i = 0; i < oct; i++) {\n      value += noise(x * scale * frequency, y * scale * frequency) * amplitude;\n      maxValue += amplitude;\n      amplitude *= N.persistence;\n      frequency *= N.lacunarity;\n    }\n    \n    return value / maxValue;\n  }\n  \n  // Helper: Cellular noise (Worley)\n  function cellularNoise(x, y, points) {\n    let sampleX = x;\n    let sampleY = y;\n    \n    // Warp distortion if using warp mode\n    if (N.isWarp && N.cellDistortion > 0) {\n      const distortionAmount = N.cellDistortion * 100;\n      sampleX += noise(x * 0.01, y * 0.01) * distortionAmount;\n      sampleY += noise(y * 0.01, x * 0.01) * distortionAmount;\n    }\n    \n    // Find distances to closest points\n    let minDist = 999999;\n    let secondMinDist = 999999;\n    \n    for (let i = 0; i < points.length; i++) {\n      const px = points[i][0];\n      const py = points[i][1];\n      const dx = sampleX - px;\n      const dy = sampleY - py;\n      const dist = Math.sqrt(dx * dx + dy * dy);\n      \n      if (dist < minDist) {\n        secondMinDist = minDist;\n        minDist = dist;\n      } else if (dist < secondMinDist) {\n        secondMinDist = dist;\n      }\n    }\n    \n    // Normalize distance\n    return Math.min(1.0, (secondMinDist - minDist) / 50);\n  }\n  \n  // Render the noise grid\n  noStroke();\n  \n  for (let y = 0; y < height; y += cellSize) {\n    for (let x = 0; x < width; x += cellSize) {\n      // Calculate Perlin value\n      const perlinValue = perlinFBM(x, y, adjustedScale);\n      \n      // Calculate final value based on blend mode\n      let finalValue = perlinValue;\n      \n      if (!N.isPerlinOnly) {\n        const cellValue = cellularNoise(x, y, cellPoints);\n        \n        if (N.isBlend) {\n          finalValue = perlinValue * cellValue;\n        } else if (N.isWarp) {\n          finalValue = (perlinValue + cellValue) / 2;\n        } else if (N.isInterleave) {\n          finalValue = (Math.floor(x / 20) + Math.floor(y / 20)) % 2 === 0\n            ? perlinValue\n            : cellValue;\n        }\n      }\n      \n      // Set opacity based on noise value\n      const alpha = map(finalValue, 0, 1, 0, 255);\n      \n      // Fill with noise color and calculated alpha\n      fill(N.noiseR, N.noiseG, N.noiseB, alpha);\n      rect(x, y, cellSize, cellSize);\n    }\n  }\n}\n";
+export default FRACTAL_NOISE_SKETCH;
+//# sourceMappingURL=fractalNoise.d.ts.map

package/dist/noise-sketches/fractalNoise.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fractalNoise.d.ts","sourceRoot":"","sources":["../../noise-sketches/fractalNoise.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,eAAO,MAAM,oBAAoB,4sGA+GhC,CAAC;AAEF,eAAe,oBAAoB,CAAC"}

package/dist/noise-sketches/fractalNoise.js

@@ -0,0 +1,121 @@
+/**
+ * Fractal Noise - Code Mode Sketch
+ *
+ * This sketch implements Perlin FBM and Cellular noise rendering
+ * through the Code Mode p5-runtime. Uses N.* globals for all parameters.
+ *
+ * Original: client/src/components/noise-canvas-simple.tsx
+ */
+export const FRACTAL_NOISE_SKETCH = `
+// Fractal Noise - Code Mode Sketch
+// Uses N.* noise globals and standard p5-like functions
+
+function setup() {
+  // Set seeded random for reproducibility
+  randomSeed(N.seed);
+  noiseSeed(N.seed);
+  
+  // Set background color
+  background(N.bgR, N.bgG, N.bgB);
+  
+  // Noise rendering parameters
+  const adjustedScale = N.scale * (1 / N.zoom) * 0.05;
+  const cellSize = 4; // Fixed for quality
+  
+  // Generate cellular points if needed
+  const numPoints = Math.floor(20 + N.cellDensity * 180);
+  const cellPoints = [];
+  for (let i = 0; i < numPoints; i++) {
+    cellPoints.push([random(0, width), random(0, height)]);
+  }
+  
+  // Helper: Perlin FBM (Fractional Brownian Motion)
+  function perlinFBM(x, y, scale) {
+    let value = 0;
+    let amplitude = 1;
+    let frequency = 1;
+    let maxValue = 0;
+    
+    const oct = Math.min(N.octaves, 6); // Cap for performance
+    
+    for (let i = 0; i < oct; i++) {
+      value += noise(x * scale * frequency, y * scale * frequency) * amplitude;
+      maxValue += amplitude;
+      amplitude *= N.persistence;
+      frequency *= N.lacunarity;
+    }
+    
+    return value / maxValue;
+  }
+  
+  // Helper: Cellular noise (Worley)
+  function cellularNoise(x, y, points) {
+    let sampleX = x;
+    let sampleY = y;
+    
+    // Warp distortion if using warp mode
+    if (N.isWarp && N.cellDistortion > 0) {
+      const distortionAmount = N.cellDistortion * 100;
+      sampleX += noise(x * 0.01, y * 0.01) * distortionAmount;
+      sampleY += noise(y * 0.01, x * 0.01) * distortionAmount;
+    }
+    
+    // Find distances to closest points
+    let minDist = 999999;
+    let secondMinDist = 999999;
+    
+    for (let i = 0; i < points.length; i++) {
+      const px = points[i][0];
+      const py = points[i][1];
+      const dx = sampleX - px;
+      const dy = sampleY - py;
+      const dist = Math.sqrt(dx * dx + dy * dy);
+      
+      if (dist < minDist) {
+        secondMinDist = minDist;
+        minDist = dist;
+      } else if (dist < secondMinDist) {
+        secondMinDist = dist;
+      }
+    }
+    
+    // Normalize distance
+    return Math.min(1.0, (secondMinDist - minDist) / 50);
+  }
+  
+  // Render the noise grid
+  noStroke();
+  
+  for (let y = 0; y < height; y += cellSize) {
+    for (let x = 0; x < width; x += cellSize) {
+      // Calculate Perlin value
+      const perlinValue = perlinFBM(x, y, adjustedScale);
+      
+      // Calculate final value based on blend mode
+      let finalValue = perlinValue;
+      
+      if (!N.isPerlinOnly) {
+        const cellValue = cellularNoise(x, y, cellPoints);
+        
+        if (N.isBlend) {
+          finalValue = perlinValue * cellValue;
+        } else if (N.isWarp) {
+          finalValue = (perlinValue + cellValue) / 2;
+        } else if (N.isInterleave) {
+          finalValue = (Math.floor(x / 20) + Math.floor(y / 20)) % 2 === 0
+            ? perlinValue
+            : cellValue;
+        }
+      }
+      
+      // Set opacity based on noise value
+      const alpha = map(finalValue, 0, 1, 0, 255);
+      
+      // Fill with noise color and calculated alpha
+      fill(N.noiseR, N.noiseG, N.noiseB, alpha);
+      rect(x, y, cellSize, cellSize);
+    }
+  }
+}
+`;
+export default FRACTAL_NOISE_SKETCH;

package/dist/noise-sketches/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Noise Sketches Index
+ *
+ * Exports all available noise sketch generators for the Code Mode runtime.
+ */
+import FRACTAL_NOISE_SKETCH from './fractalNoise';
+export type NoiseSketchName = 'fractalNoise';
+/**
+ * Get a noise sketch by name
+ */
+export declare function getNoiseSketch(name: NoiseSketchName): string;
+/**
+ * Check if a sketch name is valid
+ */
+export declare function isValidNoiseSketch(name: string): name is NoiseSketchName;
+/**
+ * Get list of all available noise sketch names
+ */
+export declare function getAvailableNoiseSketchNames(): NoiseSketchName[];
+export { FRACTAL_NOISE_SKETCH };
+//# sourceMappingURL=index.d.ts.map

package/dist/noise-sketches/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../noise-sketches/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,oBAAoB,MAAM,gBAAgB,CAAC;AAElD,MAAM,MAAM,eAAe,GAAG,cAAc,CAAC;AAM7C;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,CAE5D;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,eAAe,CAExE;AAED;;GAEG;AACH,wBAAgB,4BAA4B,IAAI,eAAe,EAAE,CAEhE;AAED,OAAO,EAAE,oBAAoB,EAAE,CAAC"}

package/dist/noise-sketches/index.js

@@ -0,0 +1,28 @@
+/**
+ * Noise Sketches Index
+ *
+ * Exports all available noise sketch generators for the Code Mode runtime.
+ */
+import FRACTAL_NOISE_SKETCH from './fractalNoise';
+const NOISE_SKETCHES = {
+    fractalNoise: FRACTAL_NOISE_SKETCH,
+};
+/**
+ * Get a noise sketch by name
+ */
+export function getNoiseSketch(name) {
+    return NOISE_SKETCHES[name];
+}
+/**
+ * Check if a sketch name is valid
+ */
+export function isValidNoiseSketch(name) {
+    return name in NOISE_SKETCHES;
+}
+/**
+ * Get list of all available noise sketch names
+ */
+export function getAvailableNoiseSketchNames() {
+    return Object.keys(NOISE_SKETCHES);
+}
+export { FRACTAL_NOISE_SKETCH };

package/dist/sound-bridge.d.ts

@@ -0,0 +1,89 @@
+/**
+ * SoundArt → Code Mode Bridge
+ *
+ * This module injects sound-derived parameters into the Code Mode runtime
+ * as read-only `S.*` globals. It is the integration layer between sound
+ * analysis and generative art rendering.
+ *
+ * Usage in Code Mode sketches:
+ *   S.volume     // 0-100: Overall loudness
+ *   S.bass       // 0-100: Bass frequency energy
+ *   S.treble     // 0-100: Treble frequency energy
+ *   S.aggression // 0-100: Intensity/harshness
+ *   S.t          // 0-1: Normalized time position
+ *   etc.
+ */
+import type { SoundSnapshot } from '../../shared/soundSnapshot';
+/**
+ * The injected sound globals interface
+ * This is what sketches see as `S`
+ */
+export interface SoundGlobals extends Readonly<SoundSnapshot> {
+}
+/**
+ * Create a frozen, read-only sound globals object from a snapshot
+ */
+export declare function createSoundGlobals(snapshot: SoundSnapshot): SoundGlobals;
+/**
+ * Create empty/default sound globals for testing or fallback
+ */
+export declare function createEmptySoundGlobals(): SoundGlobals;
+/**
+ * Inject sound globals into the p5 runtime context
+ *
+ * This adds the `S` global object to the runtime so sketches can access
+ * sound-derived parameters like S.volume, S.bass, etc.
+ *
+ * @param runtime - The p5 runtime object
+ * @param snapshot - The sound snapshot to inject
+ * @returns The runtime with S globals added
+ */
+export declare function injectSoundGlobals<T extends Record<string, any>>(runtime: T, snapshot: SoundSnapshot): T & {
+    S: SoundGlobals;
+};
+/**
+ * Helper function to map S.* values to useful ranges
+ *
+ * Usage in sketches:
+ *   const density = mapSound(S.volume, 100, 2000) // Map 0-100 to 100-2000
+ */
+export declare function createSoundHelpers(): {
+    /**
+     * Map a sound value (0-100) to a custom range
+     */
+    mapSound: (value: number, outMin: number, outMax: number) => number;
+    /**
+     * Map a sound value (0-100) with easing
+     */
+    mapSoundEased: (value: number, outMin: number, outMax: number, easing?: number) => number;
+    /**
+     * Get a value that oscillates based on sound
+     */
+    soundOscillate: (base: number, amplitude: number, soundValue: number) => number;
+};
+/**
+ * Convert SoundSnapshot hue (0-100) to degrees (0-360)
+ */
+export declare function hueToDegrees(hue: number): number;
+/**
+ * Generate a color palette from sound parameters
+ *
+ * @param snapshot - The sound snapshot
+ * @param paletteSize - Number of colors to generate
+ * @returns Array of HSL color strings
+ */
+export declare function generateSoundPalette(snapshot: SoundSnapshot, paletteSize?: number): string[];
+/**
+ * Infer a genre profile from sound parameters
+ * This helps sketches adapt their visual style to the audio content
+ */
+export type EnergyLevel = 'low' | 'mid' | 'high';
+export type StructureType = 'chaotic' | 'organic' | 'geometric';
+export type ClarityLevel = 'muddy' | 'clear' | 'sharp';
+export interface GenreProfile {
+    energy: EnergyLevel;
+    structure: StructureType;
+    clarity: ClarityLevel;
+}
+export declare function inferGenreProfile(snapshot: SoundSnapshot): GenreProfile;
+//# sourceMappingURL=sound-bridge.d.ts.map

package/dist/sound-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sound-bridge.d.ts","sourceRoot":"","sources":["../sound-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAGhE;;;GAGG;AACH,MAAM,WAAW,YAAa,SAAQ,QAAQ,CAAC,aAAa,CAAC;CAE5D;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,aAAa,GAAG,YAAY,CAExE;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,YAAY,CAEtD;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC9D,OAAO,EAAE,CAAC,EACV,QAAQ,EAAE,aAAa,GACtB,CAAC,GAAG;IAAE,CAAC,EAAE,YAAY,CAAA;CAAE,CAuBzB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB;IAE9B;;OAEG;sBACe,MAAM,UAAU,MAAM,UAAU,MAAM,KAAG,MAAM;IAIjE;;OAEG;2BACoB,MAAM,UAAU,MAAM,UAAU,MAAM,WAAU,MAAM,KAAO,MAAM;IAK1F;;OAEG;2BACoB,MAAM,aAAa,MAAM,cAAc,MAAM,KAAG,MAAM;EAIhF;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,aAAa,EACvB,WAAW,GAAE,MAAU,GACtB,MAAM,EAAE,CAeV;AAED;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,CAAC;AACjD,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,SAAS,GAAG,WAAW,CAAC;AAChE,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;AAEvD,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,WAAW,CAAC;IACpB,SAAS,EAAE,aAAa,CAAC;IACzB,OAAO,EAAE,YAAY,CAAC;CACvB;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,aAAa,GAAG,YAAY,CAiBvE"}

package/dist/sound-bridge.js

@@ -0,0 +1,128 @@
+/**
+ * SoundArt → Code Mode Bridge
+ *
+ * This module injects sound-derived parameters into the Code Mode runtime
+ * as read-only `S.*` globals. It is the integration layer between sound
+ * analysis and generative art rendering.
+ *
+ * Usage in Code Mode sketches:
+ *   S.volume     // 0-100: Overall loudness
+ *   S.bass       // 0-100: Bass frequency energy
+ *   S.treble     // 0-100: Treble frequency energy
+ *   S.aggression // 0-100: Intensity/harshness
+ *   S.t          // 0-1: Normalized time position
+ *   etc.
+ */
+import { createEmptySoundSnapshot, freezeSoundSnapshot } from '../../shared/soundSnapshot';
+/**
+ * Create a frozen, read-only sound globals object from a snapshot
+ */
+export function createSoundGlobals(snapshot) {
+    return freezeSoundSnapshot(snapshot);
+}
+/**
+ * Create empty/default sound globals for testing or fallback
+ */
+export function createEmptySoundGlobals() {
+    return freezeSoundSnapshot(createEmptySoundSnapshot());
+}
+/**
+ * Inject sound globals into the p5 runtime context
+ *
+ * This adds the `S` global object to the runtime so sketches can access
+ * sound-derived parameters like S.volume, S.bass, etc.
+ *
+ * @param runtime - The p5 runtime object
+ * @param snapshot - The sound snapshot to inject
+ * @returns The runtime with S globals added
+ */
+export function injectSoundGlobals(runtime, snapshot) {
+    const globals = createSoundGlobals(snapshot);
+    // Create a proxy to make S immutable and prevent modification
+    const immutableS = new Proxy(globals, {
+        set() {
+            console.warn('[SoundBridge] S.* globals are read-only');
+            return false;
+        },
+        deleteProperty() {
+            console.warn('[SoundBridge] Cannot delete S.* properties');
+            return false;
+        },
+        defineProperty() {
+            console.warn('[SoundBridge] Cannot define new S.* properties');
+            return false;
+        }
+    });
+    return {
+        ...runtime,
+        S: immutableS
+    };
+}
+/**
+ * Helper function to map S.* values to useful ranges
+ *
+ * Usage in sketches:
+ *   const density = mapSound(S.volume, 100, 2000) // Map 0-100 to 100-2000
+ */
+export function createSoundHelpers() {
+    return {
+        /**
+         * Map a sound value (0-100) to a custom range
+         */
+        mapSound: (value, outMin, outMax) => {
+            return outMin + (value / 100) * (outMax - outMin);
+        },
+        /**
+         * Map a sound value (0-100) with easing
+         */
+        mapSoundEased: (value, outMin, outMax, easing = 2) => {
+            const t = Math.pow(value / 100, easing);
+            return outMin + t * (outMax - outMin);
+        },
+        /**
+         * Get a value that oscillates based on sound
+         */
+        soundOscillate: (base, amplitude, soundValue) => {
+            return base + Math.sin(soundValue * Math.PI / 50) * amplitude;
+        }
+    };
+}
+/**
+ * Convert SoundSnapshot hue (0-100) to degrees (0-360)
+ */
+export function hueToDegrees(hue) {
+    return (hue / 100) * 360;
+}
+/**
+ * Generate a color palette from sound parameters
+ *
+ * @param snapshot - The sound snapshot
+ * @param paletteSize - Number of colors to generate
+ * @returns Array of HSL color strings
+ */
+export function generateSoundPalette(snapshot, paletteSize = 6) {
+    const mainHue = hueToDegrees(snapshot.hue);
+    const hueShift = 20 + (snapshot.harmonicity / 100) * 40; // 20-60 degrees
+    const sat = 60 + (snapshot.treble / 100) * 30; // 60-90%
+    const light = 70 + (snapshot.bass / 100) * 25; // 70-95%
+    const palette = [];
+    for (let i = 0; i < paletteSize; i++) {
+        const hue = (mainHue + i * hueShift) % 360;
+        const satVar = sat - (i % 2) * 10;
+        const lightVar = light - (i % 3) * 5;
+        palette.push(`hsl(${hue}, ${satVar}%, ${lightVar}%)`);
+    }
+    return palette;
+}
+export function inferGenreProfile(snapshot) {
+    // Energy based on volume and aggression
+    const energy = (snapshot.volume > 60 || snapshot.aggression > 60) ? 'high' :
+        (snapshot.volume > 30) ? 'mid' : 'low';
+    // Structure based on rhythmicity and aggression
+    const structure = (snapshot.rhythmicity > 50 && snapshot.dynamicRange < 25) ? 'geometric' :
+        (snapshot.aggression > 60 && snapshot.dynamicRange > 50) ? 'chaotic' : 'organic';
+    // Clarity based on brightness
+    const clarity = (snapshot.brightness > 60) ? 'sharp' :
+        (snapshot.brightness > 40) ? 'clear' : 'muddy';
+    return { energy, structure, clarity };
+}

package/dist/soundart-engine.d.ts

@@ -0,0 +1,87 @@
+/**
+ * SoundArt → Code Mode Engine
+ *
+ * This is the orchestrator that runs SoundArt styles through the Code Mode engine.
+ * It replaces the old Canvas2D-based SoundArt renderer with a Code Mode pipeline.
+ *
+ * Architecture:
+ *   1. Sound analysis produces SoundFeatures (unchanged)
+ *   2. SoundFeatures → SoundSnapshot conversion
+ *   3. SoundSnapshot injected as S.* globals into Code Mode
+ *   4. SoundArt sketch executed via Code Mode runtime
+ *   5. Result: PNG or MP4 output
+ */
+import type { SoundSnapshot, SoundFeatures } from '../../shared/soundSnapshot';
+import { type SoundArtSketchName } from './soundart-sketches';
+export interface TweakParams {
+    volumeRangeFactor?: number;
+    centroidBrightnessFactor?: number;
+    aggressionPaletteFactor?: number;
+    rhythmPatternFactor?: number;
+    harmonySmoothnessFactor?: number;
+    attackSharpnessFactor?: number;
+    dynamicRangeVariationFactor?: number;
+    bassThicknessFactor?: number;
+    trebleSharpnessFactor?: number;
+}
+export interface SoundArtEngineConfig {
+    width: number;
+    height: number;
+    seed?: number;
+    backgroundMode?: 'rgb' | 'black' | 'white';
+    tweakParams?: TweakParams;
+}
+export interface SoundArtRenderOptions {
+    style: SoundArtSketchName;
+    sound: SoundFeatures;
+    canvas: HTMLCanvasElement;
+    config: SoundArtEngineConfig;
+    onProgress?: (progress: number) => void;
+}
+export interface SoundArtRenderResult {
+    style: SoundArtSketchName;
+    mode: 'soundart';
+    snapshot: SoundSnapshot;
+    metadata: SoundArtMetadata;
+}
+export interface SoundArtMetadata {
+    mode: 'SoundArt';
+    style: SoundArtSketchName;
+    timestamp: string;
+    soundFeatures: {
+        duration: number;
+        amplitude: number;
+        frequency: number;
+        bass: number;
+        treble: number;
+        aggression: number;
+    };
+    effects: {
+        timeFilter: boolean;
+        backgroundMode: string;
+    };
+    generationParams: {
+        seed: number;
+        canvasSize: {
+            width: number;
+            height: number;
+        };
+    };
+}
+/**
+ * Render a SoundArt style using Code Mode
+ *
+ * This is the main entry point for the new SoundArt → Code Mode pipeline.
+ */
+export declare function renderSoundArtViaCodeMode(options: SoundArtRenderOptions): Promise<SoundArtRenderResult>;
+/**
+ * Check if a SoundArt style can be rendered via Code Mode
+ */
+export declare function canRenderViaCodeMode(style: SoundArtSketchName): boolean;
+/**
+ * Get the list of SoundArt styles available via Code Mode
+ */
+export declare function getCodeModeAvailableStyles(): SoundArtSketchName[];
+export type { SoundSnapshot, SoundFeatures } from '../../shared/soundSnapshot';
+export type { SoundArtSketchName } from './soundart-sketches';
+//# sourceMappingURL=soundart-engine.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"soundart-engine.d.ts","sourceRoot":"","sources":["../soundart-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAI/E,OAAO,EAAqB,KAAK,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAEjF,MAAM,WAAW,WAAW;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,2BAA2B,CAAC,EAAE,MAAM,CAAC;IACrC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,cAAc,CAAC,EAAE,KAAK,GAAG,OAAO,GAAG,OAAO,CAAC;IAC3C,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,kBAAkB,CAAC;IAC1B,KAAK,EAAE,aAAa,CAAC;IACrB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,MAAM,EAAE,oBAAoB,CAAC;IAC7B,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;CACzC;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,kBAAkB,CAAC;IAC1B,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE,aAAa,CAAC;IACxB,QAAQ,EAAE,gBAAgB,CAAC;CAC5B;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,UAAU,CAAC;IACjB,KAAK,EAAE,kBAAkB,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE;QACb,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC;IACF,OAAO,EAAE;QACP,UAAU,EAAE,OAAO,CAAC;QACpB,cAAc,EAAE,MAAM,CAAC;KACxB,CAAC;IACF,gBAAgB,EAAE;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,UAAU,EAAE;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,CAAC;KAC/C,CAAC;CACH;AAqCD;;;;GAIG;AACH,wBAAsB,yBAAyB,CAC7C,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,oBAAoB,CAAC,CAoG/B;AA4BD;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAEvE;AAED;;GAEG;AACH,wBAAgB,0BAA0B,IAAI,kBAAkB,EAAE,CAGjE;AAGD,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC/E,YAAY,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC"}