@nexart/codemode-sdk 1.0.1 → 1.1.1

package/dist/p5-runtime.js

@@ -1,11 +1,97 @@
 /**
  * NexArt Code Mode Runtime SDK - p5-like Runtime
- * Version: 0.1.1
  *
- * Minimal p5.js-like runtime for deterministic generative art execution.
- * This is a headless runtime - no UI dependencies.
+ * ╔══════════════════════════════════════════════════════════════════════════╗
+ * ║  CODE MODE PROTOCOL v1.0.0 (Phase 1) — LOCKED                            ║
+ * ║                                                                          ║
+ * ║  Status: HARD PROTOCOL ENFORCEMENT                                       ║
+ * ║  This is the stable, canonical execution surface.                        ║
+ * ║  SDKs, ByX, and external builders can depend on this API.                ║
+ * ║                                                                          ║
+ * ║  Phase 1 Surface:                                                        ║
+ * ║  - VAR[0..9]: 10 read-only protocol variables (0-100 range)              ║
+ * ║  - Drawing: line, rect, ellipse, circle, triangle, quad, arc, etc.       ║
+ * ║  - Style: fill, stroke, colorMode, strokeWeight                          ║
+ * ║  - Transform: push, pop, translate, rotate, scale                        ║
+ * ║  - Random: random(), randomSeed(), randomGaussian() (seeded)             ║
+ * ║  - Noise: noise(), noiseSeed(), noiseDetail() (seeded)                   ║
+ * ║  - Math: map, constrain, lerp, lerpColor, dist, mag, norm                ║
+ * ║  - Color: Full CSS format support, color extraction functions            ║
+ * ║  - Time: frameCount, t, time, tGlobal                                    ║
+ * ║                                                                          ║
+ * ║  Determinism Guarantees:                                                 ║
+ * ║  - Same code + same seed + same VARs = identical output                  ║
+ * ║  - No external state, no browser entropy, no time-based drift            ║
+ * ║  - Randomness ONLY from: random(), noise() (both seeded)                 ║
+ * ║                                                                          ║
+ * ║  ⚠️  Future changes require Phase 2+                                     ║
+ * ╚══════════════════════════════════════════════════════════════════════════╝
  */
-export function createP5Runtime(canvas, width, height) {
+/**
+ * Code Mode Protocol Version
+ * This constant defines the locked protocol version.
+ * Changes to the execution surface require a version bump.
+ */
+export const CODE_MODE_PROTOCOL_VERSION = '1.0.0';
+export const CODE_MODE_PROTOCOL_PHASE = 1;
+export const CODE_MODE_ENFORCEMENT = 'HARD';
+/**
+ * Create a seeded random number generator (Mulberry32)
+ * Same algorithm used in SoundArt for consistency
+ */
+function createSeededRNG(seed = 123456) {
+    let a = seed >>> 0;
+    return () => {
+        a += 0x6D2B79F5;
+        let t = Math.imul(a ^ (a >>> 15), a | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+/**
+ * Create improved Perlin-like noise with seeding support
+ */
+function createSeededNoise(seed = 0) {
+    const permutation = [];
+    const rng = createSeededRNG(seed);
+    for (let i = 0; i < 256; i++) {
+        permutation[i] = i;
+    }
+    for (let i = 255; i > 0; i--) {
+        const j = Math.floor(rng() * (i + 1));
+        [permutation[i], permutation[j]] = [permutation[j], permutation[i]];
+    }
+    for (let i = 0; i < 256; i++) {
+        permutation[256 + i] = permutation[i];
+    }
+    const fade = (t) => t * t * t * (t * (t * 6 - 15) + 10);
+    const lerp = (a, b, t) => a + t * (b - a);
+    const grad = (hash, x, y, z) => {
+        const h = hash & 15;
+        const u = h < 8 ? x : y;
+        const v = h < 4 ? y : h === 12 || h === 14 ? x : z;
+        return ((h & 1) === 0 ? u : -u) + ((h & 2) === 0 ? v : -v);
+    };
+    return (x, y = 0, z = 0) => {
+        const X = Math.floor(x) & 255;
+        const Y = Math.floor(y) & 255;
+        const Z = Math.floor(z) & 255;
+        x -= Math.floor(x);
+        y -= Math.floor(y);
+        z -= Math.floor(z);
+        const u = fade(x);
+        const v = fade(y);
+        const w = fade(z);
+        const A = permutation[X] + Y;
+        const AA = permutation[A] + Z;
+        const AB = permutation[A + 1] + Z;
+        const B = permutation[X + 1] + Y;
+        const BA = permutation[B] + Z;
+        const BB = permutation[B + 1] + Z;
+        return (lerp(lerp(lerp(grad(permutation[AA], x, y, z), grad(permutation[BA], x - 1, y, z), u), lerp(grad(permutation[AB], x, y - 1, z), grad(permutation[BB], x - 1, y - 1, z), u), v), lerp(lerp(grad(permutation[AA + 1], x, y, z - 1), grad(permutation[BA + 1], x - 1, y, z - 1), u), lerp(grad(permutation[AB + 1], x, y - 1, z - 1), grad(permutation[BB + 1], x - 1, y - 1, z - 1), u), v), w) + 1) / 2;
+    };
+}
+export function createP5Runtime(canvas, width, height, config) {
     const ctx = canvas.getContext('2d', { willReadFrequently: true });
     let currentFill = 'rgba(255, 255, 255, 1)';
     let currentStroke = 'rgba(0, 0, 0, 1)';
@@ -14,14 +100,119 @@ export function createP5Runtime(canvas, width, height) {
     let currentStrokeWeight = 1;
     let colorModeSettings = { mode: 'RGB', maxR: 255, maxG: 255, maxB: 255, maxA: 255 };
     let shapeStarted = false;
+    // Seeded random state
+    let randomSeedValue = config?.seed ?? Math.floor(Math.random() * 2147483647);
+    let rng = createSeededRNG(randomSeedValue);
+    // Seeded noise state
+    let noiseSeedValue = config?.seed ?? 0;
+    let noiseFunc = createSeededNoise(noiseSeedValue);
+    let noiseOctaves = 4;
+    let noiseFalloff = 0.5;
+    /**
+     * Parse CSS color string to normalized RGBA values
+     * Supports: hex (#RGB, #RRGGBB, #RRGGBBAA), rgb(), rgba(), hsl(), hsla()
+     */
+    const parseCssColor = (str) => {
+        const s = str.trim();
+        // Hex format: #RGB, #RRGGBB, #RRGGBBAA
+        if (s.startsWith('#')) {
+            const hex = s.slice(1);
+            if (hex.length === 3) {
+                const r = parseInt(hex[0] + hex[0], 16);
+                const g = parseInt(hex[1] + hex[1], 16);
+                const b = parseInt(hex[2] + hex[2], 16);
+                return { r, g, b, a: 1 };
+            }
+            else if (hex.length === 6) {
+                const r = parseInt(hex.slice(0, 2), 16);
+                const g = parseInt(hex.slice(2, 4), 16);
+                const b = parseInt(hex.slice(4, 6), 16);
+                return { r, g, b, a: 1 };
+            }
+            else if (hex.length === 8) {
+                const r = parseInt(hex.slice(0, 2), 16);
+                const g = parseInt(hex.slice(2, 4), 16);
+                const b = parseInt(hex.slice(4, 6), 16);
+                const a = parseInt(hex.slice(6, 8), 16) / 255;
+                return { r, g, b, a };
+            }
+        }
+        // rgb(r, g, b) or rgb(r g b)
+        const rgbMatch = s.match(/^rgb\s*\(\s*(\d+)\s*[,\s]\s*(\d+)\s*[,\s]\s*(\d+)\s*\)$/i);
+        if (rgbMatch) {
+            return {
+                r: parseInt(rgbMatch[1]),
+                g: parseInt(rgbMatch[2]),
+                b: parseInt(rgbMatch[3]),
+                a: 1
+            };
+        }
+        // rgba(r, g, b, a) or rgba(r g b / a)
+        const rgbaMatch = s.match(/^rgba\s*\(\s*(\d+)\s*[,\s]\s*(\d+)\s*[,\s]\s*(\d+)\s*[,\/\s]\s*([\d.]+)\s*\)$/i);
+        if (rgbaMatch) {
+            return {
+                r: parseInt(rgbaMatch[1]),
+                g: parseInt(rgbaMatch[2]),
+                b: parseInt(rgbaMatch[3]),
+                a: parseFloat(rgbaMatch[4])
+            };
+        }
+        // hsl(h, s%, l%) or hsla(h, s%, l%, a)
+        const hslMatch = s.match(/^hsla?\s*\(\s*([\d.]+)\s*[,\s]\s*([\d.]+)%?\s*[,\s]\s*([\d.]+)%?\s*(?:[,\/\s]\s*([\d.]+))?\s*\)$/i);
+        if (hslMatch) {
+            const h = parseFloat(hslMatch[1]) / 360;
+            const sat = parseFloat(hslMatch[2]) / 100;
+            const l = parseFloat(hslMatch[3]) / 100;
+            const a = hslMatch[4] ? parseFloat(hslMatch[4]) : 1;
+            // HSL to RGB conversion
+            let r, g, b;
+            if (sat === 0) {
+                r = g = b = l;
+            }
+            else {
+                const hue2rgb = (p, q, t) => {
+                    if (t < 0)
+                        t += 1;
+                    if (t > 1)
+                        t -= 1;
+                    if (t < 1 / 6)
+                        return p + (q - p) * 6 * t;
+                    if (t < 1 / 2)
+                        return q;
+                    if (t < 2 / 3)
+                        return p + (q - p) * (2 / 3 - t) * 6;
+                    return p;
+                };
+                const q = l < 0.5 ? l * (1 + sat) : l + sat - l * sat;
+                const p = 2 * l - q;
+                r = hue2rgb(p, q, h + 1 / 3);
+                g = hue2rgb(p, q, h);
+                b = hue2rgb(p, q, h - 1 / 3);
+            }
+            return {
+                r: Math.round(r * 255),
+                g: Math.round(g * 255),
+                b: Math.round(b * 255),
+                a
+            };
+        }
+        return null;
+    };
     const parseColor = (...args) => {
         if (args.length === 0)
             return 'rgba(0, 0, 0, 1)';
         const { mode, maxR, maxG, maxB, maxA } = colorModeSettings;
         if (args.length === 1) {
             const val = args[0];
-            if (typeof val === 'string')
+            if (typeof val === 'string') {
+                // Try to parse CSS color formats
+                const parsed = parseCssColor(val);
+                if (parsed) {
+                    return `rgba(${parsed.r}, ${parsed.g}, ${parsed.b}, ${parsed.a})`;
+                }
+                // Return as-is for named colors (canvas handles them)
                 return val;
+            }
             if (mode === 'HSB') {
                 return `hsla(${val}, 100%, 50%, 1)`;
             }
@@ -112,7 +303,71 @@ export function createP5Runtime(canvas, width, height) {
         },
         color: (...args) => parseColor(...args),
         lerpColor: (c1, c2, amt) => {
-            return c1; // Simplified - full implementation would blend colors
+            // Parse both colors
+            const color1 = parseCssColor(c1) || { r: 0, g: 0, b: 0, a: 1 };
+            const color2 = parseCssColor(c2) || { r: 255, g: 255, b: 255, a: 1 };
+            // Linearly interpolate each channel
+            const r = Math.round(color1.r + (color2.r - color1.r) * amt);
+            const g = Math.round(color1.g + (color2.g - color1.g) * amt);
+            const b = Math.round(color1.b + (color2.b - color1.b) * amt);
+            const a = color1.a + (color2.a - color1.a) * amt;
+            return `rgba(${r}, ${g}, ${b}, ${a})`;
+        },
+        red: (color) => {
+            const parsed = parseCssColor(color);
+            return parsed ? parsed.r : 0;
+        },
+        green: (color) => {
+            const parsed = parseCssColor(color);
+            return parsed ? parsed.g : 0;
+        },
+        blue: (color) => {
+            const parsed = parseCssColor(color);
+            return parsed ? parsed.b : 0;
+        },
+        alpha: (color) => {
+            const parsed = parseCssColor(color);
+            return parsed ? parsed.a * 255 : 255;
+        },
+        brightness: (color) => {
+            const parsed = parseCssColor(color);
+            if (!parsed)
+                return 0;
+            return Math.max(parsed.r, parsed.g, parsed.b) / 255 * 100;
+        },
+        saturation: (color) => {
+            const parsed = parseCssColor(color);
+            if (!parsed)
+                return 0;
+            const max = Math.max(parsed.r, parsed.g, parsed.b);
+            const min = Math.min(parsed.r, parsed.g, parsed.b);
+            if (max === 0)
+                return 0;
+            return ((max - min) / max) * 100;
+        },
+        hue: (color) => {
+            const parsed = parseCssColor(color);
+            if (!parsed)
+                return 0;
+            const { r, g, b } = parsed;
+            const max = Math.max(r, g, b);
+            const min = Math.min(r, g, b);
+            if (max === min)
+                return 0;
+            let h = 0;
+            const d = max - min;
+            switch (max) {
+                case r:
+                    h = ((g - b) / d + (g < b ? 6 : 0)) / 6;
+                    break;
+                case g:
+                    h = ((b - r) / d + 2) / 6;
+                    break;
+                case b:
+                    h = ((r - g) / d + 4) / 6;
+                    break;
+            }
+            return h * 360;
         },
         // Shape functions
         ellipse: (x, y, w, h) => {
@@ -242,30 +497,53 @@ export function createP5Runtime(canvas, width, height) {
         resetMatrix: () => {
             ctx.setTransform(1, 0, 0, 1, 0, 0);
         },
-        // Math functions
+        // Math functions - SEEDED for determinism
         random: (min, max) => {
+            // Support random() with arrays
+            if (Array.isArray(min)) {
+                return min[Math.floor(rng() * min.length)];
+            }
             if (min === undefined)
-                return Math.random();
+                return rng();
             if (max === undefined)
-                return Math.random() * min;
-            return min + Math.random() * (max - min);
+                return rng() * min;
+            return min + rng() * (max - min);
         },
         randomSeed: (seed) => {
-            // Simplified - would need proper seeded random
+            randomSeedValue = seed;
+            rng = createSeededRNG(seed);
+        },
+        randomGaussian: (mean = 0, sd = 1) => {
+            // Box-Muller transform for Gaussian distribution
+            const u1 = rng();
+            const u2 = rng();
+            const z0 = Math.sqrt(-2 * Math.log(u1)) * Math.cos(2 * Math.PI * u2);
+            return z0 * sd + mean;
         },
         noise: (x, y, z) => {
-            // Simplified Perlin-like noise
-            const hash = (n) => {
-                const s = Math.sin(n) * 43758.5453123;
-                return s - Math.floor(s);
-            };
-            const xVal = x ?? 0;
-            const yVal = y ?? 0;
-            const zVal = z ?? 0;
-            return hash(xVal * 12.9898 + yVal * 78.233 + zVal * 37.719);
+            // Use seeded Perlin noise with octaves
+            let total = 0;
+            let frequency = 1;
+            let amplitude = 1;
+            let maxValue = 0;
+            for (let i = 0; i < noiseOctaves; i++) {
+                total += noiseFunc(x * frequency, (y ?? 0) * frequency, (z ?? 0) * frequency) * amplitude;
+                maxValue += amplitude;
+                amplitude *= noiseFalloff;
+                frequency *= 2;
+            }
+            return total / maxValue;
+        },
+        noiseSeed: (seed) => {
+            noiseSeedValue = seed;
+            noiseFunc = createSeededNoise(seed);
+        },
+        noiseDetail: (lod, falloff) => {
+            noiseOctaves = Math.max(1, Math.min(8, lod));
+            if (falloff !== undefined) {
+                noiseFalloff = Math.max(0, Math.min(1, falloff));
+            }
         },
-        noiseSeed: (seed) => { },
-        noiseDetail: (lod, falloff) => { },
         map: (value, start1, stop1, start2, stop2) => {
             return start2 + (stop2 - start2) * ((value - start1) / (stop1 - start1));
         },
@@ -316,3 +594,51 @@ export function createP5Runtime(canvas, width, height) {
 export function injectTimeVariables(p, time) {
     p.frameCount = time.frameCount;
 }
+/**
+ * VAR Protocol Constants (Phase 1 — Protocol v1.0.0)
+ * SDK v1.0.2: VAR input is optional (0-10 elements), but runtime always has 10
+ */
+export const VAR_COUNT = 10; // Exactly 10 protocol variables: VAR[0..9]
+export const VAR_MIN = 0; // Minimum value
+export const VAR_MAX = 100; // Maximum value (normalized range)
+/**
+ * Create a protected, read-only VAR array for protocol execution.
+ *
+ * SDK v1.0.2 Rules (Protocol v1.0.0):
+ * - Input accepts 0-10 elements
+ * - Runtime VAR is ALWAYS 10 elements (padded with zeros)
+ * - Values are numeric, must be in 0-100 range (validated upstream)
+ * - Read-only: writes throw descriptive errors
+ * - Available in both setup() and draw()
+ */
+export function createProtocolVAR(vars) {
+    // Create frozen 10-element array (upstream normalizeVars ensures this)
+    const normalizedVars = [];
+    for (let i = 0; i < VAR_COUNT; i++) {
+        normalizedVars[i] = vars?.[i] ?? 0;
+    }
+    // Freeze the array to prevent modifications
+    const frozenVars = Object.freeze(normalizedVars);
+    // Wrap in Proxy for descriptive error messages on write attempts
+    return new Proxy(frozenVars, {
+        set(_target, prop, _value) {
+            const propName = typeof prop === 'symbol' ? prop.toString() : prop;
+            throw new Error(`[Code Mode Protocol Error] VAR is read-only. ` +
+                `Cannot write to VAR[${propName}]. ` +
+                `VAR[0..9] are protocol inputs, not sketch state.`);
+        },
+        deleteProperty(_target, prop) {
+            const propName = typeof prop === 'symbol' ? prop.toString() : prop;
+            throw new Error(`[Code Mode Protocol Error] VAR is read-only. ` +
+                `Cannot delete VAR[${propName}].`);
+        },
+        defineProperty(_target, prop) {
+            const propName = typeof prop === 'symbol' ? prop.toString() : prop;
+            throw new Error(`[Code Mode Protocol Error] Cannot define new VAR properties. ` +
+                `VAR is fixed at 10 elements (VAR[0..9]). Attempted: ${propName}`);
+        },
+    });
+}
+export function injectProtocolVariables(p, vars) {
+    p.VAR = createProtocolVAR(vars);
+}

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 };
+}