@dynamicu/chromedebug-mcp 2.2.0

package/src/database.js

@@ -0,0 +1,2178 @@
+// SQLite database module for ChromeDebug MCP recordings
+import Database from 'better-sqlite3';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import fs from 'fs';
+import { ProjectManager } from './services/project-manager.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// Initialize project manager for path resolution
+const projectManager = new ProjectManager();
+
+/**
+ * Gets the appropriate database path (always use global chromedebug.db)
+ * @returns {string} Database file path
+ */
+function getDatabasePath() {
+  // Always use global database for cross-project accessibility
+  const globalDbPath = path.join(__dirname, '../data/chromedebug.db');
+  
+  // Ensure data directory exists
+  const dbDir = path.dirname(globalDbPath);
+  if (!fs.existsSync(dbDir)) {
+    fs.mkdirSync(dbDir, { recursive: true });
+  }
+  
+  console.log(`[Database] Using global database: ${globalDbPath}`);
+  return globalDbPath;
+}
+
+// Get the database path (project-local or global)
+const DB_PATH = getDatabasePath();
+
+class ChromePilotDatabase {
+  constructor() {
+    this.db = null;
+    this.initialized = false;
+  }
+
+  init() {
+    if (this.initialized) return;
+    
+    // Ensure data directory exists
+    const dataDir = path.dirname(DB_PATH);
+    if (!fs.existsSync(dataDir)) {
+      fs.mkdirSync(dataDir, { recursive: true });
+    }
+    
+    this.db = new Database(DB_PATH);
+    this.db.pragma('journal_mode = WAL'); // Enable WAL mode for better concurrent access
+    
+    // Create tables
+    this.createTables();
+    this.initialized = true;
+    console.log(`ChromeDebug MCP database initialized at: ${DB_PATH}`);
+  }
+
+  createTables() {
+    // Recordings table for frame capture sessions
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS recordings (
+        id TEXT PRIMARY KEY,
+        session_id TEXT NOT NULL,
+        type TEXT NOT NULL DEFAULT 'frame_capture',
+        timestamp INTEGER NOT NULL,
+        total_frames INTEGER DEFAULT 0,
+        name TEXT,
+        created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+        updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
+      )
+    `);
+
+    // Frames table to store individual frames
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS frames (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        recording_id TEXT NOT NULL,
+        frame_index INTEGER NOT NULL,
+        timestamp INTEGER NOT NULL,
+        absolute_timestamp INTEGER NOT NULL,
+        image_data TEXT NOT NULL,
+        interactions TEXT DEFAULT '[]',
+        created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+        FOREIGN KEY (recording_id) REFERENCES recordings (id) ON DELETE CASCADE,
+        UNIQUE(recording_id, frame_index)
+      )
+    `);
+
+    // Add interactions column to existing frames table if it doesn't exist
+    try {
+      this.db.exec(`ALTER TABLE frames ADD COLUMN interactions TEXT DEFAULT '[]'`);
+      console.log('[Database] Added interactions column to frames table');
+    } catch (error) {
+      // Column already exists, ignore error
+      if (!error.message.includes('duplicate column name')) {
+        console.warn('[Database] Unexpected error adding interactions column:', error.message);
+      }
+    }
+
+    // Console logs table
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS console_logs (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        frame_id INTEGER NOT NULL,
+        level TEXT NOT NULL,
+        message TEXT NOT NULL,
+        relative_time INTEGER DEFAULT 0,
+        sequence_number INTEGER DEFAULT 0,
+        created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+        FOREIGN KEY (frame_id) REFERENCES frames (id) ON DELETE CASCADE
+      )
+    `);
+
+    // Deferred logs table for logs that arrive before frames are created
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS deferred_logs (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        session_id TEXT NOT NULL,
+        level TEXT NOT NULL,
+        message TEXT NOT NULL,
+        timestamp INTEGER NOT NULL,
+        sequence_number INTEGER NOT NULL,
+        args TEXT,
+        created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+      )
+    `);
+
+    // Screen interactions table for recording user interactions during screen recordings
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS screen_interactions (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        recording_id TEXT NOT NULL,
+        interaction_index INTEGER NOT NULL,
+        type TEXT NOT NULL,
+        selector TEXT,
+        xpath TEXT,
+        x INTEGER,
+        y INTEGER,
+        value TEXT,
+        text TEXT,
+        key TEXT,
+        timestamp INTEGER NOT NULL,
+        frame_index INTEGER,
+        created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+        FOREIGN KEY (recording_id) REFERENCES recordings (id) ON DELETE CASCADE,
+        UNIQUE(recording_id, interaction_index)
+      )
+    `);
+
+    // Workflow recordings table
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS workflow_recordings (
+        id TEXT PRIMARY KEY,
+        session_id TEXT NOT NULL,
+        name TEXT,
+        url TEXT NOT NULL,
+        title TEXT,
+        timestamp INTEGER NOT NULL,
+        total_actions INTEGER DEFAULT 0,
+        include_logs BOOLEAN DEFAULT FALSE,
+        screenshot_settings TEXT,
+        created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+        updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
+      )
+    `);
+
+    // Workflow actions table
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS workflow_actions (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        workflow_id TEXT NOT NULL,
+        action_index INTEGER NOT NULL,
+        type TEXT NOT NULL,
+        selector TEXT NOT NULL,
+        x INTEGER,
+        y INTEGER,
+        value TEXT,
+        text TEXT,
+        placeholder TEXT,
+        timestamp INTEGER NOT NULL,
+        screenshot_data TEXT,
+        created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+        FOREIGN KEY (workflow_id) REFERENCES workflow_recordings (id) ON DELETE CASCADE,
+        UNIQUE(workflow_id, action_index)
+      )
+    `);
+
+    // Workflow logs table
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS workflow_logs (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        workflow_id TEXT NOT NULL,
+        level TEXT NOT NULL,
+        message TEXT NOT NULL,
+        timestamp INTEGER NOT NULL,
+        relative_time INTEGER DEFAULT 0,
+        created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+        FOREIGN KEY (workflow_id) REFERENCES workflow_recordings (id) ON DELETE CASCADE
+      )
+    `);
+    
+    // Add columns for function trace data if they don't exist
+    try {
+      // Check if component column exists
+      const columns = this.db.pragma('table_info(workflow_actions)');
+      const hasComponent = columns.some(col => col.name === 'component');
+      const hasArgs = columns.some(col => col.name === 'args');
+      const hasStack = columns.some(col => col.name === 'stack');
+      const hasElementHtml = columns.some(col => col.name === 'element_html');
+      const hasComponentData = columns.some(col => col.name === 'component_data');
+      const hasEventHandlers = columns.some(col => col.name === 'event_handlers');
+      const hasElementState = columns.some(col => col.name === 'element_state');
+      const hasPerformanceMetrics = columns.some(col => col.name === 'performance_metrics');
+
+      if (!hasComponent) {
+        this.db.exec('ALTER TABLE workflow_actions ADD COLUMN component TEXT');
+        console.log('[Database] Added component column to workflow_actions');
+      }
+      if (!hasArgs) {
+        this.db.exec('ALTER TABLE workflow_actions ADD COLUMN args TEXT');
+        console.log('[Database] Added args column to workflow_actions');
+      }
+      if (!hasStack) {
+        this.db.exec('ALTER TABLE workflow_actions ADD COLUMN stack TEXT');
+        console.log('[Database] Added stack column to workflow_actions');
+      }
+
+      // Add enhanced click tracking columns
+      if (!hasElementHtml) {
+        this.db.exec('ALTER TABLE workflow_actions ADD COLUMN element_html TEXT');
+        console.log('[Database] Added element_html column to workflow_actions');
+      }
+      if (!hasComponentData) {
+        this.db.exec('ALTER TABLE workflow_actions ADD COLUMN component_data TEXT');
+        console.log('[Database] Added component_data column to workflow_actions');
+      }
+      if (!hasEventHandlers) {
+        this.db.exec('ALTER TABLE workflow_actions ADD COLUMN event_handlers TEXT');
+        console.log('[Database] Added event_handlers column to workflow_actions');
+      }
+      if (!hasElementState) {
+        this.db.exec('ALTER TABLE workflow_actions ADD COLUMN element_state TEXT');
+        console.log('[Database] Added element_state column to workflow_actions');
+      }
+      if (!hasPerformanceMetrics) {
+        this.db.exec('ALTER TABLE workflow_actions ADD COLUMN performance_metrics TEXT');
+        console.log('[Database] Added performance_metrics column to workflow_actions');
+      }
+    } catch (error) {
+      // Columns might already exist, that's ok
+      console.log('[Database] Function trace columns already exist or migration failed:', error.message);
+    }
+
+    // Add enhanced columns to screen_interactions table
+    try {
+      const screenInteractionsColumns = this.db.pragma('table_info(screen_interactions)');
+      const hasScreenElementHtml = screenInteractionsColumns.some(col => col.name === 'element_html');
+      const hasScreenComponentData = screenInteractionsColumns.some(col => col.name === 'component_data');
+      const hasScreenEventHandlers = screenInteractionsColumns.some(col => col.name === 'event_handlers');
+      const hasScreenElementState = screenInteractionsColumns.some(col => col.name === 'element_state');
+      const hasScreenPerformanceMetrics = screenInteractionsColumns.some(col => col.name === 'performance_metrics');
+
+      // Add enhanced click tracking columns to screen_interactions
+      if (!hasScreenElementHtml) {
+        this.db.exec('ALTER TABLE screen_interactions ADD COLUMN element_html TEXT');
+        console.log('[Database] Added element_html column to screen_interactions');
+      }
+      if (!hasScreenComponentData) {
+        this.db.exec('ALTER TABLE screen_interactions ADD COLUMN component_data TEXT');
+        console.log('[Database] Added component_data column to screen_interactions');
+      }
+      if (!hasScreenEventHandlers) {
+        this.db.exec('ALTER TABLE screen_interactions ADD COLUMN event_handlers TEXT');
+        console.log('[Database] Added event_handlers column to screen_interactions');
+      }
+      if (!hasScreenElementState) {
+        this.db.exec('ALTER TABLE screen_interactions ADD COLUMN element_state TEXT');
+        console.log('[Database] Added element_state column to screen_interactions');
+      }
+      if (!hasScreenPerformanceMetrics) {
+        this.db.exec('ALTER TABLE screen_interactions ADD COLUMN performance_metrics TEXT');
+        console.log('[Database] Added performance_metrics column to screen_interactions');
+      }
+    } catch (error) {
+      // Columns might already exist, that's ok
+      console.log('[Database] Screen interactions enhanced columns already exist or migration failed:', error.message);
+    }
+
+    // Restore points table
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS restore_points (
+        id TEXT PRIMARY KEY,
+        workflow_id TEXT NOT NULL,
+        action_index INTEGER,
+        timestamp INTEGER NOT NULL,
+        url TEXT NOT NULL,
+        title TEXT,
+        dom_snapshot TEXT NOT NULL,
+        scroll_x INTEGER DEFAULT 0,
+        scroll_y INTEGER DEFAULT 0,
+        local_storage TEXT,
+        session_storage TEXT,
+        cookies TEXT,
+        console_logs TEXT,
+        created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+        FOREIGN KEY (workflow_id) REFERENCES workflow_recordings (id) ON DELETE CASCADE
+      )
+    `);
+
+    // Server instances table to track single-server mode
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS server_instances (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        pid INTEGER NOT NULL,
+        mode TEXT NOT NULL,
+        started_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+        UNIQUE(pid)
+      )
+    `);
+
+    // Full data recording configuration table
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS full_recording_configs (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        recording_id TEXT NOT NULL,
+        instrumentation_level INTEGER DEFAULT 0,
+        capture_console BOOLEAN DEFAULT TRUE,
+        capture_dom BOOLEAN DEFAULT FALSE,
+        capture_functions BOOLEAN DEFAULT FALSE,
+        capture_variables BOOLEAN DEFAULT FALSE,
+        capture_network BOOLEAN DEFAULT FALSE,
+        performance_threshold_ms INTEGER DEFAULT 10,
+        max_data_size_mb INTEGER DEFAULT 100,
+        created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+        FOREIGN KEY (recording_id) REFERENCES recordings (id) ON DELETE CASCADE
+      )
+    `);
+
+    // Execution traces table for function call tracking
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS execution_traces (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        recording_id TEXT NOT NULL,
+        trace_index INTEGER NOT NULL,
+        timestamp INTEGER NOT NULL,
+        function_name TEXT,
+        function_source TEXT,
+        arguments TEXT,
+        return_value TEXT,
+        error TEXT,
+        call_stack TEXT,
+        execution_time_ms INTEGER,
+        created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+        FOREIGN KEY (recording_id) REFERENCES recordings (id) ON DELETE CASCADE,
+        UNIQUE(recording_id, trace_index)
+      )
+    `);
+
+    // Variable states table for runtime variable tracking
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS variable_states (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        recording_id TEXT NOT NULL,
+        timestamp INTEGER NOT NULL,
+        scope_chain TEXT,
+        variables TEXT,
+        heap_snapshot BLOB,
+        created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+        FOREIGN KEY (recording_id) REFERENCES recordings (id) ON DELETE CASCADE
+      )
+    `);
+
+    // DOM mutations table for DOM change tracking
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS dom_mutations (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        recording_id TEXT NOT NULL,
+        timestamp INTEGER NOT NULL,
+        mutation_type TEXT,
+        target_selector TEXT,
+        target_xpath TEXT,
+        old_value TEXT,
+        new_value TEXT,
+        attributes_changed TEXT,
+        created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+        FOREIGN KEY (recording_id) REFERENCES recordings (id) ON DELETE CASCADE
+      )
+    `);
+
+    // Network requests table for API tracking
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS network_requests (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        recording_id TEXT NOT NULL,
+        timestamp INTEGER NOT NULL,
+        request_id TEXT,
+        method TEXT,
+        url TEXT,
+        headers TEXT,
+        body TEXT,
+        response_status INTEGER,
+        response_headers TEXT,
+        response_body TEXT,
+        duration_ms INTEGER,
+        created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+        FOREIGN KEY (recording_id) REFERENCES recordings (id) ON DELETE CASCADE
+      )
+    `);
+
+    // Performance metrics table
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS performance_metrics (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        recording_id TEXT NOT NULL,
+        timestamp INTEGER NOT NULL,
+        metric_type TEXT,
+        metric_name TEXT,
+        metric_value REAL,
+        metadata TEXT,
+        created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+        FOREIGN KEY (recording_id) REFERENCES recordings (id) ON DELETE CASCADE
+      )
+    `);
+
+    // Create indexes for better performance
+    this.db.exec(`
+      CREATE INDEX IF NOT EXISTS idx_recordings_session_id ON recordings (session_id);
+      CREATE INDEX IF NOT EXISTS idx_recordings_timestamp ON recordings (timestamp);
+      CREATE INDEX IF NOT EXISTS idx_frames_recording_id ON frames (recording_id);
+      CREATE INDEX IF NOT EXISTS idx_frames_frame_index ON frames (recording_id, frame_index);
+      CREATE INDEX IF NOT EXISTS idx_console_logs_frame_id ON console_logs (frame_id);
+      CREATE INDEX IF NOT EXISTS idx_screen_interactions_recording_id ON screen_interactions (recording_id);
+      CREATE INDEX IF NOT EXISTS idx_screen_interactions_timestamp ON screen_interactions (timestamp);
+      CREATE INDEX IF NOT EXISTS idx_screen_interactions_frame_index ON screen_interactions (recording_id, frame_index);
+      CREATE INDEX IF NOT EXISTS idx_workflow_recordings_session_id ON workflow_recordings (session_id);
+      CREATE INDEX IF NOT EXISTS idx_workflow_recordings_timestamp ON workflow_recordings (timestamp);
+      CREATE INDEX IF NOT EXISTS idx_workflow_actions_workflow_id ON workflow_actions (workflow_id);
+      CREATE INDEX IF NOT EXISTS idx_workflow_actions_action_index ON workflow_actions (workflow_id, action_index);
+      CREATE INDEX IF NOT EXISTS idx_workflow_logs_workflow_id ON workflow_logs (workflow_id);
+      CREATE INDEX IF NOT EXISTS idx_restore_points_workflow_id ON restore_points (workflow_id);
+      CREATE INDEX IF NOT EXISTS idx_restore_points_timestamp ON restore_points (timestamp);
+      
+      -- Indexes for new full recording tables
+      CREATE INDEX IF NOT EXISTS idx_full_recording_configs_recording_id ON full_recording_configs (recording_id);
+      CREATE INDEX IF NOT EXISTS idx_execution_traces_recording_id ON execution_traces (recording_id, timestamp);
+      CREATE INDEX IF NOT EXISTS idx_execution_traces_function ON execution_traces (function_name);
+      CREATE INDEX IF NOT EXISTS idx_variable_states_recording_id ON variable_states (recording_id, timestamp);
+      CREATE INDEX IF NOT EXISTS idx_dom_mutations_recording_id ON dom_mutations (recording_id, timestamp);
+      CREATE INDEX IF NOT EXISTS idx_network_requests_recording_id ON network_requests (recording_id, timestamp);
+      CREATE INDEX IF NOT EXISTS idx_performance_metrics_recording_id ON performance_metrics (recording_id, timestamp);
+    `);
+    
+    // Run migrations to update existing databases
+    this.runMigrations();
+  }
+  
+  runMigrations() {
+    // Check if workflow_recordings table has name column
+    const columns = this.db.pragma(`table_info(workflow_recordings)`);
+    const hasNameColumn = columns.some(col => col.name === 'name');
+    const hasScreenshotSettings = columns.some(col => col.name === 'screenshot_settings');
+    
+    if (!hasNameColumn) {
+      console.log('[Database] Migrating workflow_recordings table to add name column');
+      this.db.exec(`ALTER TABLE workflow_recordings ADD COLUMN name TEXT`);
+    }
+    
+    if (!hasScreenshotSettings) {
+      console.log('[Database] Migrating workflow_recordings table to add screenshot_settings column');
+      this.db.exec(`ALTER TABLE workflow_recordings ADD COLUMN screenshot_settings TEXT`);
+    }
+    
+    // Check if workflow_actions table has screenshot_data column
+    const actionColumns = this.db.pragma(`table_info(workflow_actions)`);
+    const hasScreenshotData = actionColumns.some(col => col.name === 'screenshot_data');
+    
+    if (!hasScreenshotData) {
+      console.log('[Database] Migrating workflow_actions table to add screenshot_data column');
+      this.db.exec(`ALTER TABLE workflow_actions ADD COLUMN screenshot_data TEXT`);
+    }
+    
+    // Check if console_logs table has sequence_number column
+    const logColumns = this.db.pragma(`table_info(console_logs)`);
+    const hasSequenceNumber = logColumns.some(col => col.name === 'sequence_number');
+    
+    if (!hasSequenceNumber) {
+      console.log('[Database] Migrating console_logs table to add sequence_number column');
+      this.db.exec(`ALTER TABLE console_logs ADD COLUMN sequence_number INTEGER DEFAULT 0`);
+    }
+
+    // Migration for snapshot feature support
+    const recordingsColumns = this.db.pragma(`table_info(recordings)`);
+    const hasRecordingType = recordingsColumns.some(col => col.name === 'recording_type');
+    const hasUserNote = recordingsColumns.some(col => col.name === 'user_note');
+    const hasName = recordingsColumns.some(col => col.name === 'name');
+
+    if (!hasRecordingType) {
+      console.log('[Database] Migrating recordings table to add recording_type column');
+      this.db.exec(`ALTER TABLE recordings ADD COLUMN recording_type TEXT DEFAULT 'continuous'`);
+    }
+
+    if (!hasUserNote) {
+      console.log('[Database] Migrating recordings table to add user_note column');
+      this.db.exec(`ALTER TABLE recordings ADD COLUMN user_note TEXT`);
+    }
+
+    if (!hasName) {
+      console.log('[Database] Migrating recordings table to add name column');
+      this.db.exec(`ALTER TABLE recordings ADD COLUMN name TEXT`);
+    }
+  }
+
+  // Store a recording session
+  storeRecording(sessionId, type = 'frame_capture', recordingType = 'continuous', userNote = null, name = null) {
+    this.init();
+
+    const stmt = this.db.prepare(`
+      INSERT OR REPLACE INTO recordings (id, session_id, type, timestamp, updated_at, recording_type, user_note, name)
+      VALUES (?, ?, ?, ?, CURRENT_TIMESTAMP, ?, ?, ?)
+    `);
+
+    // Use base ID instead of prefixed ID
+    const recordingId = sessionId;
+    const timestamp = Date.now();
+
+    console.log(`[Database] Storing recording: ${recordingId} for session: ${sessionId}, type: ${recordingType}, name: ${name || 'none'}`);
+    const result = stmt.run(recordingId, sessionId, type, timestamp, recordingType, userNote, name);
+    console.log(`[Database] Recording stored with changes: ${result.changes}, lastInsertRowid: ${result.lastInsertRowid}`);
+
+    return recordingId;
+  }
+
+  /*
+   * SNAPSHOT FEATURE DISABLED (2025-10-01)
+   *
+   * Snapshot database methods disabled - see SNAPSHOT_FEATURE_DISABLED.md
+   *
+   * WHY DISABLED:
+   * - Snapshots without console logs are just screenshots (users can do this natively)
+   * - Console log capture requires always-on monitoring (privacy concern)
+   * - Core value proposition (screenshot + searchable logs) cannot be achieved cleanly
+   *
+   * NOTE: Database schema (recording_type column) is preserved to maintain data integrity.
+   * Existing snapshot data in the database is not deleted.
+   *
+   * TO RE-ENABLE:
+   * 1. Implement privacy-conscious always-on log monitoring
+   * 2. Uncomment these methods
+   * 3. Re-enable chrome-controller.js methods
+   * 4. Re-enable HTTP endpoint in http-server.js
+   * 5. Re-enable extension UI and handlers
+   */
+  /*
+  storeSnapshot(sessionId, frameData, userNote = null) {
+    this.init();
+
+    // Create the recording as a snapshot type
+    const recordingId = this.storeRecording(sessionId, 'frame_capture', 'snapshot', userNote);
+
+    // Store the single frame
+    if (frameData) {
+      this.storeFrameBatch(sessionId, [frameData]);
+    }
+
+    console.log(`[Database] Snapshot stored: ${recordingId} with note: ${userNote || 'none'}`);
+    return recordingId;
+  }
+
+  getSnapshots(limit = 50) {
+    this.init();
+
+    const stmt = this.db.prepare(`
+      SELECT r.*, COUNT(f.id) as frame_count
+      FROM recordings r
+      LEFT JOIN frames f ON f.recording_id = r.id
+      WHERE r.recording_type = 'snapshot'
+      GROUP BY r.id
+      ORDER BY r.timestamp DESC
+      LIMIT ?
+    `);
+
+    return stmt.all(limit);
+  }
+  */
+
+  // Store frame batch
+  storeFrameBatch(sessionId, frames, name = null) {
+    this.init();
+
+    // Use base ID instead of prefixed ID
+    const recordingId = sessionId;
+
+    console.log(`[storeFrameBatch] DEATH SPIRAL FIX: Processing ${frames.length} frames for session ${sessionId}`);
+
+    // Ensure recording exists (but don't overwrite existing)
+    const existingRecording = this.getRecording(sessionId);
+    if (!existingRecording) {
+      this.storeRecording(sessionId, 'frame_capture', 'continuous', null, name);
+    } else {
+      console.log(`[storeFrameBatch] Using existing recording: ${existingRecording.id}`);
+      // Update name if provided and different
+      if (name && name !== existingRecording.name) {
+        const updateStmt = this.db.prepare(`UPDATE recordings SET name = ? WHERE id = ?`);
+        updateStmt.run(name, sessionId);
+        console.log(`[storeFrameBatch] Updated recording name to: ${name}`);
+      }
+    }
+    
+    // Check existing frame count BEFORE insertion
+    const preCountStmt = this.db.prepare(`SELECT COUNT(*) as count FROM frames WHERE recording_id = ?`);
+    const preCount = preCountStmt.get(recordingId).count;
+    console.log(`[storeFrameBatch] PRE-INSERT: ${preCount} existing frames in database`);
+    
+    // Use INSERT OR REPLACE instead of INSERT OR IGNORE to handle updates
+    const frameStmt = this.db.prepare(`
+      INSERT OR REPLACE INTO frames (recording_id, frame_index, timestamp, absolute_timestamp, image_data, interactions)
+      VALUES (?, ?, ?, ?, ?, ?)
+    `);
+    
+    const transaction = this.db.transaction((frames) => {
+      let insertedCount = 0;
+      let skippedCount = 0;
+      
+      for (let i = 0; i < frames.length; i++) {
+        const frame = frames[i];
+        // Use frame.index from extension (properly tracked per session), fallback to i for backward compatibility
+        const frameIndex = frame.index !== undefined ? frame.index : i;
+        
+        console.log(`[storeFrameBatch] Inserting frame ${frameIndex}: timestamp=${frame.timestamp}, absoluteTimestamp=${frame.absoluteTimestamp}`);
+        
+        try {
+          // Serialize interactions as JSON
+          const interactionsJson = JSON.stringify(frame.interactions || []);
+
+          const result = frameStmt.run(
+            recordingId,
+            frameIndex,
+            frame.timestamp || Date.now(),
+            frame.absoluteTimestamp || Date.now(),
+            frame.imageData,
+            interactionsJson
+          );
+          
+          if (result.changes > 0) {
+            insertedCount++;
+            console.log(`[storeFrameBatch] SUCCESS: Frame ${frameIndex} inserted/updated`);
+          } else {
+            skippedCount++;
+            console.log(`[storeFrameBatch] WARNING: Frame ${frameIndex} not changed`);
+          }
+        } catch (error) {
+          console.error(`[storeFrameBatch] ERROR inserting frame ${frameIndex}:`, error.message);
+          throw error; // Fail fast on SQL errors
+        }
+      }
+      
+      console.log(`[storeFrameBatch] Transaction complete: ${insertedCount} inserted, ${skippedCount} skipped`);
+      
+      // Update total frames count
+      const updateStmt = this.db.prepare(`
+        UPDATE recordings 
+        SET total_frames = (SELECT COUNT(*) FROM frames WHERE recording_id = ?),
+            updated_at = CURRENT_TIMESTAMP
+        WHERE id = ?
+      `);
+      updateStmt.run(recordingId, recordingId);
+      
+      // Debug: Check the actual count after update
+      const finalCountStmt = this.db.prepare(`SELECT COUNT(*) as count FROM frames WHERE recording_id = ?`);
+      const finalCount = finalCountStmt.get(recordingId).count;
+      console.log(`[storeFrameBatch] FINAL: ${finalCount} frames in database (was ${preCount})`);
+      
+      return { insertedCount, skippedCount, finalCount };
+    });
+    
+    const result = transaction(frames);
+    console.log(`[storeFrameBatch] DEATH SPIRAL RESOLVED: ${result.insertedCount}/${frames.length} frames stored successfully`);
+    
+    // Verify what was actually stored
+    const verifyStmt = this.db.prepare(`
+      SELECT frame_index, timestamp FROM frames 
+      WHERE recording_id = ? 
+      ORDER BY frame_index ASC
+    `);
+    const storedFrames = verifyStmt.all(recordingId);
+    console.log(`[storeFrameBatch] VERIFICATION: ${storedFrames.length} frames with indices: [${storedFrames.map(f => f.frame_index).join(', ')}]`);
+    
+    if (storedFrames.length === 0) {
+      console.error(`[storeFrameBatch] DEATH SPIRAL DETECTED: NO FRAMES STORED! Check SQL constraints and frame data.`);
+      throw new Error(`Frame storage failed: 0 frames stored for session ${sessionId}`);
+    }
+    
+    return this.getRecording(recordingId);
+  }
+
+  // Associate logs with frames
+  associateLogsWithFrames(sessionId, logs) {
+    this.init();
+    
+    // Use base ID instead of prefixed ID
+    const recordingId = sessionId;
+    
+    // Clear existing logs for this recording
+    const clearLogsStmt = this.db.prepare(`
+      DELETE FROM console_logs 
+      WHERE frame_id IN (SELECT id FROM frames WHERE recording_id = ?)
+    `);
+    clearLogsStmt.run(recordingId);
+    
+    // Get all frames sorted by timestamp
+    const framesStmt = this.db.prepare(`
+      SELECT id, frame_index, absolute_timestamp 
+      FROM frames 
+      WHERE recording_id = ? 
+      ORDER BY absolute_timestamp ASC
+    `);
+    const frames = framesStmt.all(recordingId);
+    
+    console.log(`[associateLogsWithFrames] Found ${frames.length} frames for log association`);
+    console.log(`[associateLogsWithFrames] Frame indices found: [${frames.map(f => f.frame_index).join(', ')}]`);
+    
+    // Debug: Check total frames before processing
+    const countStmt = this.db.prepare(`SELECT COUNT(*) as count FROM frames WHERE recording_id = ?`);
+    const frameCount = countStmt.get(recordingId).count;
+    console.log(`[associateLogsWithFrames] Total frames in database before log association: ${frameCount}`);
+    
+    if (frames.length === 0) {
+      return { success: false, message: 'No frames found for session' };
+    }
+    
+    // Sort logs by timestamp
+    logs.sort((a, b) => a.timestamp - b.timestamp);
+    
+    const logStmt = this.db.prepare(`
+      INSERT INTO console_logs (frame_id, level, message, relative_time)
+      VALUES (?, ?, ?, ?)
+    `);
+    
+    const transaction = this.db.transaction((logs, frames) => {
+      let associatedCount = 0;
+      let frameBucketIndex = 0;
+      
+      for (const log of logs) {
+        // Find the correct frame bucket for this log
+        while (frameBucketIndex < frames.length && 
+               frames[frameBucketIndex].absolute_timestamp < log.timestamp) {
+          frameBucketIndex++;
+        }
+        
+        if (frameBucketIndex < frames.length) {
+          const frame = frames[frameBucketIndex];
+          const relativeTime = log.timestamp - frame.absolute_timestamp;
+          
+          // Truncate large log messages before storing
+          let message = log.message;
+          const maxMessageLength = 10000; // 10KB limit per log entry
+          
+          if (message && message.length > maxMessageLength) {
+            // Check if it's a base64 image that was already truncated by the extension
+            if (message.includes('[Base64 Image:') && message.includes('truncated...]')) {
+              // Already truncated by extension, keep as is
+            } else {
+              // Additional truncation for any other large content
+              message = message.substring(0, maxMessageLength) + `... [DB TRUNCATED: ${message.length} total bytes]`;
+            }
+          }
+          
+          logStmt.run(frame.id, log.level, message, relativeTime);
+          associatedCount++;
+        }
+      }
+      
+      return associatedCount;
+    });
+    
+    const associatedCount = transaction(logs, frames);
+    
+    console.log(`Associated ${associatedCount} of ${logs.length} logs with frames`);
+    
+    // Debug: Check total frames after processing
+    const finalFrameCount = countStmt.get(recordingId).count;
+    console.log(`[associateLogsWithFrames] Total frames in database after log association: ${finalFrameCount}`);
+    
+    return {
+      success: true,
+      sessionId: sessionId,
+      logsReceived: logs.length,
+      logsAssociated: associatedCount
+    };
+  }
+
+  // Stream logs to frames - optimized for real-time batched streaming
+  streamLogsToFrames(sessionId, logs) {
+    this.init();
+    
+    // Use base ID instead of prefixed ID
+    const recordingId = sessionId;
+    
+    console.log(`[streamLogsToFrames] Processing ${logs.length} logs for session: ${sessionId}`);
+    
+    // Get all frames sorted by timestamp for efficient association
+    const framesStmt = this.db.prepare(`
+      SELECT id, frame_index, absolute_timestamp 
+      FROM frames 
+      WHERE recording_id = ? 
+      ORDER BY absolute_timestamp ASC
+    `);
+    const frames = framesStmt.all(recordingId);
+    
+    if (frames.length === 0) {
+      console.log(`[streamLogsToFrames] No frames found for session: ${sessionId}, storing ${logs.length} logs as deferred`);
+      return this.storeDeferredLogs(sessionId, logs);
+    }
+    
+    // Sort logs by sequence number for proper ordering
+    logs.sort((a, b) => a.sequence - b.sequence);
+    
+    const logStmt = this.db.prepare(`
+      INSERT INTO console_logs (frame_id, level, message, relative_time, sequence_number)
+      VALUES (?, ?, ?, ?, ?)
+    `);
+    
+    const transaction = this.db.transaction((logs, frames) => {
+      let associatedCount = 0;
+
+      for (const log of logs) {
+        // Find the best frame for this log using binary search approach
+        let targetFrame = null;
+        let minTimeDiff = Infinity;
+
+        // For each log, find the frame with the closest timestamp
+        for (let i = 0; i < frames.length; i++) {
+          const frame = frames[i];
+          const timeDiff = Math.abs(log.timestamp - frame.absolute_timestamp);
+
+          // If this frame is closer than previous best, use it
+          if (timeDiff < minTimeDiff) {
+            minTimeDiff = timeDiff;
+            targetFrame = frame;
+          }
+
+          // If we found a frame that's very close (within 50ms), use it
+          if (timeDiff <= 50) {
+            break;
+          }
+        }
+
+        // Fallback: if no close frame found, use temporal ordering
+        if (!targetFrame || minTimeDiff > 1000) {
+          // Find frame that occurs before or at the log timestamp
+          for (let i = frames.length - 1; i >= 0; i--) {
+            if (frames[i].absolute_timestamp <= log.timestamp) {
+              targetFrame = frames[i];
+              break;
+            }
+          }
+
+          // If still no frame, use the first available frame
+          if (!targetFrame && frames.length > 0) {
+            targetFrame = frames[0];
+          }
+        }
+
+        if (targetFrame) {
+          const relativeTime = log.timestamp - targetFrame.absolute_timestamp;
+
+          // Truncate message if too long to prevent DB issues
+          let message = log.message;
+          const maxMessageLength = 50000; // 50KB limit
+          if (message && message.length > maxMessageLength) {
+            message = message.substring(0, maxMessageLength) + `... [STREAM TRUNCATED: ${message.length} total bytes]`;
+          }
+
+          // Insert with sequence number for ordering
+          logStmt.run(targetFrame.id, log.level, message, relativeTime, log.sequence);
+          associatedCount++;
+        }
+      }
+
+      return associatedCount;
+    });
+    
+    const associatedCount = transaction(logs, frames);
+    
+    console.log(`[streamLogsToFrames] Streamed ${associatedCount} of ${logs.length} logs to frames`);
+    
+    return {
+      success: true,
+      sessionId: sessionId,
+      logsReceived: logs.length,
+      logsStreamed: associatedCount,
+      method: 'stream'
+    };
+  }
+
+  // Store logs temporarily when frames don't exist yet
+  storeDeferredLogs(sessionId, logs) {
+    this.init();
+    
+    console.log(`[storeDeferredLogs] Storing ${logs.length} deferred logs for session: ${sessionId}`);
+    
+    const deferredLogStmt = this.db.prepare(`
+      INSERT INTO deferred_logs (session_id, level, message, timestamp, sequence_number, args)
+      VALUES (?, ?, ?, ?, ?, ?)
+    `);
+    
+    const transaction = this.db.transaction((logs) => {
+      let stored = 0;
+      for (const log of logs) {
+        try {
+          deferredLogStmt.run(
+            sessionId,
+            log.level,
+            log.message,
+            log.timestamp,
+            log.sequence || 0,
+            log.args ? JSON.stringify(log.args) : null
+          );
+          stored++;
+        } catch (error) {
+          console.error(`[storeDeferredLogs] Failed to store deferred log:`, error, log);
+        }
+      }
+      return stored;
+    });
+    
+    const storedCount = transaction(logs);
+    
+    console.log(`[storeDeferredLogs] Stored ${storedCount} of ${logs.length} deferred logs`);
+    
+    return {
+      success: true,
+      sessionId: sessionId,
+      logsReceived: logs.length,
+      logsDeferred: storedCount,
+      method: 'deferred'
+    };
+  }
+
+  // Associate deferred logs with frames when frames become available
+  associateDeferredLogs(sessionId) {
+    this.init();
+    
+    console.log(`[associateDeferredLogs] Checking for deferred logs for session: ${sessionId}`);
+    
+    // Get deferred logs for this session
+    const deferredLogsStmt = this.db.prepare(`
+      SELECT level, message, timestamp, sequence_number, args
+      FROM deferred_logs 
+      WHERE session_id = ?
+      ORDER BY sequence_number ASC
+    `);
+    const deferredLogs = deferredLogsStmt.all(sessionId);
+    
+    if (deferredLogs.length === 0) {
+      console.log(`[associateDeferredLogs] No deferred logs found for session: ${sessionId}`);
+      return { success: true, logsAssociated: 0 };
+    }
+    
+    console.log(`[associateDeferredLogs] Found ${deferredLogs.length} deferred logs, attempting to associate with frames`);
+    
+    // Convert deferred logs back to the format expected by streamLogsToFrames
+    const logs = deferredLogs.map(log => ({
+      level: log.level,
+      message: log.message,
+      timestamp: log.timestamp,
+      sequence: log.sequence_number,
+      args: log.args ? JSON.parse(log.args) : []
+    }));
+    
+    // Try to associate with frames (this will work if frames now exist)
+    const result = this.streamLogsToFrames(sessionId, logs);
+    
+    if (result.success && result.method !== 'deferred') {
+      // Successfully associated - clean up deferred logs
+      const cleanupStmt = this.db.prepare(`DELETE FROM deferred_logs WHERE session_id = ?`);
+      cleanupStmt.run(sessionId);
+      console.log(`[associateDeferredLogs] Successfully associated ${result.logsStreamed} logs and cleaned up deferred storage`);
+      
+      return {
+        success: true,
+        logsAssociated: result.logsStreamed,
+        logsDeferred: deferredLogs.length
+      };
+    }
+    
+    console.log(`[associateDeferredLogs] Frames still not available for session: ${sessionId}`);
+    return { success: false, message: 'Frames still not available' };
+  }
+
+  // Get recording by ID
+  getRecording(recordingId) {
+    this.init();
+    
+    console.log(`[getRecording] Looking for recording with ID: ${recordingId}`);
+    
+    // Handle both old format (frame_<id>) and new format (base id)
+    let baseId = recordingId;
+    if (recordingId.startsWith('frame_')) {
+      baseId = recordingId.substring(6); // Remove 'frame_' prefix
+      console.log(`[getRecording] Converting old format ID ${recordingId} to base ID: ${baseId}`);
+    }
+    
+    // Priority order: exact id match, then session_id match with frames, then any session_id match
+    // Check both the original recordingId and the baseId to handle dual compatibility
+    const stmt = this.db.prepare(`
+      SELECT * FROM recordings 
+      WHERE id = ? OR id = ? OR session_id = ? OR session_id = ? 
+      ORDER BY 
+        CASE 
+          WHEN id = ? THEN 1 
+          WHEN id = ? THEN 2
+          WHEN session_id = ? THEN 3
+          ELSE 4 
+        END,
+        total_frames DESC,
+        created_at DESC
+      LIMIT 1
+    `);
+    const recording = stmt.get(recordingId, baseId, recordingId, baseId, recordingId, baseId, recordingId);
+    
+    if (recording) {
+      console.log(`[getRecording] Found recording with ID: ${recording.id}, total_frames: ${recording.total_frames}`);
+      return recording;
+    }
+    
+    console.log(`[getRecording] No recording found for: ${recordingId} or base ID: ${baseId}`);
+    return null;
+  }
+
+  // Get frame session info
+  getFrameSessionInfo(sessionId) {
+    this.init();
+    
+    const recording = this.getRecording(sessionId);
+    if (!recording) return null;
+    
+    const frameTimestampsStmt = this.db.prepare(`
+      SELECT timestamp FROM frames 
+      WHERE recording_id = ? 
+      ORDER BY frame_index ASC
+    `);
+    const frameTimestamps = frameTimestampsStmt.all(recording.id).map(f => f.timestamp);
+    
+    return {
+      sessionId: recording.session_id,
+      totalFrames: recording.total_frames,
+      timestamp: recording.timestamp,
+      frameTimestamps: frameTimestamps
+    };
+  }
+
+  // Get specific frame
+  getFrame(sessionId, frameIndex) {
+    this.init();
+
+    const recording = this.getRecording(sessionId);
+    if (!recording) return null;
+
+    const frameStmt = this.db.prepare(`
+      SELECT * FROM frames
+      WHERE recording_id = ? AND frame_index = ?
+    `);
+    const frame = frameStmt.get(recording.id, frameIndex);
+
+    if (!frame) return null;
+
+    // Get console logs for this frame
+    const logsStmt = this.db.prepare(`
+      SELECT level, message, relative_time
+      FROM console_logs
+      WHERE frame_id = ?
+      ORDER BY relative_time ASC
+    `);
+    const rawLogs = logsStmt.all(frame.id);
+
+    // Convert snake_case field names to camelCase for frontend compatibility
+    const logs = rawLogs.map(log => ({
+      level: log.level,
+      message: log.message,
+      relativeTime: log.relative_time
+    }));
+
+    // Deserialize interactions from the frame record (legacy embedded interactions)
+    let embeddedInteractions = [];
+    try {
+      embeddedInteractions = JSON.parse(frame.interactions || '[]');
+    } catch (error) {
+      console.warn(`[getFrame] Failed to parse embedded interactions for frame ${frameIndex}:`, error);
+      embeddedInteractions = [];
+    }
+
+    // Get timestamp-associated interactions using the new method
+    const associatedInteractionsResult = this.getInteractionsForFrame(
+      recording.id,
+      frame.timestamp || frame.absolute_timestamp, // Use relative timestamp for proper association
+      500 // ±500ms window
+    );
+
+    return {
+      timestamp: frame.timestamp,
+      absoluteTimestamp: frame.absolute_timestamp,
+      imageData: frame.image_data,
+      logs: logs,
+      interactions: embeddedInteractions, // Keep legacy field for backward compatibility
+      associatedInteractions: associatedInteractionsResult.interactions,
+      interactionMetadata: associatedInteractionsResult.metadata
+    };
+  }
+
+  // Get entire frame session
+  getFrameSession(sessionId) {
+    this.init();
+    
+    const recording = this.getRecording(sessionId);
+    if (!recording) return null;
+    
+    // Debug: Check what's actually in the database
+    const allFramesStmt = this.db.prepare(`
+      SELECT COUNT(*) as count, MIN(frame_index) as min_index, MAX(frame_index) as max_index
+      FROM frames 
+      WHERE recording_id = ?
+    `);
+    const frameStats = allFramesStmt.get(recording.id);
+    console.log(`[getFrameSession] Database stats for ${recording.id}: ${frameStats.count} frames, indices ${frameStats.min_index} to ${frameStats.max_index}`);
+    
+    const framesStmt = this.db.prepare(`
+      SELECT frame_index, timestamp, absolute_timestamp, image_data, interactions
+      FROM frames
+      WHERE recording_id = ?
+      ORDER BY frame_index ASC
+    `);
+    const frames = framesStmt.all(recording.id);
+    
+    console.log(`[getFrameSession] Found ${frames.length} frames in database for session ${sessionId}`);
+    console.log(`[getFrameSession] Frame indices: [${frames.map(f => f.frame_index).join(', ')}]`);
+    
+    // Get logs and interactions for all frames
+    for (const frame of frames) {
+      const frameRowStmt = this.db.prepare(`
+        SELECT id FROM frames
+        WHERE recording_id = ? AND frame_index = ?
+      `);
+      const frameRow = frameRowStmt.get(recording.id, frame.frame_index);
+
+      if (frameRow) {
+        const logsStmt = this.db.prepare(`
+          SELECT level, message, relative_time
+          FROM console_logs
+          WHERE frame_id = ?
+          ORDER BY relative_time ASC
+        `);
+        const rawLogs = logsStmt.all(frameRow.id);
+
+        // Convert snake_case field names to camelCase for frontend compatibility
+        frame.logs = rawLogs.map(log => ({
+          level: log.level,
+          message: log.message,
+          relativeTime: log.relative_time
+        }));
+      } else {
+        frame.logs = [];
+      }
+
+      // Rename fields to match expected format and deserialize embedded interactions
+      frame.index = frame.frame_index;
+      frame.imageData = frame.image_data;
+      frame.absoluteTimestamp = frame.absolute_timestamp;
+
+      // Deserialize embedded interactions from JSON (legacy)
+      let embeddedInteractions = [];
+      try {
+        embeddedInteractions = JSON.parse(frame.interactions || '[]');
+      } catch (error) {
+        console.warn(`[getFrameSession] Failed to parse embedded interactions for frame ${frame.frame_index}:`, error);
+        embeddedInteractions = [];
+      }
+
+      // Get timestamp-associated interactions for this frame
+      const associatedInteractionsResult = this.getInteractionsForFrame(
+        recording.id,
+        frame.timestamp || frame.absolute_timestamp, // Use relative timestamp for proper association
+        500 // ±500ms window
+      );
+
+      // Set interactions fields
+      frame.interactions = embeddedInteractions; // Keep legacy field for backward compatibility
+      frame.associatedInteractions = associatedInteractionsResult.interactions;
+      frame.interactionMetadata = associatedInteractionsResult.metadata;
+
+      delete frame.frame_index;
+      delete frame.image_data;
+      delete frame.absolute_timestamp;
+    }
+    
+    // Get all interactions for this recording
+    const interactionsStmt = this.db.prepare(`
+      SELECT * FROM screen_interactions 
+      WHERE recording_id = ?
+      ORDER BY timestamp ASC
+    `);
+    const interactions = interactionsStmt.all(recording.id);
+    
+    return {
+      type: 'frame_capture',
+      sessionId: recording.session_id,
+      timestamp: recording.timestamp,
+      frames: frames,
+      interactions: interactions
+    };
+  }
+
+  // List all recordings
+  listRecordings() {
+    this.init();
+
+    const stmt = this.db.prepare(`
+      SELECT session_id, total_frames, timestamp, name
+      FROM recordings
+      WHERE type = 'frame_capture'
+      ORDER BY timestamp DESC
+    `);
+
+    return stmt.all().map(r => ({
+      id: r.session_id,
+      sessionId: r.session_id,
+      totalFrames: r.total_frames,
+      timestamp: r.timestamp,
+      name: r.name
+    }));
+  }
+
+  // Get frame screenshot data only
+  getFrameScreenshot(sessionId, frameIndex, includeMetadata = false) {
+    this.init();
+
+    const recording = this.getRecording(sessionId);
+    if (!recording) return null;
+
+    const frameStmt = this.db.prepare(`
+      SELECT image_data, timestamp, absolute_timestamp FROM frames
+      WHERE recording_id = ? AND frame_index = ?
+    `);
+    const frame = frameStmt.get(recording.id, frameIndex);
+
+    if (!frame || !frame.image_data) return null;
+
+    const result = {
+      imageData: frame.image_data.toString('base64'),
+      imageFormat: 'jpeg'
+    };
+
+    if (includeMetadata) {
+      result.metadata = {
+        sessionId: sessionId,
+        frameIndex: frameIndex,
+        timestamp: frame.timestamp,
+        absoluteTimestamp: frame.absolute_timestamp,
+        size: frame.image_data.length,
+        encoding: 'base64'
+      };
+    }
+
+    return result;
+  }
+
+  // Delete recording
+  deleteRecording(recordingId) {
+    this.init();
+
+    const recording = this.getRecording(recordingId);
+    if (!recording) return false;
+
+    const stmt = this.db.prepare(`DELETE FROM recordings WHERE id = ?`);
+    const result = stmt.run(recording.id);
+
+    return result.changes > 0;
+  }
+
+  // Delete workflow recording
+  deleteWorkflowRecording(recordingId) {
+    this.init();
+    
+    const transaction = this.db.transaction(() => {
+      // Delete associated workflow actions first
+      const deleteActionsStmt = this.db.prepare(`DELETE FROM workflow_actions WHERE workflow_id = ?`);
+      deleteActionsStmt.run(recordingId);
+      
+      // Delete workflow recording
+      const deleteRecordingStmt = this.db.prepare(`DELETE FROM workflow_recordings WHERE id = ?`);
+      const result = deleteRecordingStmt.run(recordingId);
+      
+      return result.changes > 0;
+    });
+    
+    return transaction();
+  }
+
+  // Get database stats
+  getStats() {
+    this.init();
+    
+    const recordingsCount = this.db.prepare(`SELECT COUNT(*) as count FROM recordings`).get().count;
+    const framesCount = this.db.prepare(`SELECT COUNT(*) as count FROM frames`).get().count;
+    const logsCount = this.db.prepare(`SELECT COUNT(*) as count FROM console_logs`).get().count;
+    
+    return {
+      recordings: recordingsCount,
+      frames: framesCount,
+      logs: logsCount,
+      dbPath: DB_PATH
+    };
+  }
+
+  // Store workflow recording
+  storeWorkflowRecording(sessionId, url, title, includeLogs = false, name = null, screenshotSettings = null) {
+    this.init();
+    
+    console.log('[Database] Storing workflow recording with name:', name, 'sessionId:', sessionId);
+    
+    const stmt = this.db.prepare(`
+      INSERT OR REPLACE INTO workflow_recordings (id, session_id, name, url, title, timestamp, include_logs, screenshot_settings, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, CURRENT_TIMESTAMP)
+    `);
+    
+    const recordingId = `workflow_${sessionId}`;
+    const timestamp = Date.now();
+    
+    stmt.run(
+      recordingId, 
+      sessionId, 
+      name,
+      url, 
+      title, 
+      timestamp, 
+      includeLogs ? 1 : 0,
+      screenshotSettings ? JSON.stringify(screenshotSettings) : null
+    );
+    return recordingId;
+  }
+
+  // Store workflow actions
+  storeWorkflowActions(workflowId, actions) {
+    this.init();
+
+    const stmt = this.db.prepare(`
+      INSERT OR REPLACE INTO workflow_actions
+      (workflow_id, action_index, type, selector, x, y, value, text, placeholder, timestamp,
+       screenshot_data, component, args, stack, element_html, component_data,
+       event_handlers, element_state, performance_metrics)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+
+    const transaction = this.db.transaction((actions) => {
+      let storedCount = 0;
+
+      for (const action of actions) {
+        // Helper function to safely stringify and truncate JSON data
+        const safeJsonStringify = (data, maxSize) => {
+          if (!data) return null;
+          let jsonStr = typeof data === 'string' ? data : JSON.stringify(data);
+          if (jsonStr.length > maxSize) {
+            console.warn(`[Database] Truncating data field from ${jsonStr.length} to ${maxSize} bytes`);
+            jsonStr = jsonStr.substring(0, maxSize - 50) + '...[TRUNCATED]';
+          }
+          return jsonStr;
+        };
+
+        // Helper function to safely get enhanced field data with dual naming convention support
+        const getEnhancedFieldData = (action, camelCaseName, snakeCaseName) => {
+          return action[camelCaseName] || action[snakeCaseName] || null;
+        };
+
+        stmt.run(
+          workflowId,
+          action.index,
+          action.type,
+          action.selector || '',  // Provide empty string as default for selector
+          action.x || null,
+          action.y || null,
+          action.value || null,
+          action.text || null,
+          action.placeholder || null,
+          action.timestamp,
+          action.screenshot_data || null,
+          action.component || null,  // For function traces
+          action.args ? JSON.stringify(action.args) : null,  // Store args as JSON string
+          action.stack || null,  // For function traces
+          // Enhanced click tracking data with size limits - supports both camelCase and snake_case
+          safeJsonStringify(getEnhancedFieldData(action, 'elementHTML', 'element_html'), 10240),  // 10KB limit
+          safeJsonStringify(getEnhancedFieldData(action, 'componentData', 'component_data'), 3072),  // 3KB limit
+          safeJsonStringify(getEnhancedFieldData(action, 'eventHandlers', 'event_handlers'), 2048),  // 2KB limit
+          safeJsonStringify(getEnhancedFieldData(action, 'elementState', 'element_state'), 2048),   // 2KB limit
+          safeJsonStringify(getEnhancedFieldData(action, 'performanceMetrics', 'performance_metrics'), 1024)  // 1KB limit
+        );
+        storedCount++;
+      }
+
+      return storedCount;
+    });
+
+    const storedCount = transaction(actions);
+
+    // Update total actions count
+    const updateStmt = this.db.prepare(`
+      UPDATE workflow_recordings
+      SET total_actions = ?, updated_at = CURRENT_TIMESTAMP
+      WHERE id = ?
+    `);
+    updateStmt.run(storedCount, workflowId);
+
+    return { success: true, storedCount };
+  }
+
+  // Store workflow logs
+  storeWorkflowLogs(workflowId, logs) {
+    this.init();
+    
+    const stmt = this.db.prepare(`
+      INSERT INTO workflow_logs (workflow_id, level, message, timestamp, relative_time)
+      VALUES (?, ?, ?, ?, ?)
+    `);
+    
+    const transaction = this.db.transaction((logs) => {
+      let storedCount = 0;
+      
+      for (const log of logs) {
+        // Truncate large log messages before storing
+        let message = log.message;
+        const maxMessageLength = 10000; // 10KB limit per log entry
+        
+        if (message && message.length > maxMessageLength) {
+          // Check if it's a base64 image that was already truncated by the extension
+          if (message.includes('[Base64 Image:') && message.includes('truncated...]')) {
+            // Already truncated by extension, keep as is
+          } else {
+            // Additional truncation for any other large content
+            message = message.substring(0, maxMessageLength) + `... [DB TRUNCATED: ${message.length} total bytes]`;
+          }
+        }
+        
+        stmt.run(
+          workflowId,
+          log.level,
+          message,
+          log.timestamp,
+          log.relativeTime || 0
+        );
+        storedCount++;
+      }
+      
+      return storedCount;
+    });
+    
+    const storedCount = transaction(logs);
+    
+    return { success: true, storedCount };
+  }
+
+  // Get workflow recording info
+  getWorkflowRecordingInfo(sessionId) {
+    this.init();
+    
+    const stmt = this.db.prepare(`
+      SELECT * FROM workflow_recordings 
+      WHERE session_id = ?
+    `);
+    
+    const recording = stmt.get(sessionId);
+    
+    if (!recording) {
+      return { error: 'Workflow recording not found' };
+    }
+    
+    return {
+      sessionId: recording.session_id,
+      name: recording.name,
+      url: recording.url,
+      title: recording.title,
+      timestamp: recording.timestamp,
+      totalActions: recording.total_actions,
+      includeLogs: recording.include_logs,
+      screenshotSettings: recording.screenshot_settings ? JSON.parse(recording.screenshot_settings) : null
+    };
+  }
+
+  // Get workflow actions
+  getWorkflowActions(sessionId) {
+    this.init();
+    
+    const workflowStmt = this.db.prepare(`
+      SELECT id FROM workflow_recordings 
+      WHERE session_id = ?
+    `);
+    
+    const recording = workflowStmt.get(sessionId);
+    
+    if (!recording) {
+      return { error: 'Workflow recording not found' };
+    }
+    
+    const actionsStmt = this.db.prepare(`
+      SELECT * FROM workflow_actions 
+      WHERE workflow_id = ?
+      ORDER BY action_index ASC
+    `);
+    
+    const actions = actionsStmt.all(recording.id);
+    
+    return actions.map(action => {
+      const result = {
+        type: action.type,
+        selector: action.selector,
+        x: action.x,
+        y: action.y,
+        value: action.value,
+        text: action.text,
+        placeholder: action.placeholder,
+        timestamp: action.timestamp,
+        screenshot_data: action.screenshot_data
+      };
+
+      // Add function trace fields if they exist
+      if (action.component) {
+        result.component = action.component;
+      }
+      if (action.args) {
+        try {
+          result.args = JSON.parse(action.args);
+        } catch (e) {
+          result.args = action.args;
+        }
+      }
+      if (action.stack) {
+        result.stack = action.stack;
+      }
+
+      // Add enhanced click tracking fields if they exist
+      if (action.element_html) {
+        try {
+          result.elementHTML = JSON.parse(action.element_html);
+        } catch (e) {
+          result.elementHTML = action.element_html;
+        }
+      }
+      if (action.component_data) {
+        try {
+          result.componentData = JSON.parse(action.component_data);
+        } catch (e) {
+          result.componentData = action.component_data;
+        }
+      }
+      if (action.event_handlers) {
+        try {
+          result.eventHandlers = JSON.parse(action.event_handlers);
+        } catch (e) {
+          result.eventHandlers = action.event_handlers;
+        }
+      }
+      if (action.element_state) {
+        try {
+          result.elementState = JSON.parse(action.element_state);
+        } catch (e) {
+          result.elementState = action.element_state;
+        }
+      }
+      if (action.performance_metrics) {
+        try {
+          result.performanceMetrics = JSON.parse(action.performance_metrics);
+        } catch (e) {
+          result.performanceMetrics = action.performance_metrics;
+        }
+      }
+
+      return result;
+    });
+  }
+
+  // Get workflow logs
+  getWorkflowLogs(sessionId) {
+    this.init();
+    
+    const workflowStmt = this.db.prepare(`
+      SELECT id FROM workflow_recordings 
+      WHERE session_id = ?
+    `);
+    
+    const recording = workflowStmt.get(sessionId);
+    
+    if (!recording) {
+      return { error: 'Workflow recording not found' };
+    }
+    
+    const logsStmt = this.db.prepare(`
+      SELECT * FROM workflow_logs 
+      WHERE workflow_id = ?
+      ORDER BY timestamp ASC
+    `);
+    
+    const logs = logsStmt.all(recording.id);
+    
+    return logs.map(log => ({
+      level: log.level,
+      message: log.message,
+      timestamp: log.timestamp,
+      relativeTime: log.relative_time
+    }));
+  }
+
+  // Get complete workflow recording
+  getWorkflowRecording(sessionId) {
+    this.init();
+    
+    const info = this.getWorkflowRecordingInfo(sessionId);
+    if (info.error) {
+      return info;
+    }
+    
+    const actions = this.getWorkflowActions(sessionId);
+    const logs = info.includeLogs ? this.getWorkflowLogs(sessionId) : [];
+    
+    return {
+      type: 'workflow_recording',
+      sessionId: info.sessionId,
+      name: info.name,
+      url: info.url,
+      title: info.title,
+      timestamp: info.timestamp,
+      totalActions: info.totalActions,
+      screenshotSettings: info.screenshotSettings,
+      actions: actions,
+      logs: logs
+    };
+  }
+
+  // List all workflow recordings
+  listWorkflowRecordings() {
+    this.init();
+    
+    const stmt = this.db.prepare(`
+      SELECT id, session_id, name, url, title, total_actions, timestamp, screenshot_settings
+      FROM workflow_recordings 
+      ORDER BY timestamp DESC
+    `);
+    
+    return stmt.all().map(r => ({
+      id: r.id,
+      session_id: r.session_id,
+      name: r.name,
+      url: r.url,
+      title: r.title,
+      total_actions: r.total_actions,
+      timestamp: r.timestamp,
+      screenshot_settings: r.screenshot_settings ? JSON.parse(r.screenshot_settings) : null
+    }));
+  }
+
+  // Clear all workflow recordings
+  clearWorkflowRecordings() {
+    this.init();
+    
+    const transaction = this.db.transaction(() => {
+      // Delete all workflow logs
+      const deleteLogsStmt = this.db.prepare(`DELETE FROM workflow_logs`);
+      deleteLogsStmt.run();
+      
+      // Delete all workflow actions
+      const deleteActionsStmt = this.db.prepare(`DELETE FROM workflow_actions`);
+      deleteActionsStmt.run();
+      
+      // Delete all restore points
+      const deleteRestorePointsStmt = this.db.prepare(`DELETE FROM restore_points`);
+      deleteRestorePointsStmt.run();
+      
+      // Delete all workflow recordings
+      const deleteRecordingsStmt = this.db.prepare(`DELETE FROM workflow_recordings`);
+      const result = deleteRecordingsStmt.run();
+      
+      console.log(`[Database] Cleared workflow recordings: ${result.changes} recordings deleted`);
+      return result.changes;
+    });
+    
+    return transaction();
+  }
+
+  // Store restore point
+  storeRestorePoint(workflowId, actionIndex, restoreData) {
+    this.init();
+    
+    const stmt = this.db.prepare(`
+      INSERT OR REPLACE INTO restore_points 
+      (id, workflow_id, action_index, timestamp, url, title, dom_snapshot, 
+       scroll_x, scroll_y, local_storage, session_storage, cookies, console_logs)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+    
+    const restorePointId = `restore_${workflowId}_${actionIndex}_${Date.now()}`;
+    
+    try {
+      stmt.run(
+        restorePointId,
+        workflowId,
+        actionIndex,
+        Date.now(),
+        restoreData.url,
+        restoreData.title,
+        JSON.stringify(restoreData.domSnapshot),
+        restoreData.scrollX || 0,
+        restoreData.scrollY || 0,
+        JSON.stringify(restoreData.localStorage || {}),
+        JSON.stringify(restoreData.sessionStorage || {}),
+        JSON.stringify(restoreData.cookies || []),
+        JSON.stringify(restoreData.consoleLogs || [])
+      );
+      
+      return { success: true, restorePointId };
+    } catch (error) {
+      console.error('Error storing restore point:', error);
+      return { success: false, error: error.message };
+    }
+  }
+
+  // Get restore point
+  getRestorePoint(restorePointId) {
+    this.init();
+    
+    const stmt = this.db.prepare(`
+      SELECT * FROM restore_points WHERE id = ?
+    `);
+    
+    const restorePoint = stmt.get(restorePointId);
+    
+    if (!restorePoint) {
+      return { error: 'Restore point not found' };
+    }
+    
+    return {
+      id: restorePoint.id,
+      workflowId: restorePoint.workflow_id,
+      actionIndex: restorePoint.action_index,
+      timestamp: restorePoint.timestamp,
+      url: restorePoint.url,
+      title: restorePoint.title,
+      domSnapshot: JSON.parse(restorePoint.dom_snapshot),
+      scrollX: restorePoint.scroll_x,
+      scrollY: restorePoint.scroll_y,
+      localStorage: JSON.parse(restorePoint.local_storage),
+      sessionStorage: JSON.parse(restorePoint.session_storage),
+      cookies: JSON.parse(restorePoint.cookies),
+      consoleLogs: JSON.parse(restorePoint.console_logs)
+    };
+  }
+
+  // List restore points for a workflow
+  listRestorePoints(workflowId) {
+    this.init();
+    
+    const stmt = this.db.prepare(`
+      SELECT id, action_index, timestamp, url, title 
+      FROM restore_points 
+      WHERE workflow_id = ?
+      ORDER BY action_index ASC, timestamp DESC
+    `);
+    
+    return stmt.all(workflowId).map(rp => ({
+      id: rp.id,
+      actionIndex: rp.action_index,
+      timestamp: rp.timestamp,
+      url: rp.url,
+      title: rp.title
+    }));
+  }
+
+  // Close database
+  // Server instance tracking methods
+  async registerServerInstance(pid, mode) {
+    this.init();
+    
+    // Clean up old entries first
+    await this.cleanupDeadServerInstances();
+    
+    const stmt = this.db.prepare(`
+      INSERT OR REPLACE INTO server_instances (pid, mode)
+      VALUES (?, ?)
+    `);
+    
+    stmt.run(pid, mode);
+    console.log(`Registered server instance: PID ${pid}, mode: ${mode}`);
+  }
+  
+  async getSingleServerInstance() {
+    this.init();
+    
+    // Clean up dead processes first
+    await this.cleanupDeadServerInstances();
+    
+    const stmt = this.db.prepare(`
+      SELECT pid FROM server_instances 
+      WHERE mode = 'single-server'
+      ORDER BY started_at DESC
+      LIMIT 1
+    `);
+    
+    const result = stmt.get();
+    return result ? result.pid : null;
+  }
+  
+  async cleanupDeadServerInstances() {
+    this.init();
+    
+    const stmt = this.db.prepare(`SELECT pid FROM server_instances`);
+    const instances = stmt.all();
+    
+    const { exec } = await import('child_process');
+    const { promisify } = await import('util');
+    const execAsync = promisify(exec);
+    
+    for (const instance of instances) {
+      try {
+        // Check if process is still running
+        await execAsync(`ps -p ${instance.pid}`);
+        // Process is still running, keep it
+      } catch (error) {
+        // Process is dead, remove it
+        const deleteStmt = this.db.prepare(`DELETE FROM server_instances WHERE pid = ?`);
+        deleteStmt.run(instance.pid);
+        console.log(`Cleaned up dead server instance: PID ${instance.pid}`);
+      }
+    }
+  }
+  
+  unregisterServerInstance(pid) {
+    this.init();
+    
+    const stmt = this.db.prepare(`DELETE FROM server_instances WHERE pid = ?`);
+    const result = stmt.run(pid);
+    
+    if (result.changes > 0) {
+      console.log(`Unregistered server instance: PID ${pid}`);
+    }
+  }
+
+  // Store screen interactions for a recording
+  storeScreenInteractions(recordingId, interactions) {
+    this.init();
+    
+    // Ensure a recording exists for this ID
+    const checkStmt = this.db.prepare(`SELECT id FROM recordings WHERE id = ?`);
+    const existingRecord = checkStmt.get(recordingId);
+    
+    if (!existingRecord) {
+      // Create a recording record if it doesn't exist
+      const insertRecordingStmt = this.db.prepare(`
+        INSERT INTO recordings (id, session_id, type, timestamp, updated_at)
+        VALUES (?, ?, ?, ?, CURRENT_TIMESTAMP)
+      `);
+      insertRecordingStmt.run(recordingId, recordingId, 'screen_recording', Date.now());
+    }
+    
+    const stmt = this.db.prepare(`
+      INSERT OR REPLACE INTO screen_interactions
+      (recording_id, interaction_index, type, selector, xpath, x, y, value, text, key, timestamp, frame_index,
+       element_html, component_data, event_handlers, element_state, performance_metrics)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+    
+    const transaction = this.db.transaction(() => {
+      interactions.forEach((interaction, index) => {
+        stmt.run(
+          recordingId,
+          index,
+          interaction.type,
+          interaction.selector || null,
+          interaction.xpath || null,
+          interaction.x || null,
+          interaction.y || null,
+          interaction.value || null,
+          interaction.text || null,
+          interaction.key || null,
+          interaction.timestamp,
+          interaction.frameIndex || null,
+          // Enhanced fields - handle mixed string/object types correctly
+          interaction.element_html || null, // This is a string, store directly
+          interaction.component_data ? JSON.stringify(interaction.component_data) : null,
+          interaction.event_handlers ? JSON.stringify(interaction.event_handlers) : null,
+          interaction.element_state ? JSON.stringify(interaction.element_state) : null,
+          interaction.performance_metrics ? JSON.stringify(interaction.performance_metrics) : null
+        );
+      });
+    });
+    
+    try {
+      transaction();
+      return { success: true, count: interactions.length };
+    } catch (error) {
+      console.error('Error storing screen interactions:', error);
+      return { success: false, error: error.message };
+    }
+  }
+
+  // Get screen interactions for a recording
+  getScreenInteractions(recordingId) {
+    this.init();
+
+    // Apply same ID resolution logic as getRecording() method
+    // Handle both old format (frame_<id>) and new format (base id)
+    let baseId = recordingId;
+    if (recordingId.startsWith('frame_')) {
+      baseId = recordingId.substring(6); // Remove 'frame_' prefix
+      console.log(`[getScreenInteractions] Converting old format ID ${recordingId} to base ID: ${baseId}`);
+    }
+
+    // Priority order: exact recording_id match, then baseId match
+    // Check both the original recordingId and the baseId to handle dual compatibility
+    const stmt = this.db.prepare(`
+      SELECT * FROM screen_interactions
+      WHERE recording_id = ? OR recording_id = ?
+      ORDER BY
+        CASE
+          WHEN recording_id = ? THEN 1
+          WHEN recording_id = ? THEN 2
+          ELSE 3
+        END,
+        interaction_index ASC
+    `);
+
+    return stmt.all(recordingId, baseId, recordingId, baseId);
+  }
+
+  // Get interactions for a specific frame
+  getFrameInteractions(recordingId, frameIndex) {
+    this.init();
+
+    const stmt = this.db.prepare(`
+      SELECT * FROM screen_interactions
+      WHERE recording_id = ? AND frame_index = ?
+      ORDER BY timestamp ASC
+    `);
+
+    return stmt.all(recordingId, frameIndex);
+  }
+
+  // Get interactions associated with a frame by timestamp window
+  getInteractionsForFrame(recordingId, frameTimestamp, windowMs = 500) {
+    this.init();
+
+    const lowerBound = frameTimestamp - windowMs;
+    const upperBound = frameTimestamp + windowMs;
+
+    const stmt = this.db.prepare(`
+      SELECT
+        id,
+        interaction_index,
+        type,
+        selector,
+        xpath,
+        x,
+        y,
+        value,
+        text,
+        key,
+        timestamp,
+        frame_index,
+        ABS(timestamp - ?) as time_diff
+      FROM screen_interactions
+      WHERE recording_id = ?
+        AND timestamp BETWEEN ? AND ?
+      ORDER BY time_diff ASC, timestamp ASC
+      LIMIT 10
+    `);
+
+    const interactions = stmt.all(frameTimestamp, recordingId, lowerBound, upperBound);
+
+    // Diagnostic logging for interaction association debugging
+    console.log(`[getInteractionsForFrame] DEBUGGING - recordingId: ${recordingId}, frameTimestamp: ${frameTimestamp}, window: ±${windowMs}ms`);
+    console.log(`[getInteractionsForFrame] Search range: ${lowerBound} to ${upperBound}`);
+    console.log(`[getInteractionsForFrame] Found ${interactions.length} interactions`);
+    if (interactions.length > 0) {
+      console.log(`[getInteractionsForFrame] First interaction:`, interactions[0]);
+    }
+
+    // Convert to InteractionData format with metadata
+    const result = interactions.map(interaction => ({
+      id: interaction.id,
+      index: interaction.interaction_index,
+      type: interaction.type,
+      selector: interaction.selector,
+      xpath: interaction.xpath,
+      x: interaction.x,
+      y: interaction.y,
+      value: interaction.value,
+      text: interaction.text,
+      key: interaction.key,
+      timestamp: interaction.timestamp,
+      frameIndex: interaction.frame_index,
+      timeDifference: interaction.time_diff
+    }));
+
+    // Add metadata
+    const totalFoundStmt = this.db.prepare(`
+      SELECT COUNT(*) as count
+      FROM screen_interactions
+      WHERE recording_id = ?
+        AND timestamp BETWEEN ? AND ?
+    `);
+    const totalFound = totalFoundStmt.get(recordingId, lowerBound, upperBound).count;
+
+    return {
+      interactions: result,
+      metadata: {
+        totalFound: totalFound,
+        displayed: result.length,
+        timeWindow: windowMs,
+        frameTimestamp: frameTimestamp,
+        searchRange: {
+          start: lowerBound,
+          end: upperBound
+        }
+      }
+    };
+  }
+
+  // Store execution trace data
+  storeExecutionTrace(recordingId, event) {
+    this.init();
+    
+    // Generate a trace_index if not provided (use timestamp + random for uniqueness)
+    const traceIndex = event.trace_index || Date.now() + Math.floor(Math.random() * 1000);
+    
+    const stmt = this.db.prepare(`
+      INSERT OR REPLACE INTO execution_traces (
+        recording_id, trace_index, timestamp, function_name, function_source,
+        arguments, return_value, error, call_stack, execution_time_ms
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+    
+    // Build call stack info from the event data
+    const callStackInfo = {
+      call_id: event.call_id,
+      call_depth: event.call_depth || 0,
+      parent_call_id: event.parent_call_id,
+      category: event.category || 'unknown',
+      metadata: event.metadata || {}
+    };
+    
+    return stmt.run(
+      recordingId,
+      traceIndex,
+      event.timestamp || Date.now(),
+      event.function_name,
+      event.function_source || null, // Source location if available
+      JSON.stringify(event.arguments || []),
+      JSON.stringify(event.return_value),
+      event.error,
+      JSON.stringify(callStackInfo),
+      event.execution_time_ms || 0
+    );
+  }
+
+  // Store variable state data
+  storeVariableState(recordingId, event) {
+    this.init();
+    
+    const stmt = this.db.prepare(`
+      INSERT INTO variable_states (
+        recording_id, timestamp, scope_chain, variables, heap_snapshot
+      ) VALUES (?, ?, ?, ?, ?)
+    `);
+    
+    // Build variables object from event data
+    const variables = {
+      [event.variable_name || 'unknown']: event.variable_value,
+      call_id: event.call_id,
+      capture_point: event.capture_point || 'unknown'
+    };
+    
+    const scopeChain = {
+      scope: event.scope || 'unknown',
+      call_id: event.call_id
+    };
+    
+    return stmt.run(
+      recordingId,
+      event.timestamp || Date.now(),
+      JSON.stringify(scopeChain),
+      JSON.stringify(variables),
+      null // heap_snapshot - not captured yet
+    );
+  }
+
+  // Store DOM mutation data
+  storeDomMutation(recordingId, event) {
+    this.init();
+    
+    const stmt = this.db.prepare(`
+      INSERT INTO dom_mutations (
+        recording_id, timestamp, mutation_type, target_selector, 
+        target_xpath, old_value, new_value, attributes_changed
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+    
+    // Build attributes changed object
+    const attributesChanged = {
+      attribute_name: event.attribute_name,
+      added_nodes: event.added_nodes || [],
+      removed_nodes: event.removed_nodes || []
+    };
+    
+    return stmt.run(
+      recordingId,
+      event.timestamp || Date.now(),
+      event.mutation_type,
+      event.target_selector,
+      event.target_xpath,
+      event.old_value,
+      event.new_value,
+      JSON.stringify(attributesChanged)
+    );
+  }
+
+  // Store network request data
+  storeNetworkRequest(recordingId, event) {
+    this.init();
+    
+    const stmt = this.db.prepare(`
+      INSERT INTO network_requests (
+        recording_id, timestamp, request_id, method, url, 
+        headers, body, response_status, response_headers, 
+        response_body, duration_ms
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+    
+    return stmt.run(
+      recordingId,
+      event.timestamp || Date.now(),
+      event.request_id || 'req_' + Date.now(),
+      event.method,
+      event.url,
+      JSON.stringify(event.request_headers || {}),
+      event.request_body,
+      event.status_code || event.response_status,
+      JSON.stringify(event.response_headers || {}),
+      event.response_body,
+      event.duration_ms || 0
+    );
+  }
+
+  // Store performance metric data
+  storePerformanceMetric(recordingId, event) {
+    this.init();
+    
+    const stmt = this.db.prepare(`
+      INSERT INTO performance_metrics (
+        recording_id, timestamp, metric_type, metric_name, 
+        metric_value, metadata
+      ) VALUES (?, ?, ?, ?, ?, ?)
+    `);
+    
+    return stmt.run(
+      recordingId,
+      event.timestamp || Date.now(),
+      event.metric_type || 'unknown',
+      event.metric_name,
+      event.metric_value,
+      JSON.stringify(event.metadata || {})
+    );
+  }
+
+  close() {
+    if (this.db) {
+      this.db.close();
+      this.initialized = false;
+    }
+  }
+}
+
+// Export singleton instance
+export const database = new ChromePilotDatabase();