ContextScript.js

// /ContextScript.js

import { PluginRegistry } from './modules/core/PluginRegistry.js';
import { Configuration } from './modules/core/Configuration.js';
import { Settings } from './modules/core/Settings.js';
import { EventCapture } from './modules/EventCapture.js';
import { MouseRecognizer } from './modules/MouseRecognizer.js';
import { KeyboardRecognizer } from './modules/KeyboardRecognizer.js';
import { GlobalKeyRecognizer } from './modules/GlobalKeyRecognizer.js';
import { ScrollRecognizer } from './modules/ScrollRecognizer.js';
import { ClipboardRecognizer } from './modules/ClipboardRecognizer.js';
import { FormRecognizer } from './modules/FormRecognizer.js';
import { WindowRecognizer } from './modules/WindowRecognizer.js';
import { DragDropRecognizer } from './modules/DragDropRecognizer.js';
import { MediaRecognizer } from './modules/MediaRecognizer.js';
import { TouchRecognizer } from './modules/TouchRecognizer.js';
import { PointerRecognizer } from './modules/PointerRecognizer.js';
import { DeveloperRecognizer } from './modules/DeveloperRecognizer.js';
import { NavigationRecognizer } from './modules/NavigationRecognizer.js';
import { Coalescer } from './modules/Coalescer.js';
import { TextFormatter } from './modules/TextFormatter.js';
import { RecordingIndicator } from './modules/ui/RecordingIndicator.js';
import { TranscriptOutput } from './modules/ui/TranscriptOutput.js';
import { InstructionOverlay } from './modules/ui/InstructionOverlay.js';

class ContextScript {
  static instance = null;

  constructor() {
    if (ContextScript.instance) {
      return ContextScript.instance;
    }
    ContextScript.instance = this;

    // Initialize plugin registry and register built-in plugins
    this.#registry = new PluginRegistry();
    this.#registerBuiltinPlugins();

    // Initialize configuration after plugins are registered
    this.#config = new Configuration(this.#registry);
    this.#config.onCategoryChange = (category, enabled) => {
      this.#handleCategoryChange(category, enabled);
    };

    // Initialize core modules
    this.#eventCapture = new EventCapture();
    this.#coalescer = new Coalescer();
    this.#textFormatter = new TextFormatter(this.#registry);
    this.#recordingIndicator = new RecordingIndicator();
    this.#transcriptOutput = new TranscriptOutput();
    this.#instructionOverlay = new InstructionOverlay();

    this.#bindEventHandlers();
  }

  // Public API

  // Configuration options
  streamToConsole = true;
  headless = false;
  onEvent = null;
  eventFilter = null;

  // Access to configuration for programmatic use
  get config() {
    return this.#config;
  }

  // Format a raw event object into its display text representation.
  // Returns the formatted string, or null if the event type has no formatter.
  formatEvent(event) {
    return this.#textFormatter.formatEvent(event);
  }

  // Starts recording user actions.
  start() {
    if (this.#isRecording) {
      console.log('Already recording.');
      return;
    }

    this.#isRecording = true;
    this.#startTime = Date.now();
    this.#coalescer.reset();

    // Reset all registered plugins
    for (const plugin of this.#registry.getAllPlugins()) {
      if (plugin.reset) {
        plugin.reset();
      }
    }

    // Get event definitions only for enabled categories
    const enabledCategories = this.#config.getEnabledCategories();
    const eventDefs = this.#registry.getEventDefinitions(enabledCategories);
    this.#eventCapture.start(eventDefs);

    // Start polling for scroll if scroll category is enabled
    const scrollPlugin = this.#registry.getPlugin('scroll');
    if (scrollPlugin && this.#config.isEnabled('scroll')) {
      scrollPlugin.startPolling();
    }

    // Install API hooks for developer category if enabled
    const developerPlugin = this.#registry.getPlugin('developer');
    if (developerPlugin && this.#config.isEnabled('developer')) {
      developerPlugin.install((action) => this.#emitToCoalescer(action));
    }

    // Install History API interceptors for navigation category if enabled
    const navigationPlugin = this.#registry.getPlugin('navigation');
    if (navigationPlugin && this.#config.isEnabled('navigation')) {
      navigationPlugin.install((action) => this.#emitToCoalescer(action));
    }

    if (!this.headless) {
      this.#recordingIndicator.show();
      console.log('Recording started. Press Command+Escape to end recording.');
    }
  }

  /**
   * Ends recording and optionally shows the transcript.
   * @param {Object} options - End options
   * @param {boolean} options.silent - If true, returns transcript without showing UI (default: false)
   * @param {string} options.format - Export format: 'plaintext', 'json', 'xml', 'markdown' (default: 'plaintext')
   * @returns {string} The formatted transcript
   */
  end(options = {}) {
    const { silent = false, format = 'plaintext' } = options;

    if (!this.#isRecording) {
      console.log('Not recording.');
      return '';
    }

    this.#isRecording = false;
    this.#eventCapture.stop();

    // Stop polling for scroll
    const scrollPlugin = this.#registry.getPlugin('scroll');
    if (scrollPlugin) {
      scrollPlugin.stopPolling();
    }

    // Uninstall API hooks for developer
    const developerPlugin = this.#registry.getPlugin('developer');
    if (developerPlugin) {
      developerPlugin.uninstall();
    }

    // Uninstall History API interceptors for navigation
    const navigationPlugin = this.#registry.getPlugin('navigation');
    if (navigationPlugin) {
      navigationPlugin.uninstall();
    }

    if (!this.headless) {
      this.#recordingIndicator.hide();
    }

    this.#flushPendingEvents();

    const duration = Date.now() - this.#startTime;
    const events = this.#coalescer.events;
    const transcript = this.#textFormatter.formatAs(events, duration, format);

    if (!this.headless) {
      console.log(transcript);

      // Only show UI if not in silent mode
      if (!silent) {
        this.#transcriptOutput.show({
          events,
          duration,
          formatter: this.#textFormatter
        });
      }
    }

    return transcript;
  }

  get isRecording() {
    return this.#isRecording;
  }

  /**
   * Gets the current transcript without stopping recording.
   * Useful for LLM tools to peek at progress or capture after user stops via shortcut.
   * @param {string} format - Export format: 'plaintext', 'json', 'xml', 'markdown' (default: 'plaintext')
   * @returns {string} The formatted transcript
   */
  getTranscript(format = 'plaintext') {
    this.#flushPendingEvents();
    const duration = Date.now() - this.#startTime;
    const events = this.#coalescer.events;
    return this.#textFormatter.formatAs(events, duration, format);
  }

  /**
   * Gets the raw events array for programmatic access.
   * @returns {Array} Copy of the events array
   */
  getEvents() {
    this.#flushPendingEvents();
    return [...this.#coalescer.events];
  }

  /**
   * Shows an instruction overlay to the user before recording.
   * Useful for AI agents to display a message asking users to demonstrate an issue.
   * @param {Object} options - Display options
   * @param {string} options.message - Custom message to display (optional)
   * @returns {Promise<{startRecording: boolean}>} Resolves with startRecording: true if user clicked Start, false if dismissed
   */
  async prompt(options = {}) {
    const result = await this.#instructionOverlay.show(options);

    if (result.startRecording && !this.#isRecording) {
      this.start();
    }

    return result;
  }

  // Private

  #isRecording = false;
  #startTime = 0;
  #registry;
  #config;
  #eventCapture;
  #coalescer;
  #textFormatter;
  #recordingIndicator;
  #transcriptOutput;
  #instructionOverlay;
  #keydownHandler;

  #shouldEmit(action) {
    if (!this.eventFilter) return true;
    try { return this.eventFilter(action) !== false; }
    catch { return true; }
  }

  #emitToCoalescer(action) {
    if (this.#shouldEmit(action)) {
      this.#coalescer.add(action);
    }
  }

  // Registers the built-in recognizer plugins.
  #registerBuiltinPlugins() {
    this.#registry.register(new MouseRecognizer());
    this.#registry.register(new KeyboardRecognizer());
    this.#registry.register(new GlobalKeyRecognizer());
    this.#registry.register(new ScrollRecognizer());
    this.#registry.register(new ClipboardRecognizer());
    this.#registry.register(new FormRecognizer());
    this.#registry.register(new WindowRecognizer());
    this.#registry.register(new DragDropRecognizer());
    this.#registry.register(new MediaRecognizer());
    this.#registry.register(new TouchRecognizer());
    this.#registry.register(new PointerRecognizer());
    this.#registry.register(new DeveloperRecognizer());
    this.#registry.register(new NavigationRecognizer());
  }

  // Binds the event handlers between modules.
  #bindEventHandlers() {
    // Route events from EventCapture to appropriate plugins
    this.#eventCapture.onEvent = (type, event) => {
      this.#handleEvent(type, event);
    };

    // Flush GlobalKeyRecognizer before adding non-globalkey events
    // This ensures correct event ordering (e.g., typed keys appear before the click that interrupted them)
    this.#coalescer.onBeforeAdd = (event) => {
      // Don't flush for globalkey events (they come from GlobalKeyRecognizer itself)
      if (event.type === 'shortcut' || event.type === 'global-type') {
        return;
      }

      // Don't reset for developer events (console logs, errors, etc.)
      // These shouldn't reset the log counter - only user-initiated events should
      const developerEventTypes = [
        'console_log', 'console_warn', 'console_error', 'console_info', 'console_debug',
        'fetch_error', 'fetch_status', 'uncaught_error', 'unhandled_rejection', 'logs_truncated'
      ];
      if (developerEventTypes.includes(event.type)) {
        return;
      }

      // Flush GlobalKeyRecognizer's pending buffer
      const globalKeyPlugin = this.#registry.getPlugin('globalkey');
      if (globalKeyPlugin && globalKeyPlugin.flush) {
        globalKeyPlugin.flush();
      }

      // Reset developer log counter on user events (for truncation feature)
      const developerPlugin = this.#registry.getPlugin('developer');
      if (developerPlugin && developerPlugin.resetLogCounter) {
        developerPlugin.resetLogCounter();
      }
    };

    // Route actions from coalescer to formatter for streaming output and token counting
    this.#coalescer.onEvent = (event) => {
      const line = this.#textFormatter.formatEvent(event);
      if (line) {
        if (this.streamToConsole) {
          console.log(line);
        }
        if (this.onEvent) {
          this.onEvent({ event, formatted: line });
        }
        // Update token estimate
        this.#updateTokenEstimate();
      }
    };

    // Global keyboard shortcuts
    this.#keydownHandler = (e) => {
      // Cmd+Escape ends recording
      if (e.metaKey && e.key === 'Escape') {
        e.preventDefault();
        this.end();
        return;
      }

      // Launch shortcut toggles recording
      if (Settings.matchesShortcut(e, Settings.get('launchShortcut'))) {
        e.preventDefault();
        if (this.#isRecording) {
          this.end();
        } else {
          this.start();
        }
      }
    };

    document.addEventListener('keydown', this.#keydownHandler);

    // Dump transcript to console if browser closes while recording
    // This allows LLM tools to capture the transcript from console logs
    window.addEventListener('beforeunload', () => {
      if (this.#isRecording) {
        this.#flushPendingEvents();
        const duration = Date.now() - this.#startTime;
        const events = this.#coalescer.events;
        const transcript = this.#textFormatter.format(events, duration);
        console.log('=== ContextScript Recording (browser closing) ===');
        console.log(transcript);
        console.log('=== End Recording ===');
      }
    });
  }

  // Routes events to the appropriate plugin handlers.
  #handleEvent(type, event) {
    const entries = this.#registry.getPluginsForEvent(type);

    for (const { plugin } of entries) {
      // Skip if this plugin's category is disabled
      if (!this.#config.isEnabled(plugin.category)) {
        continue;
      }

      const handler = plugin.handlers[type];
      if (handler) {
        // Create emit function that routes actions to coalescer
        const emit = (action) => {
          this.#emitToCoalescer(action);
        };
        handler(event, emit);
      }
    }
  }

  // Handles category enable/disable changes during recording.
  #handleCategoryChange(category, enabled) {
    if (!this.#isRecording) {
      return;
    }

    const plugins = this.#registry.getPluginsByCategory(category);

    if (enabled) {
      // Re-attach listeners for this category
      const eventDefs = [];
      for (const plugin of plugins) {
        if (plugin.events) {
          eventDefs.push(...plugin.events);
        }
        // Start polling if scroll was re-enabled
        if (plugin.id === 'scroll' && plugin.startPolling) {
          plugin.startPolling();
        }
        // Install API hooks if developer was re-enabled
        if (plugin.id === 'developer' && plugin.install) {
          plugin.install((action) => this.#emitToCoalescer(action));
        }
        // Install History API interceptors if navigation was re-enabled
        if (plugin.id === 'navigation' && plugin.install) {
          plugin.install((action) => this.#emitToCoalescer(action));
        }
      }
      this.#eventCapture.addListeners(eventDefs);
    } else {
      // Remove listeners for this category
      const eventTypes = new Set();
      for (const plugin of plugins) {
        if (plugin.events) {
          for (const eventDef of plugin.events) {
            eventTypes.add(eventDef.type);
          }
        }
        // Stop polling if scroll was disabled
        if (plugin.id === 'scroll' && plugin.stopPolling) {
          plugin.stopPolling();
        }
        // Uninstall API hooks if developer was disabled
        if (plugin.id === 'developer' && plugin.uninstall) {
          plugin.uninstall();
        }
        // Uninstall History API interceptors if navigation was disabled
        if (plugin.id === 'navigation' && plugin.uninstall) {
          plugin.uninstall();
        }
      }
      this.#eventCapture.removeListeners(Array.from(eventTypes));
    }
  }

  // Flushes any pending buffered events from plugins.
  #flushPendingEvents() {
    for (const plugin of this.#registry.getAllPlugins()) {
      if (plugin.flush) {
        plugin.flush();
      }
    }
  }

  // Updates the token estimate displayed in the recording indicator.
  #updateTokenEstimate() {
    const events = this.#coalescer.events;
    const duration = Date.now() - this.#startTime;
    const transcript = this.#textFormatter.format(events, duration);
    const tokens = RecordingIndicator.estimateTokens(transcript);
    this.#recordingIndicator.updateTokens(tokens);
  }
}

// Singleton instance - created once on module load
let recorderInstance = null;

// Gets or creates the singleton recorder instance
function getRecorderInstance() {
  if (!recorderInstance) {
    recorderInstance = new ContextScript();
  }
  return recorderInstance;
}

// Initialize the recorder instance immediately so the global shortcut handler is registered
getRecorderInstance();

// Create a proxy for console configuration API
// Allows: ContextScript.help, ContextScript.scroll = false, etc.
const createConfigProxy = () => {
  const recorder = getRecorderInstance();

  return new Proxy({}, {
    get(_target, prop) {
      // Toggle recording when just accessing ContextScript
      if (prop === Symbol.toPrimitive || prop === 'valueOf' || prop === 'toString') {
        return () => {
          if (recorder.isRecording) {
            recorder.end();
          } else {
            recorder.start();
          }
          return recorder;
        };
      }

      // Show help
      if (prop === 'help') {
        recorder.config.showHelp();
        return recorder;
      }

      // Return the recorder instance
      if (prop === 'instance') {
        return recorder;
      }

      // Check if it's a category toggle
      if (recorder.config.hasCategory(prop)) {
        return recorder.config.isEnabled(prop);
      }

      // Handle maskPasswords option
      if (prop === 'maskPasswords') {
        return KeyboardRecognizer.maskPasswords;
      }

      // Handle shortcut getter
      if (prop === 'shortcut') {
        return Settings.get('launchShortcut');
      }

      // Handle resetShortcut function
      if (prop === 'resetShortcut') {
        return () => {
          Settings.reset('launchShortcut');
          console.log(`Shortcut reset to: ${Settings.DEFAULTS.launchShortcut}`);
        };
      }

      // Default: return property from recorder (bind methods so private fields work)
      const value = recorder[prop];
      if (typeof value === 'function') {
        return value.bind(recorder);
      }
      return value;
    },

    set(_target, prop, value) {
      // Handle category toggles
      if (recorder.config.hasCategory(prop)) {
        recorder.config.setEnabled(prop, value);
        console.log(`${prop} capture: ${value ? 'enabled' : 'disabled'}`);
        return true;
      }

      // Handle maskPasswords option
      if (prop === 'maskPasswords') {
        KeyboardRecognizer.maskPasswords = value;
        console.log(`Password masking: ${value ? 'enabled' : 'disabled'}`);
        return true;
      }

      // Handle shortcut setter
      if (prop === 'shortcut') {
        Settings.set('launchShortcut', value);
        console.log(`Launch shortcut set to: ${value}`);
        return true;
      }

      // Default: set on recorder
      recorder[prop] = value;
      return true;
    }
  });
};

// Expose ContextScript globally for console use
// Allows: ContextScript.start(), ContextScript.end(), ContextScript.scroll = false, etc.
window.ContextScript = createConfigProxy();

export { ContextScript };