loukai-app 0.3.0

package/src/shared/state/StateManager.js

@@ -0,0 +1,263 @@
+import { EventEmitter } from 'events';
+
+/**
+ * StateManager - Universal state management for both Node.js and Browser
+ *
+ * This class provides a single source of truth for application state that works
+ * in both the Electron main process (Node.js) and renderer process (Browser).
+ *
+ * Features:
+ * - Event-based subscriptions for reactive updates
+ * - Granular events for different state domains
+ * - State snapshots for persistence
+ * - Type-safe state updates
+ * - Works in both Node.js and browser environments
+ */
+class StateManager extends EventEmitter {
+  constructor(initialState = {}) {
+    super();
+
+    // Initialize state with defaults
+    this.state = {
+      // Playback state
+      playback: {
+        isPlaying: false,
+        position: 0,
+        duration: 0,
+        volume: 1.0,
+        isPaused: false,
+        isLoading: false,
+      },
+
+      // Current song
+      currentSong: null,
+
+      // Queue
+      queue: [],
+
+      // Mixer settings
+      mixer: {
+        vocalVolume: 1.0,
+        musicVolume: 1.0,
+        micVolume: 1.0,
+        paVolume: 1.0,
+        iemVolume: 1.0,
+        micSolo: false,
+        vocalSolo: false,
+        musicSolo: false,
+      },
+
+      // Effects
+      effects: {
+        autotuneEnabled: false,
+        autotuneKey: 'C',
+        autotuneScale: 'major',
+        reverbEnabled: false,
+        reverbAmount: 0.3,
+        delayEnabled: false,
+        delayAmount: 0.3,
+      },
+
+      // User preferences
+      preferences: {
+        theme: 'dark',
+        visualizer: 'milkdrop',
+        defaultOutputDevice: null,
+        defaultInputDevice: null,
+      },
+
+      // Web server state
+      webServer: {
+        enabled: false,
+        port: 3000,
+        requestsEnabled: true,
+        adminPassword: null,
+      },
+
+      // Library metadata
+      library: {
+        totalSongs: 0,
+        lastScan: null,
+        scanInProgress: false,
+      },
+
+      // Override with any initial state
+      ...initialState,
+    };
+
+    // Track last update timestamp for each domain
+    this.lastUpdate = {
+      playback: Date.now(),
+      currentSong: Date.now(),
+      queue: Date.now(),
+      mixer: Date.now(),
+      effects: Date.now(),
+      preferences: Date.now(),
+      webServer: Date.now(),
+      library: Date.now(),
+    };
+  }
+
+  /**
+   * Get a snapshot of the current state
+   * @returns {Object} Deep copy of current state
+   */
+  getSnapshot() {
+    return JSON.parse(JSON.stringify(this.state));
+  }
+
+  /**
+   * Get a specific domain of state
+   * @param {string} domain - State domain (playback, mixer, effects, etc.)
+   * @returns {Object} Copy of domain state
+   */
+  getDomain(domain) {
+    if (!this.state[domain]) {
+      throw new Error(`Unknown state domain: ${domain}`);
+    }
+    return JSON.parse(JSON.stringify(this.state[domain]));
+  }
+
+  /**
+   * Update state and emit appropriate events
+   * @param {string} domain - State domain to update
+   * @param {Object|Function} updates - Updates object or function that receives current state
+   * @param {boolean} silent - If true, don't emit events
+   * @returns {Object} Updated domain state
+   */
+  update(domain, updates, silent = false) {
+    if (!this.state[domain]) {
+      throw new Error(`Unknown state domain: ${domain}`);
+    }
+
+    // Handle function-based updates
+    const actualUpdates = typeof updates === 'function' ? updates(this.state[domain]) : updates;
+
+    // Apply updates
+    this.state[domain] = {
+      ...this.state[domain],
+      ...actualUpdates,
+    };
+
+    // Update timestamp
+    this.lastUpdate[domain] = Date.now();
+
+    if (!silent) {
+      // Emit domain-specific event
+      this.emit(`${domain}Changed`, this.state[domain]);
+
+      // Emit general state change event
+      this.emit('stateChanged', {
+        domain,
+        state: this.state[domain],
+        timestamp: this.lastUpdate[domain],
+      });
+    }
+
+    return this.state[domain];
+  }
+
+  /**
+   * Subscribe to state changes for a specific domain
+   * @param {string} domain - State domain to watch
+   * @param {Function} callback - Callback function (receives updated state)
+   * @returns {Function} Unsubscribe function
+   */
+  subscribe(domain, callback) {
+    const event = `${domain}Changed`;
+    this.on(event, callback);
+
+    // Return unsubscribe function
+    return () => this.off(event, callback);
+  }
+
+  /**
+   * Subscribe to all state changes
+   * @param {Function} callback - Callback function (receives {domain, state, timestamp})
+   * @returns {Function} Unsubscribe function
+   */
+  subscribeAll(callback) {
+    this.on('stateChanged', callback);
+    return () => this.off('stateChanged', callback);
+  }
+
+  /**
+   * Reset state to initial values
+   * @param {boolean} silent - If true, don't emit events
+   */
+  reset(silent = false) {
+    const domains = Object.keys(this.state);
+
+    domains.forEach((domain) => {
+      // Reset to default values based on domain
+      switch (domain) {
+        case 'playback':
+          this.state.playback = {
+            isPlaying: false,
+            position: 0,
+            duration: 0,
+            volume: 1.0,
+            isPaused: false,
+            isLoading: false,
+          };
+          break;
+        case 'currentSong':
+          this.state.currentSong = null;
+          break;
+        case 'queue':
+          this.state.queue = [];
+          break;
+        // Other domains keep their current values on reset
+        default:
+          break;
+      }
+
+      this.lastUpdate[domain] = Date.now();
+
+      if (!silent) {
+        this.emit(`${domain}Changed`, this.state[domain]);
+      }
+    });
+
+    if (!silent) {
+      this.emit('stateChanged', {
+        domain: 'all',
+        state: this.state,
+        timestamp: Date.now(),
+      });
+    }
+  }
+
+  /**
+   * Load state from a serialized snapshot
+   * @param {Object} snapshot - State snapshot to load
+   * @param {boolean} silent - If true, don't emit events
+   */
+  loadSnapshot(snapshot, silent = false) {
+    this.state = JSON.parse(JSON.stringify(snapshot));
+
+    const now = Date.now();
+    Object.keys(this.lastUpdate).forEach((domain) => {
+      this.lastUpdate[domain] = now;
+    });
+
+    if (!silent) {
+      this.emit('stateChanged', {
+        domain: 'all',
+        state: this.state,
+        timestamp: now,
+      });
+    }
+  }
+
+  /**
+   * Get last update timestamp for a domain
+   * @param {string} domain - State domain
+   * @returns {number} Timestamp of last update
+   */
+  getLastUpdate(domain) {
+    return this.lastUpdate[domain] || 0;
+  }
+}
+
+export default StateManager;

package/src/shared/utils/audio.js

@@ -0,0 +1,42 @@
+/**
+ * Shared audio utility functions - pure functions with no side effects
+ * Usable in browser, Electron renderer, and Node.js
+ */
+
+/**
+ * Convert decibels to linear gain
+ * @param {number} db - Gain in decibels
+ * @returns {number} Linear gain value
+ */
+export function dbToLinear(db) {
+  return Math.pow(10, db / 20);
+}
+
+/**
+ * Convert linear gain to decibels
+ * @param {number} linear - Linear gain value
+ * @returns {number} Gain in decibels
+ */
+export function linearToDb(linear) {
+  return 20 * Math.log10(linear);
+}
+
+/**
+ * Clamp a value between min and max
+ * @param {number} value - Value to clamp
+ * @param {number} min - Minimum value
+ * @param {number} max - Maximum value
+ * @returns {number} Clamped value
+ */
+export function clamp(value, min, max) {
+  return Math.min(Math.max(value, min), max);
+}
+
+/**
+ * Check if a stem name is vocals
+ * @param {string} stemName - Name of the stem
+ * @returns {boolean} True if vocals stem
+ */
+export function isVocalStem(stemName) {
+  return stemName === 'vocals' || stemName.toLowerCase().includes('vocal');
+}

package/src/shared/utils/format.js

@@ -0,0 +1,32 @@
+/**
+ * Shared formatting utility functions
+ * Usable in browser, Electron renderer, and Node.js
+ */
+
+/**
+ * Format time in seconds to MM:SS format
+ * @param {number} seconds - Time in seconds
+ * @returns {string} Formatted time string
+ */
+export function formatTime(seconds) {
+  if (!seconds || isNaN(seconds)) return '0:00';
+
+  const mins = Math.floor(seconds / 60);
+  const secs = Math.floor(seconds % 60);
+  return `${mins}:${secs.toString().padStart(2, '0')}`;
+}
+
+/**
+ * Format file size in bytes to human-readable string
+ * @param {number} bytes - Size in bytes
+ * @returns {string} Formatted size string
+ */
+export function formatFileSize(bytes) {
+  if (bytes === 0) return '0 Bytes';
+
+  const k = 1024;
+  const sizes = ['Bytes', 'KB', 'MB', 'GB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+
+  return Math.round((bytes / Math.pow(k, i)) * 100) / 100 + ' ' + sizes[i];
+}

package/src/shared/utils/lyricsUtils.js

@@ -0,0 +1,162 @@
+/**
+ * Lyrics utility functions - pure JavaScript utilities for lyric manipulation
+ * No Node.js dependencies - safe for browser/renderer contexts
+ */
+
+/**
+ * Check if a line can be split
+ * @param {Object} line - Line to check (with text)
+ * @returns {boolean} True if line can be split
+ */
+export function canSplitLine(line) {
+  if (!line || !line.text) {
+    return false;
+  }
+
+  const text = line.text.trim();
+
+  // Find first sentence-ending punctuation (. ! ?)
+  const punctuationMatch = text.match(/[.!?]/);
+
+  if (!punctuationMatch) {
+    return false;
+  }
+
+  const splitIndex = punctuationMatch.index + 1;
+  const firstLineText = text.substring(0, splitIndex).trim();
+  const secondLineText = text.substring(splitIndex).trim();
+
+  // Must have text on both sides (prevents splitting if punctuation is at the end)
+  // Example: "Hello world." → false (only one sentence)
+  // Example: "Hello world. Hi" → true (two sentences)
+  return firstLineText.length > 0 && secondLineText.length > 0;
+}
+
+/**
+ * Split a lyric line at the first sentence-ending punctuation
+ * @param {Object} line - Line to split (with start, end, text, word_timing)
+ * @param {number} lineIndex - Index of the line (for logging)
+ * @returns {Array<Object>|null} Two new lines, or null if cannot split
+ */
+export function splitLine(line, lineIndex = 0) {
+  if (!line || !line.text) {
+    console.warn('Cannot split line: missing text');
+    return null;
+  }
+
+  const text = line.text.trim();
+
+  // Find first sentence-ending punctuation (. ! ?)
+  const punctuationMatch = text.match(/[.!?]/);
+
+  if (!punctuationMatch) {
+    console.log(`Line ${lineIndex}: No punctuation found, cannot split`);
+    return null;
+  }
+
+  const splitIndex = punctuationMatch.index + 1; // Include the punctuation
+  const firstLineText = text.substring(0, splitIndex).trim();
+  const secondLineText = text.substring(splitIndex).trim();
+
+  if (!firstLineText || !secondLineText) {
+    console.log(`Line ${lineIndex}: Split would create empty line, aborting`);
+    return null;
+  }
+
+  const duration = line.end - line.start;
+
+  // Try to use word-level timing if available and accurate
+  if (line.word_timing && Array.isArray(line.word_timing)) {
+    console.log(`Line ${lineIndex}: Attempting word-timing based split`);
+
+    // Validate word timing matches the text
+    const textWords = text.split(/\s+/);
+    const timingWordCount = line.word_timing.length;
+
+    if (timingWordCount !== textWords.length) {
+      console.warn(
+        `Line ${lineIndex}: Word count mismatch (timing: ${timingWordCount}, text: ${textWords.length}), falling back to percentage split`
+      );
+    } else {
+      // Word counts match, try to find the split point
+      const firstLineWords = firstLineText.split(/\s+/);
+      const splitWordIndex = firstLineWords.length;
+
+      if (splitWordIndex > 0 && splitWordIndex < line.word_timing.length) {
+        // Get timing of the word just before the split
+        const lastWordOfFirstLine = line.word_timing[splitWordIndex - 1];
+        const splitTime = line.start + lastWordOfFirstLine[1]; // end time of last word (relative to line start)
+
+        // First line: same start, new end
+        const firstLine = {
+          ...line,
+          text: firstLineText,
+          end: splitTime,
+          word_timing: line.word_timing.slice(0, splitWordIndex),
+        };
+
+        // Second line: new start, same end
+        // Adjust word_timing to be relative to new line start
+        const newLineStart = splitTime;
+        const secondLineWordTiming = line.word_timing.slice(splitWordIndex).map((timing) => {
+          const absoluteStart = line.start + timing[0];
+          const absoluteEnd = line.start + timing[1];
+          return [absoluteStart - newLineStart, absoluteEnd - newLineStart];
+        });
+
+        const secondLine = {
+          ...line,
+          text: secondLineText,
+          start: newLineStart,
+          end: line.end,
+          word_timing: secondLineWordTiming,
+        };
+
+        console.log(`✅ Line ${lineIndex}: Split using word-timing at ${splitTime.toFixed(2)}s`);
+        console.log(
+          `   Line 1: ${firstLine.start.toFixed(2)}-${firstLine.end.toFixed(2)}s "${firstLineText}"`
+        );
+        console.log(
+          `   Line 2: ${secondLine.start.toFixed(2)}-${secondLine.end.toFixed(2)}s "${secondLineText}"`
+        );
+
+        return [firstLine, secondLine];
+      }
+    }
+  }
+
+  // Fallback: split time based on text length percentage
+  console.log(`Line ${lineIndex}: Using percentage-based time split`);
+
+  const firstLineRatio = firstLineText.length / text.length;
+  const splitTime = line.start + duration * firstLineRatio;
+
+  const firstLine = {
+    ...line,
+    text: firstLineText,
+    end: splitTime,
+    // Remove word_timing since it's no longer accurate
+    word_timing: undefined,
+  };
+
+  const secondLine = {
+    ...line,
+    text: secondLineText,
+    start: splitTime,
+    end: line.end,
+    // Remove word_timing since it's no longer accurate
+    word_timing: undefined,
+  };
+
+  console.log(
+    `✅ Line ${lineIndex}: Split using percentage (${(firstLineRatio * 100).toFixed(1)}% / ${((1 - firstLineRatio) * 100).toFixed(1)}%)`
+  );
+  console.log(
+    `   Line 1: ${firstLine.start.toFixed(2)}-${firstLine.end.toFixed(2)}s "${firstLineText}"`
+  );
+  console.log(
+    `   Line 2: ${secondLine.start.toFixed(2)}-${secondLine.end.toFixed(2)}s "${secondLineText}"`
+  );
+
+  return [firstLine, secondLine];
+}

package/src/test/setup.js

@@ -0,0 +1,40 @@
+/**
+ * Vitest Setup File
+ * Runs before all tests to configure the testing environment
+ */
+
+import { expect, afterEach, vi } from 'vitest';
+import { cleanup } from '@testing-library/react';
+import * as matchers from '@testing-library/jest-dom/matchers';
+
+// Extend Vitest's expect with jest-dom matchers
+expect.extend(matchers);
+
+// Cleanup after each test case (e.g. clearing jsdom)
+afterEach(() => {
+  cleanup();
+});
+
+// Mock Electron IPC for renderer tests
+global.window = global.window || {};
+global.window.kaiAPI = {
+  app: {
+    getState: vi.fn(),
+  },
+  player: {
+    onPlaybackState: vi.fn(),
+  },
+  queue: {
+    addSong: vi.fn(),
+    removeSong: vi.fn(),
+    clear: vi.fn(),
+  },
+  settings: {
+    get: vi.fn(),
+    set: vi.fn(),
+  },
+  events: {
+    on: vi.fn(),
+    removeListener: vi.fn(),
+  },
+};