machinaos 0.0.76 → 0.0.78

package/client/src/lib/sound.ts

@@ -0,0 +1,393 @@
+/**
+ * sound.ts — per-theme WebAudio sound packs.
+ *
+ * Synthesizes click / hover / type / success / error / run / save /
+ * modalOpen / modalClose events via a single OscillatorNode + GainNode
+ * per call. No external samples; no module-level audio context until
+ * the first play(). Off by default — toggle with `Sounds.setEnabled`.
+ *
+ * The active pack is selected by name (matches the per-theme
+ * `--sound-pack` CSS token). React glue lives in
+ * client/src/hooks/useSound.ts which:
+ *   1. Reads `--sound-pack` from `:root` whenever the active theme
+ *      changes and calls `Sounds.setPack(...)`.
+ *   2. Wires `Sounds.setEnabled(...)` to the `soundEnabled` Zustand
+ *      slice (persisted to localStorage as `machinaos-sound`).
+ *
+ * Ported from design_handoff_machinaos_themes/app/sound.js. The DOM
+ * autocapture (`document.addEventListener('click', ...)`) at the
+ * bottom of the upstream module is intentionally dropped — in React
+ * we fire `play()` from explicit handlers (ActionButton onClick,
+ * Modal open/close effect, etc.) so the side-effect surface is
+ * traceable.
+ */
+
+export type SoundEvent =
+  | 'click'
+  | 'hover'
+  | 'type'
+  | 'success'
+  | 'error'
+  | 'run'
+  | 'save'
+  | 'modalOpen'
+  | 'modalClose';
+
+export type SoundPackName =
+  | 'none'
+  | 'parchment'
+  | 'marble'
+  | 'ink'
+  | 'clockwork'
+  | 'vibraphone'
+  | 'terminal'
+  | 'scrap'
+  | 'crypt'
+  | 'bell'
+  | 'telex';
+
+interface OscConfig {
+  type: OscillatorType;
+  freq: number;
+  dur: number;
+  vol: number;
+  attack: number;
+  decay: number;
+  /** Optional low-pass filter cutoff (Hz). */
+  lp?: number;
+  /** Optional frequency sweep multiplier; final = freq * sweep. */
+  sweep?: number;
+}
+
+type EventTable = Partial<Record<SoundEvent, OscConfig>>;
+
+// Singleton AudioContext lazily constructed on first play.
+let audioCtx: AudioContext | null = null;
+function ensureCtx(): AudioContext | null {
+  if (audioCtx) return audioCtx;
+  try {
+    const Ctx = window.AudioContext || (window as any).webkitAudioContext;
+    if (!Ctx) return null;
+    audioCtx = new Ctx();
+    return audioCtx;
+  } catch {
+    return null;
+  }
+}
+
+let enabled = false;
+let activePackName: SoundPackName = 'none';
+let activePack: EventTable = {};
+
+/**
+ * Per-event last-fire timestamps for throttling. Currently only `type`
+ * is throttled — rapid typing into a long input shouldn't queue dozens
+ * of OscillatorNodes per second. Other events (click, hover, success,
+ * etc.) are user-paced and don't need throttling.
+ *
+ * Uses `performance.now()` for monotonic timing. The 30 ms window
+ * matches the upstream `app/sound.js` reference engine's documented
+ * hover debounce; we apply the same to `type` since each oscillator
+ * costs ~25 ms decay on the parchment / marble packs.
+ */
+const lastFireMs: Partial<Record<SoundEvent, number>> = {};
+const THROTTLE_MS: Partial<Record<SoundEvent, number>> = {
+  type: 30,
+  hover: 30,
+};
+
+function play(cfg: OscConfig | undefined): void {
+  if (!cfg || !enabled) return;
+  const ac = ensureCtx();
+  if (!ac) return;
+  // If suspended, defer oscillator scheduling until resume() settles.
+  // Synchronously scheduled oscillators on a suspended context are
+  // silently dropped per the WebAudio autoplay policy
+  // (https://developer.chrome.com/blog/autoplay/#webaudio).
+  const schedule = () => {
+    try {
+      const osc = ac.createOscillator();
+      const gain = ac.createGain();
+      osc.type = cfg.type;
+      osc.frequency.value = cfg.freq;
+      let target: AudioNode = osc;
+      if (cfg.lp) {
+        const lp = ac.createBiquadFilter();
+        lp.type = 'lowpass';
+        lp.frequency.value = cfg.lp;
+        target.connect(lp);
+        target = lp;
+      }
+      target.connect(gain);
+      gain.connect(ac.destination);
+      const now = ac.currentTime;
+      gain.gain.setValueAtTime(0, now);
+      gain.gain.linearRampToValueAtTime(cfg.vol, now + cfg.attack);
+      gain.gain.exponentialRampToValueAtTime(0.0001, now + cfg.attack + cfg.decay);
+      if (cfg.sweep) {
+        osc.frequency.exponentialRampToValueAtTime(cfg.freq * cfg.sweep, now + cfg.dur);
+      }
+      osc.start(now);
+      osc.stop(now + cfg.dur + 0.02);
+    } catch {
+      // WebAudio errors are non-fatal — silently drop.
+    }
+  };
+  if (ac.state === 'running') {
+    schedule();
+  } else {
+    void Promise.resolve(ac.resume()).then(schedule).catch(() => {/* noop */});
+  }
+}
+
+// ── Sound packs ──────────────────────────────────────────────────────────
+//
+// Each pack maps each `SoundEvent` to an oscillator config. Volume is
+// kept ≤ 0.10 across the board so no pack clips. Configs are ported
+// verbatim from app/sound.js (handoff bundle).
+
+const PARCHMENT: EventTable = {
+  click:      { type: 'sine',     freq: 220, dur: 0.04,  vol: 0.06, attack: 0.005, decay: 0.04 },
+  hover:      { type: 'triangle', freq: 380, dur: 0.02,  vol: 0.025, attack: 0.002, decay: 0.02 },
+  type:       { type: 'square',   freq: 180, dur: 0.025, vol: 0.04, attack: 0.001, decay: 0.025, lp: 800 },
+  success:    { type: 'sine',     freq: 523, dur: 0.4,   vol: 0.08, attack: 0.01,  decay: 0.4,  sweep: 1.5 },
+  error:      { type: 'sawtooth', freq: 110, dur: 0.25,  vol: 0.10, attack: 0.005, decay: 0.25, lp: 600 },
+  run:        { type: 'sine',     freq: 392, dur: 0.18,  vol: 0.10, attack: 0.01,  decay: 0.18, sweep: 1.3 },
+  save:       { type: 'triangle', freq: 294, dur: 0.3,   vol: 0.10, attack: 0.02,  decay: 0.3 },
+  modalOpen:  { type: 'sine',     freq: 392, dur: 0.18,  vol: 0.07, attack: 0.02,  decay: 0.18, sweep: 1.2 },
+  modalClose: { type: 'sine',     freq: 392, dur: 0.14,  vol: 0.06, attack: 0.005, decay: 0.14, sweep: 0.7 },
+};
+
+const MARBLE: EventTable = {
+  click:      { type: 'sine',     freq: 330, dur: 0.05,  vol: 0.07, attack: 0.001, decay: 0.05 },
+  hover:      { type: 'sine',     freq: 520, dur: 0.02,  vol: 0.025, attack: 0.001, decay: 0.02 },
+  type:       { type: 'triangle', freq: 260, dur: 0.03,  vol: 0.04, attack: 0.001, decay: 0.03, lp: 1200 },
+  success:    { type: 'sine',     freq: 392, dur: 0.5,   vol: 0.09, attack: 0.005, decay: 0.5,  sweep: 1.6 },
+  error:      { type: 'sawtooth', freq: 130, dur: 0.30,  vol: 0.10, attack: 0.005, decay: 0.30, lp: 500 },
+  run:        { type: 'sine',     freq: 440, dur: 0.22,  vol: 0.10, attack: 0.005, decay: 0.22, sweep: 1.4 },
+  save:       { type: 'sine',     freq: 330, dur: 0.35,  vol: 0.10, attack: 0.01,  decay: 0.35 },
+  modalOpen:  { type: 'sine',     freq: 392, dur: 0.20,  vol: 0.07, attack: 0.02,  decay: 0.20, sweep: 1.3 },
+  modalClose: { type: 'sine',     freq: 392, dur: 0.16,  vol: 0.06, attack: 0.005, decay: 0.16, sweep: 0.7 },
+};
+
+const INK: EventTable = {
+  click:      { type: 'triangle', freq: 280, dur: 0.05,  vol: 0.05, attack: 0.005, decay: 0.05, lp: 1500 },
+  hover:      { type: 'sine',     freq: 440, dur: 0.018, vol: 0.02, attack: 0.001, decay: 0.018 },
+  type:       { type: 'sine',     freq: 220, dur: 0.04,  vol: 0.04, attack: 0.005, decay: 0.04, lp: 600 },
+  success:    { type: 'sine',     freq: 660, dur: 1.2,   vol: 0.08, attack: 0.01,  decay: 1.2 },
+  error:      { type: 'triangle', freq: 174, dur: 0.4,   vol: 0.08, attack: 0.005, decay: 0.4,  lp: 800 },
+  run:        { type: 'sine',     freq: 523, dur: 0.6,   vol: 0.08, attack: 0.02,  decay: 0.6 },
+  save:       { type: 'sine',     freq: 440, dur: 0.8,   vol: 0.10, attack: 0.01,  decay: 0.8 },
+  modalOpen:  { type: 'sine',     freq: 523, dur: 0.4,   vol: 0.06, attack: 0.04,  decay: 0.4 },
+  modalClose: { type: 'sine',     freq: 392, dur: 0.4,   vol: 0.05, attack: 0.005, decay: 0.4 },
+};
+
+const CLOCKWORK: EventTable = {
+  click:      { type: 'square',   freq: 800,  dur: 0.04,  vol: 0.06, attack: 0.001, decay: 0.04,  lp: 2200 },
+  hover:      { type: 'square',   freq: 1100, dur: 0.012, vol: 0.02, attack: 0.001, decay: 0.012 },
+  type:       { type: 'square',   freq: 600,  dur: 0.025, vol: 0.05, attack: 0.001, decay: 0.025, lp: 1800 },
+  success:    { type: 'sawtooth', freq: 523,  dur: 0.5,   vol: 0.08, attack: 0.005, decay: 0.5,   sweep: 1.5, lp: 2500 },
+  error:      { type: 'sawtooth', freq: 196,  dur: 0.35,  vol: 0.10, attack: 0.005, decay: 0.35,  lp: 700 },
+  run:        { type: 'square',   freq: 440,  dur: 0.30,  vol: 0.10, attack: 0.005, decay: 0.30,  sweep: 1.4, lp: 2000 },
+  save:       { type: 'triangle', freq: 660,  dur: 0.45,  vol: 0.10, attack: 0.01,  decay: 0.45,  lp: 2400 },
+  modalOpen:  { type: 'square',   freq: 392,  dur: 0.18,  vol: 0.07, attack: 0.005, decay: 0.18,  sweep: 1.3, lp: 1800 },
+  modalClose: { type: 'square',   freq: 392,  dur: 0.14,  vol: 0.06, attack: 0.005, decay: 0.14,  sweep: 0.65, lp: 1400 },
+};
+
+const VIBRAPHONE: EventTable = {
+  click:      { type: 'triangle', freq: 880,  dur: 0.10, vol: 0.06, attack: 0.001, decay: 0.10 },
+  hover:      { type: 'triangle', freq: 1320, dur: 0.05, vol: 0.025, attack: 0.001, decay: 0.05 },
+  type:       { type: 'sine',     freq: 660,  dur: 0.06, vol: 0.04, attack: 0.001, decay: 0.06 },
+  success:    { type: 'triangle', freq: 988,  dur: 0.5,  vol: 0.09, attack: 0.001, decay: 0.5,  sweep: 1.5 },
+  error:      { type: 'sawtooth', freq: 233,  dur: 0.25, vol: 0.10, attack: 0.005, decay: 0.25, sweep: 0.6 },
+  run:        { type: 'triangle', freq: 1175, dur: 0.30, vol: 0.10, attack: 0.001, decay: 0.30, sweep: 1.4 },
+  save:       { type: 'triangle', freq: 880,  dur: 0.40, vol: 0.10, attack: 0.001, decay: 0.40 },
+  modalOpen:  { type: 'triangle', freq: 988,  dur: 0.18, vol: 0.06, attack: 0.001, decay: 0.18, sweep: 1.4 },
+  modalClose: { type: 'triangle', freq: 988,  dur: 0.18, vol: 0.06, attack: 0.001, decay: 0.18, sweep: 0.65 },
+};
+
+const TERMINAL: EventTable = {
+  click:      { type: 'square',   freq: 1200, dur: 0.025, vol: 0.06, attack: 0.001, decay: 0.025 },
+  hover:      { type: 'square',   freq: 1800, dur: 0.012, vol: 0.025, attack: 0.001, decay: 0.012 },
+  type:       { type: 'square',   freq: 880,  dur: 0.018, vol: 0.05, attack: 0.0005, decay: 0.018 },
+  success:    { type: 'square',   freq: 1318, dur: 0.18,  vol: 0.08, attack: 0.001, decay: 0.18,  sweep: 1.5 },
+  error:      { type: 'sawtooth', freq: 220,  dur: 0.18,  vol: 0.10, attack: 0.001, decay: 0.18,  sweep: 0.5 },
+  run:        { type: 'square',   freq: 1568, dur: 0.10,  vol: 0.10, attack: 0.001, decay: 0.10 },
+  save:       { type: 'square',   freq: 988,  dur: 0.12,  vol: 0.08, attack: 0.001, decay: 0.12,  sweep: 1.2 },
+  modalOpen:  { type: 'square',   freq: 1175, dur: 0.06,  vol: 0.06, attack: 0.001, decay: 0.06,  sweep: 1.4 },
+  modalClose: { type: 'square',   freq: 1175, dur: 0.06,  vol: 0.06, attack: 0.001, decay: 0.06,  sweep: 0.6 },
+};
+
+const SCRAP: EventTable = {
+  click:      { type: 'sawtooth', freq: 180, dur: 0.05,  vol: 0.07, attack: 0.0005, decay: 0.05,  lp: 1400 },
+  hover:      { type: 'sawtooth', freq: 320, dur: 0.012, vol: 0.025, attack: 0.0005, decay: 0.012, lp: 2000 },
+  type:       { type: 'square',   freq: 140, dur: 0.03,  vol: 0.05, attack: 0.0005, decay: 0.03,  lp: 800 },
+  success:    { type: 'sawtooth', freq: 440, dur: 0.18,  vol: 0.10, attack: 0.001,  decay: 0.18,  sweep: 1.3, lp: 1600 },
+  error:      { type: 'sawtooth', freq: 90,  dur: 0.5,   vol: 0.12, attack: 0.001,  decay: 0.5,   lp: 400 },
+  run:        { type: 'square',   freq: 220, dur: 0.20,  vol: 0.10, attack: 0.001,  decay: 0.20,  sweep: 1.2, lp: 1200 },
+  save:       { type: 'sawtooth', freq: 330, dur: 0.18,  vol: 0.10, attack: 0.001,  decay: 0.18,  lp: 1400 },
+  modalOpen:  { type: 'sawtooth', freq: 196, dur: 0.10,  vol: 0.07, attack: 0.001,  decay: 0.10,  lp: 1000 },
+  modalClose: { type: 'sawtooth', freq: 196, dur: 0.08,  vol: 0.06, attack: 0.001,  decay: 0.08,  sweep: 0.5, lp: 700 },
+};
+
+const CRYPT: EventTable = {
+  click:      { type: 'sine',     freq: 220, dur: 0.08,  vol: 0.06, attack: 0.005, decay: 0.08, lp: 600 },
+  hover:      { type: 'sine',     freq: 330, dur: 0.025, vol: 0.02, attack: 0.005, decay: 0.025, lp: 800 },
+  type:       { type: 'sine',     freq: 165, dur: 0.04,  vol: 0.04, attack: 0.005, decay: 0.04, lp: 400 },
+  success:    { type: 'triangle', freq: 261, dur: 0.8,   vol: 0.08, attack: 0.02,  decay: 0.8,  sweep: 1.5, lp: 1200 },
+  error:      { type: 'sawtooth', freq: 73,  dur: 0.6,   vol: 0.10, attack: 0.01,  decay: 0.6,  lp: 300 },
+  run:        { type: 'sine',     freq: 196, dur: 0.45,  vol: 0.10, attack: 0.02,  decay: 0.45, sweep: 1.3, lp: 800 },
+  save:       { type: 'sine',     freq: 174, dur: 0.7,   vol: 0.10, attack: 0.05,  decay: 0.7,  lp: 700 },
+  modalOpen:  { type: 'sine',     freq: 220, dur: 0.5,   vol: 0.07, attack: 0.05,  decay: 0.5,  lp: 600 },
+  modalClose: { type: 'sine',     freq: 220, dur: 0.4,   vol: 0.06, attack: 0.005, decay: 0.4,  sweep: 0.6, lp: 500 },
+};
+
+const BELL: EventTable = {
+  click:      { type: 'triangle', freq: 392, dur: 0.10,  vol: 0.06, attack: 0.001, decay: 0.10, lp: 1500 },
+  hover:      { type: 'sine',     freq: 660, dur: 0.025, vol: 0.025, attack: 0.001, decay: 0.025 },
+  type:       { type: 'square',   freq: 220, dur: 0.025, vol: 0.04, attack: 0.001, decay: 0.025, lp: 800 },
+  success:    { type: 'triangle', freq: 523, dur: 1.0,   vol: 0.09, attack: 0.001, decay: 1.0 },
+  error:      { type: 'sawtooth', freq: 110, dur: 0.6,   vol: 0.10, attack: 0.005, decay: 0.6,  lp: 500 },
+  run:        { type: 'triangle', freq: 440, dur: 0.6,   vol: 0.10, attack: 0.001, decay: 0.6 },
+  save:       { type: 'triangle', freq: 392, dur: 0.9,   vol: 0.10, attack: 0.001, decay: 0.9 },
+  modalOpen:  { type: 'triangle', freq: 523, dur: 0.4,   vol: 0.07, attack: 0.001, decay: 0.4 },
+  modalClose: { type: 'triangle', freq: 392, dur: 0.4,   vol: 0.06, attack: 0.001, decay: 0.4 },
+};
+
+const TELEX: EventTable = {
+  click:      { type: 'square',   freq: 1500, dur: 0.012, vol: 0.07, attack: 0.0005, decay: 0.012 },
+  hover:      { type: 'square',   freq: 2200, dur: 0.006, vol: 0.02, attack: 0.0005, decay: 0.006 },
+  type:       { type: 'square',   freq: 1100, dur: 0.010, vol: 0.05, attack: 0.0005, decay: 0.010 },
+  success:    { type: 'square',   freq: 1318, dur: 0.10,  vol: 0.08, attack: 0.0005, decay: 0.10 },
+  error:      { type: 'sawtooth', freq: 220,  dur: 0.4,   vol: 0.12, attack: 0.0005, decay: 0.4 },
+  run:        { type: 'square',   freq: 1760, dur: 0.06,  vol: 0.10, attack: 0.0005, decay: 0.06 },
+  save:       { type: 'square',   freq: 1175, dur: 0.08,  vol: 0.08, attack: 0.0005, decay: 0.08 },
+  modalOpen:  { type: 'square',   freq: 988,  dur: 0.05,  vol: 0.07, attack: 0.0005, decay: 0.05 },
+  modalClose: { type: 'square',   freq: 988,  dur: 0.04,  vol: 0.06, attack: 0.0005, decay: 0.04, sweep: 0.6 },
+};
+
+const PACKS: Record<SoundPackName, EventTable> = {
+  none: {},
+  parchment: PARCHMENT,
+  marble: MARBLE,
+  ink: INK,
+  clockwork: CLOCKWORK,
+  vibraphone: VIBRAPHONE,
+  terminal: TERMINAL,
+  scrap: SCRAP,
+  crypt: CRYPT,
+  bell: BELL,
+  telex: TELEX,
+};
+
+// ── Public API ───────────────────────────────────────────────────────────
+
+export const Sounds = {
+  setEnabled(value: boolean): void {
+    enabled = value;
+  },
+  isEnabled(): boolean {
+    return enabled;
+  },
+  setPack(name: SoundPackName): void {
+    activePackName = name;
+    activePack = PACKS[name] ?? PACKS.none;
+  },
+  pack(): SoundPackName {
+    return activePackName;
+  },
+  /**
+   * Idempotent gesture-time unlock. Constructs the AudioContext (if not
+   * already constructed) and resumes it if the browser autoplay policy
+   * left it `suspended`. Safe to call repeatedly — `resume()` on a
+   * running context is a no-op.
+   *
+   * Modern Chrome / Safari require the resume() call to occur inside
+   * the same task as a user gesture (pointerdown / keydown / touchstart).
+   * `Sounds.play()` defensively calls resume() too, but state-change-
+   * driven plays (e.g. modal open from an effect) can land microseconds
+   * after the gesture frame and lose the very first sound. Calling
+   * `unlock()` from a once-listener on the gesture path closes that gap.
+   */
+  unlock(): void {
+    const ac = ensureCtx();
+    if (!ac) return;
+    if (ac.state === 'suspended') void ac.resume();
+  },
+  play(event: SoundEvent): void {
+    const throttle = THROTTLE_MS[event];
+    if (throttle !== undefined) {
+      const now = typeof performance !== 'undefined' ? performance.now() : Date.now();
+      const last = lastFireMs[event] ?? 0;
+      if (now - last < throttle) return;
+      lastFireMs[event] = now;
+    }
+    play(activePack[event]);
+  },
+  /**
+   * Snapshot the engine state for DevTools self-diagnosis. Returns an
+   * object the user can inspect from the browser console:
+   *   `> Sounds.diagnose()` →
+   *     { enabled, pack, eventsForPack, audioContextState, browserSupport }
+   * Common silent-audio modes:
+   *   - `enabled: false` → user hasn't toggled Settings → Audio.
+   *   - `pack: 'none'` → :root[data-theme="..."] declares chime/typo
+   *     and the validator falls through to none.
+   *   - `audioContextState: 'suspended'` after a click → a browser
+   *     extension or autoplay-block policy is denying resume().
+   */
+  diagnose(): {
+    enabled: boolean;
+    pack: SoundPackName;
+    eventsForPack: string[];
+    cssSoundPack: string;
+    cssDataTheme: string | null;
+    audioContextState: string | 'no-ac' | 'no-audio-api';
+    browserSupport: boolean;
+  } {
+    const Ctx = typeof window !== 'undefined'
+      ? window.AudioContext || (window as any).webkitAudioContext
+      : undefined;
+    const cssSoundPack = typeof document !== 'undefined'
+      ? getComputedStyle(document.documentElement).getPropertyValue('--sound-pack').trim().replace(/['"]/g, '')
+      : '';
+    const cssDataTheme = typeof document !== 'undefined'
+      ? document.documentElement.getAttribute('data-theme')
+      : null;
+    return {
+      enabled,
+      pack: activePackName,
+      eventsForPack: Object.keys(activePack),
+      cssSoundPack,
+      cssDataTheme,
+      audioContextState: !Ctx ? 'no-audio-api' : audioCtx ? audioCtx.state : 'no-ac',
+      browserSupport: !!Ctx,
+    };
+  },
+  /**
+   * Force a sound to play for testing — bypasses the `enabled` gate.
+   * Call from DevTools: `Sounds.test('click')` after the AC has unlocked.
+   * Returns whether the play scheduled successfully.
+   */
+  test(event: SoundEvent = 'click'): boolean {
+    const cfg = activePack[event];
+    if (!cfg) return false;
+    const ac = ensureCtx();
+    if (!ac) return false;
+    const wasEnabled = enabled;
+    enabled = true;
+    try {
+      play(cfg);
+      return true;
+    } finally {
+      enabled = wasEnabled;
+    }
+  },
+};
+
+// Expose on `window` in dev mode so users can self-diagnose silent audio
+// from DevTools (`> Sounds.diagnose()`, `> Sounds.test()`). No-op in
+// production builds — Vite tree-shakes the `import.meta.env.DEV` branch.
+if (typeof window !== 'undefined' && import.meta.env.DEV) {
+  (window as any).Sounds = Sounds;
+}

package/client/src/main.tsx

@@ -2,6 +2,26 @@ import { StrictMode } from 'react'
 import { createRoot } from 'react-dom/client'
 import { PersistQueryClientProvider } from '@tanstack/react-query-persist-client'
 import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
+// Theme CSS — load BEFORE index.css so the per-theme [data-theme="..."]
+// blocks register their tokens before Tailwind compiles `@theme inline`
+// against the cascade. Order within the theme list matches specificity:
+// base.css (neutral defaults) → light.css (default :root + [data-theme="light"])
+// → dark.css (.dark + [data-theme="dark"]) → renaissance + cyber overrides.
+import './themes/base.css'
+import './themes/light.css'
+import './themes/dark.css'
+// Utopian set
+import './themes/renaissance.css'
+import './themes/greek.css'
+import './themes/edo.css'
+import './themes/steampunk.css'
+import './themes/atomic.css'
+// Dystopian set
+import './themes/cyber.css'
+import './themes/wasteland.css'
+import './themes/rot.css'
+import './themes/plague.css'
+import './themes/surveillance.css'
 import './index.css'
 import App from './App'
 import { ThemeProvider } from './contexts/ThemeContext'

package/client/src/store/useAppStore.ts

@@ -49,6 +49,13 @@ interface AppStore {
   componentPaletteVisible: boolean;
   consolePanelVisible: boolean;
   proMode: boolean;  // false = noob mode (only AI categories), true = pro mode (all categories)
+  /** WebAudio sound effects toggle (per-theme pack picked from
+   *  --sound-pack CSS token by `useSoundSync()`). Persisted to
+   *  localStorage as `machinaos-sound`; default ON (user disables in
+   *  Settings -> Audio). The AudioContext starts suspended per
+   *  browser autoplay policy — `Sounds.unlock()` resumes it on the
+   *  user's first interaction (no separate audio permission needed). */
+  soundEnabled: boolean;
   renamingNodeId: string | null;
 
   // Workflow actions
@@ -65,6 +72,8 @@ interface AppStore {
   toggleSidebar: () => void;
   toggleComponentPalette: () => void;
   toggleProMode: () => void;
+  setSoundEnabled: (enabled: boolean) => void;
+  toggleSoundEnabled: () => void;
   setRenamingNodeId: (nodeId: string | null) => void;
 
   // UI defaults from database
@@ -130,6 +139,10 @@ const STORAGE_KEYS = {
   componentPaletteVisible: 'ui_component_palette_visible',
   consolePanelVisible: 'ui_console_panel_visible',
   proMode: 'ui_pro_mode',
+  /** Sound enabled key — matches the design handoff's
+   *  `localStorage['machinaos-sound']` convention so a returning user's
+   *  prior choice rehydrates regardless of which session set it. */
+  soundEnabled: 'machinaos-sound',
 };
 
 // Helper to load boolean from localStorage
@@ -163,6 +176,7 @@ export const useAppStore = create<AppStore>((set, get) => ({
   componentPaletteVisible: loadBooleanFromStorage(STORAGE_KEYS.componentPaletteVisible, true),
   consolePanelVisible: loadBooleanFromStorage(STORAGE_KEYS.consolePanelVisible, false),
   proMode: loadBooleanFromStorage(STORAGE_KEYS.proMode, false),  // Default to noob mode
+  soundEnabled: loadBooleanFromStorage(STORAGE_KEYS.soundEnabled, true),  // On by default; user can disable in Settings -> Audio. Browsers gesture-gate WebAudio (no separate permission), so the AC unlocks on first interaction via Sounds.unlock().
   renamingNodeId: null,
 
   // Workflow management
@@ -331,6 +345,18 @@ export const useAppStore = create<AppStore>((set, get) => ({
     });
   },
 
+  setSoundEnabled: (enabled) => {
+    saveBooleanToStorage(STORAGE_KEYS.soundEnabled, enabled);
+    set({ soundEnabled: enabled });
+  },
+  toggleSoundEnabled: () => {
+    set((state) => {
+      const newValue = !state.soundEnabled;
+      saveBooleanToStorage(STORAGE_KEYS.soundEnabled, newValue);
+      return { soundEnabled: newValue };
+    });
+  },
+
   setRenamingNodeId: (nodeId) => {
     set({ renamingNodeId: nodeId });
   },

package/client/src/styles/canvasAnimations.ts

@@ -3,14 +3,26 @@
  * Dashboard. Split into named groups so a new status visual or keyframe
  * can be added without touching Dashboard.tsx.
  *
- *   KEYFRAMES                -- @keyframes definitions
+ *   KEYFRAMES                -- @keyframes definitions for edges
  *   edgeStatusStyles(...)    -- .react-flow__edge.{selected,executing,...}
- *   nodeStatusStyles(...)    -- .react-flow__node.{executing,...}
+ *   nodeStatusStyles(...)    -- .react-flow__node.{...} (status-class colors only)
  *   buildCanvasStyles(...)   -- composes the three for Dashboard
  *
  * Per-node inline animations (border pulse, etc.) live in their own
  * components and read theme tokens directly; this module is for
  * canvas-wide rules that need to match React Flow's wrapper classes.
+ *
+ * Node execution glow is owned by `client/src/themes/base.css` — see
+ * the `node-pulse` keyframe + `.react-flow__node.executing .node` /
+ * `.sq-node[data-executing] .sq-node-box` rules there. This file used
+ * to inject a competing `nodeGlow` keyframe targeting the React Flow
+ * wrapper; that was dead code (only the inner `.node` child animated)
+ * and has been removed in favour of base.css as the single source of
+ * truth.
+ *
+ * The light vs dark distinction is encoded entirely in `colors` (the
+ * theme object provides different values per mode), so this file knows
+ * nothing about which theme is active.
  */
 
 export interface CanvasStatusColors {
@@ -19,6 +31,9 @@ export interface CanvasStatusColors {
   edgeExecuting: string;
   edgeCompleted: string;
   edgeError: string;
+  edgePending: string;
+  edgeMemoryActive: string;
+  edgeToolActive: string;
 }
 
 const KEYFRAMES = `
@@ -26,19 +41,9 @@ const KEYFRAMES = `
     0% { stroke-dashoffset: 24; }
     100% { stroke-dashoffset: 0; }
   }
-
-  @keyframes nodeGlowDark {
-    0%, 100% { filter: drop-shadow(0 0 8px var(--node-glow)) drop-shadow(0 0 16px var(--node-glow-soft)); }
-    50%      { filter: drop-shadow(0 0 14px var(--node-glow)) drop-shadow(0 0 24px var(--node-glow)); }
-  }
-
-  @keyframes nodeGlowLight {
-    0%, 100% { filter: drop-shadow(0 0 10px rgba(37, 99, 235, 0.8)) drop-shadow(0 0 20px rgba(37, 99, 235, 0.6)); }
-    50%      { filter: drop-shadow(0 0 16px rgba(37, 99, 235, 1))   drop-shadow(0 0 30px rgba(37, 99, 235, 0.8)); }
-  }
 `;
 
-function edgeStatusStyles(colors: CanvasStatusColors, isDark: boolean): string {
+function edgeStatusStyles(colors: CanvasStatusColors): string {
   return `
   .react-flow__edge path {
     stroke: ${colors.edgeDefault} !important;
@@ -51,14 +56,14 @@ function edgeStatusStyles(colors: CanvasStatusColors, isDark: boolean): string {
   }
 
   .react-flow__edge.executing path {
-    stroke: ${isDark ? colors.edgeExecuting : '#2563eb'} !important;
+    stroke: ${colors.edgeExecuting} !important;
     stroke-width: 3px !important;
     stroke-dasharray: 8 4;
     animation: dashFlow 0.5s linear infinite;
   }
 
   .react-flow__edge.completed path {
-    stroke: ${isDark ? colors.edgeCompleted : '#16a34a'} !important;
+    stroke: ${colors.edgeCompleted} !important;
     stroke-width: 2px !important;
   }
 
@@ -68,45 +73,41 @@ function edgeStatusStyles(colors: CanvasStatusColors, isDark: boolean): string {
   }
 
   .react-flow__edge.pending path {
-    stroke: ${isDark ? colors.edgeDefault : '#6b7280'} !important;
+    stroke: ${colors.edgePending} !important;
     stroke-width: 2px !important;
     stroke-dasharray: 8 4;
     animation: dashFlow 0.5s linear infinite;
   }
 
   .react-flow__edge.memory-active path {
-    stroke: ${isDark ? '#ff79c6' : '#db2777'} !important;
+    stroke: ${colors.edgeMemoryActive} !important;
     stroke-width: 3px !important;
   }
 
   .react-flow__edge.tool-active path {
-    stroke: ${isDark ? '#ffb86c' : '#ea580c'} !important;
+    stroke: ${colors.edgeToolActive} !important;
     stroke-width: 3px !important;
   }
 `;
 }
 
-function nodeStatusStyles(colors: CanvasStatusColors, isDark: boolean): string {
-  // --node-glow / --node-glow-soft are scoped vars consumed by the
-  // nodeGlowDark keyframe, so the keyframe stays color-agnostic and
-  // theme swaps don't require regenerating the keyframe text.
-  const glow = colors.edgeExecuting;
-  return `
-  .react-flow__node.executing {
-    --node-glow: ${glow};
-    --node-glow-soft: ${glow}80;
-    animation: ${isDark ? 'nodeGlowDark' : 'nodeGlowLight'} 1.2s ease-in-out infinite;
-  }
-`;
+function nodeStatusStyles(_colors: CanvasStatusColors): string {
+  // Node execution animation is owned by base.css (`node-pulse`
+  // keyframe + `.react-flow__node.executing .node` /
+  // `.sq-node[data-executing] .sq-node-box` rules). This function is
+  // retained as a hook for future canvas-wide status-class rules on
+  // the React Flow wrapper that don't fit per-component CSS.
+  //
+  // `_colors` is intentionally unused at the moment; the parameter is
+  // kept on the signature so callers (buildCanvasStyles) and the
+  // CanvasStatusColors contract stay stable for downstream consumers.
+  return '';
 }
 
-export function buildCanvasStyles(
-  colors: CanvasStatusColors,
-  isDark: boolean,
-): string {
+export function buildCanvasStyles(colors: CanvasStatusColors): string {
   return [
-    edgeStatusStyles(colors, isDark),
-    nodeStatusStyles(colors, isDark),
+    edgeStatusStyles(colors),
+    nodeStatusStyles(colors),
     KEYFRAMES,
   ].join('\n');
 }