@dynamicu/chromedebug-mcp 2.2.0

package/src/capture/types.js

@@ -0,0 +1,342 @@
+/**
+ * Unified Interaction Capture System - Core Type Definitions
+ *
+ * This module defines the unified data format for ALL interaction capture types:
+ * - Screen captures (frames/screenshots)
+ * - DOM state snapshots
+ * - Console logs and network traffic
+ * - User interactions (clicks, typing, navigation)
+ * - Function execution traces
+ * - Browser state changes
+ *
+ * DESIGN PRINCIPLES:
+ * 1. Single unified format for all capture types
+ * 2. Extensible without breaking existing code
+ * 3. Memory efficient with streaming support
+ * 4. Chrome extension compatible
+ * 5. Database optimized structure
+ *
+ * DATA FLOW ARCHITECTURE:
+ * ChromeExtension → CaptureCollector → CaptureProcessor → CaptureStorage
+ *                                   ↓
+ *                              CaptureAnalyzer → CaptureQuery
+ */
+
+/**
+ * Base timestamp interface for all capture events
+ */
+export const TimestampInfo = {
+  /** Milliseconds since capture session started */
+  relative: 0,
+  /** Absolute timestamp (Date.now()) */
+  absolute: 0,
+  /** High-resolution timestamp for precise timing */
+  performance: 0
+};
+
+/**
+ * Unified capture event - the core data structure
+ * All interaction types extend this base format
+ */
+export const CaptureEvent = {
+  /** Unique identifier for this capture event */
+  id: '',
+  /** Session ID this event belongs to */
+  sessionId: '',
+  /** Event sequence number within session */
+  sequence: 0,
+  /** Event timing information */
+  timestamp: TimestampInfo,
+  /** Event type identifier */
+  type: '', // 'screen', 'dom', 'console', 'user', 'function', 'network', 'state'
+  /** Event subtype for categorization */
+  subtype: '', // 'click', 'screenshot', 'log', 'error', 'navigation', etc.
+  /** Browser tab/page identifier */
+  pageId: '',
+  /** URL when event occurred */
+  url: '',
+  /** Event-specific data payload */
+  data: {},
+  /** Optional metadata for filtering/analysis */
+  metadata: {
+    /** Tags for categorization */
+    tags: [],
+    /** Source that generated this event */
+    source: '', // 'extension', 'puppeteer', 'devtools'
+    /** Processing priority */
+    priority: 'normal', // 'low', 'normal', 'high', 'critical'
+    /** Memory usage hint for storage optimization */
+    sizeHint: 'small' // 'small', 'medium', 'large', 'huge'
+  }
+};
+
+/**
+ * Screen capture event data
+ */
+export const ScreenCaptureData = {
+  /** Image data (base64 or binary) */
+  imageData: null,
+  /** Image format */
+  format: 'jpeg', // 'jpeg', 'png', 'webp'
+  /** Image dimensions */
+  width: 0,
+  height: 0,
+  /** Quality/compression settings */
+  quality: 80,
+  /** Viewport information */
+  viewport: {
+    x: 0,
+    y: 0,
+    width: 0,
+    height: 0,
+    scale: 1.0
+  },
+  /** Optional screenshot of specific element */
+  elementSelector: null
+};
+
+/**
+ * DOM state capture data
+ */
+export const DOMCaptureData = {
+  /** HTML content snapshot */
+  html: '',
+  /** Computed styles for key elements */
+  styles: {},
+  /** Form data values */
+  forms: {},
+  /** Scroll positions */
+  scroll: { x: 0, y: 0 },
+  /** Selected elements */
+  selection: [],
+  /** Focus information */
+  focus: { element: null, position: 0 },
+  /** Document ready state */
+  readyState: 'complete'
+};
+
+/**
+ * Console/log capture data
+ */
+export const ConsoleCaptureData = {
+  /** Log level */
+  level: 'info', // 'trace', 'debug', 'info', 'warn', 'error', 'fatal'
+  /** Log message */
+  message: '',
+  /** Structured log arguments */
+  args: [],
+  /** Stack trace if available */
+  stack: null,
+  /** Source location */
+  source: { file: '', line: 0, column: 0 },
+  /** Console API method used */
+  method: 'log' // 'log', 'error', 'warn', 'debug', 'trace', 'assert'
+};
+
+/**
+ * User interaction capture data
+ */
+export const UserInteractionData = {
+  /** Interaction type */
+  action: '', // 'click', 'type', 'scroll', 'hover', 'drag', 'key'
+  /** Target element information */
+  target: {
+    selector: '',
+    tagName: '',
+    text: '',
+    attributes: {},
+    bounds: { x: 0, y: 0, width: 0, height: 0 }
+  },
+  /** Input data (for typing, dragging) */
+  input: null,
+  /** Mouse/touch coordinates */
+  coordinates: { x: 0, y: 0 },
+  /** Modifier keys pressed */
+  modifiers: [],
+  /** Interaction duration */
+  duration: 0
+};
+
+/**
+ * Function execution trace data
+ */
+export const FunctionTraceData = {
+  /** Function name */
+  name: '',
+  /** Function signature */
+  signature: '',
+  /** Source location */
+  source: { file: '', line: 0, column: 0 },
+  /** Execution status */
+  status: 'completed', // 'started', 'completed', 'error', 'timeout'
+  /** Execution duration in ms */
+  duration: 0,
+  /** Arguments passed to function */
+  args: [],
+  /** Return value */
+  result: null,
+  /** Error information if failed */
+  error: null,
+  /** Call stack depth */
+  depth: 0,
+  /** Parent function call ID */
+  parentId: null
+};
+
+/**
+ * Network request capture data
+ */
+export const NetworkCaptureData = {
+  /** Request URL */
+  url: '',
+  /** HTTP method */
+  method: 'GET',
+  /** Request headers */
+  headers: {},
+  /** Request body */
+  body: null,
+  /** Response status */
+  status: 0,
+  /** Response headers */
+  responseHeaders: {},
+  /** Response body */
+  response: null,
+  /** Request timing */
+  timing: {
+    start: 0,
+    end: 0,
+    duration: 0
+  },
+  /** Request type */
+  type: 'xhr' // 'xhr', 'fetch', 'document', 'stylesheet', 'script', 'image'
+};
+
+/**
+ * Browser state change data
+ */
+export const StateChangeData = {
+  /** State type */
+  type: '', // 'navigation', 'load', 'resize', 'focus', 'storage'
+  /** Previous state */
+  from: null,
+  /** New state */
+  to: null,
+  /** Change trigger */
+  trigger: '', // 'user', 'script', 'system'
+  /** Additional context */
+  context: {}
+};
+
+/**
+ * Capture session metadata
+ */
+export const CaptureSession = {
+  /** Unique session identifier */
+  id: '',
+  /** Session name/description */
+  name: '',
+  /** Session start time */
+  startTime: 0,
+  /** Session end time (null if ongoing) */
+  endTime: null,
+  /** Session tags */
+  tags: [],
+  /** Browser information */
+  browser: {
+    name: '',
+    version: '',
+    userAgent: ''
+  },
+  /** Initial page information */
+  initialPage: {
+    url: '',
+    title: '',
+    timestamp: 0
+  },
+  /** Session configuration */
+  config: {
+    /** Capture types enabled */
+    captureTypes: [],
+    /** Screenshot settings */
+    screenshots: {
+      enabled: true,
+      quality: 80,
+      interval: 1000
+    },
+    /** Memory limits */
+    limits: {
+      maxEvents: 10000,
+      maxMemoryMB: 100
+    }
+  },
+  /** Session statistics */
+  stats: {
+    /** Total events captured */
+    totalEvents: 0,
+    /** Events by type */
+    eventsByType: {},
+    /** Memory usage */
+    memoryUsageMB: 0,
+    /** Duration in milliseconds */
+    duration: 0
+  }
+};
+
+/**
+ * Type mapping for event data validation
+ */
+export const EVENT_DATA_TYPES = {
+  'screen': ScreenCaptureData,
+  'dom': DOMCaptureData,
+  'console': ConsoleCaptureData,
+  'user': UserInteractionData,
+  'function': FunctionTraceData,
+  'network': NetworkCaptureData,
+  'state': StateChangeData
+};
+
+/**
+ * Event priority levels for processing and storage
+ */
+export const PRIORITY_LEVELS = {
+  LOW: 'low',        // Background events, low-frequency logs
+  NORMAL: 'normal',  // Standard user interactions, regular logs
+  HIGH: 'high',      // Important state changes, errors
+  CRITICAL: 'critical' // System errors, security events
+};
+
+/**
+ * Memory size hints for storage optimization
+ */
+export const SIZE_HINTS = {
+  SMALL: 'small',    // < 1KB (logs, simple interactions)
+  MEDIUM: 'medium',  // 1KB - 100KB (DOM snapshots, small images)
+  LARGE: 'large',    // 100KB - 1MB (screenshots, network responses)
+  HUGE: 'huge'       // > 1MB (video frames, large network payloads)
+};
+
+/**
+ * Supported capture event types
+ */
+export const CAPTURE_TYPES = {
+  SCREEN: 'screen',
+  DOM: 'dom',
+  CONSOLE: 'console',
+  USER: 'user',
+  FUNCTION: 'function',
+  NETWORK: 'network',
+  STATE: 'state'
+};
+
+/**
+ * Common event subtypes by category
+ */
+export const SUBTYPES = {
+  screen: ['screenshot', 'video_frame', 'element_capture'],
+  dom: ['snapshot', 'mutation', 'selection_change'],
+  console: ['log', 'error', 'warn', 'debug', 'trace'],
+  user: ['click', 'type', 'scroll', 'hover', 'drag', 'key', 'touch'],
+  function: ['start', 'end', 'error', 'async_start', 'async_end'],
+  network: ['request', 'response', 'error', 'abort'],
+  state: ['navigation', 'load', 'resize', 'focus', 'storage', 'cookie']
+};