perfViz/types/trace.ts

/**
 * Chrome DevTools Performance Trace Format
 * Based on the Trace Event Format specification
 */

// Main trace file structure
export interface TraceFile {
  metadata: TraceMetadata
  traceEvents: TraceEvent[]
}

// Metadata section
export interface TraceMetadata {
  source: string
  startTime: string
  hardwareConcurrency: number
  dataOrigin: string
  modifications: TraceModifications
}

export interface TraceModifications {
  entriesModifications: {
    hiddenEntries: unknown[]
    expandableEntries: unknown[]
  }
  initialBreadcrumb: {
    window: {
      min: number
      max: number
      range: number
    }
    child: null | unknown
  }
  annotations: {
    entryLabels: unknown[]
    labelledTimeRanges: unknown[]
    linksBetweenEntries: unknown[]
  }
}

// Base trace event structure
export interface BaseTraceEvent {
  /** Event arguments - varies by event type */
  args: Record<string, unknown>
  /** Category */
  cat: string
  /** Event name */
  name: string
  /** Phase type */
  ph: TraceEventPhase
  /** Process ID */
  pid: number
  /** Thread ID */
  tid: number
  /** Timestamp in microseconds */
  ts: number
  /** Thread timestamp in microseconds (optional) */
  tts?: number
}

// Specific event types
export interface MetadataEvent extends BaseTraceEvent {
  ph: 'M'
  args: {
    name?: string
    uptime?: string
    [key: string]: unknown
  }
}

export interface DurationEvent extends BaseTraceEvent {
  ph: 'X'
  /** Duration in microseconds */
  dur: number
  /** Thread duration in microseconds (optional) */
  tdur?: number
}

export interface InstantEvent extends BaseTraceEvent {
  ph: 'I'
  /** Scope (optional) */
  s?: 't' | 'p' | 'g'
  /** Layer tree ID (optional) */
  layerTreeId?: number
  /** Layer ID (optional) */
  layerId?: number
}

export interface BeginEvent extends BaseTraceEvent {
  ph: 'B'
}

export interface EndEvent extends BaseTraceEvent {
  ph: 'E'
}

// Union type for all trace events
export type TraceEvent = MetadataEvent | DurationEvent | InstantEvent | BeginEvent | EndEvent

// Phase type enumeration
export type TraceEventPhase = 
  | 'M'  // Metadata
  | 'X'  // Complete (duration)
  | 'I'  // Instant
  | 'B'  // Begin
  | 'E'  // End
  | 'D'  // Deprecated
  | 'b'  // Nestable start
  | 'e'  // Nestable end
  | 'n'  // Nestable instant
  | 'S'  // Async start
  | 'T'  // Async instant
  | 'F'  // Async end
  | 'P'  // Sample
  | 'C'  // Counter
  | 'R'  // Mark

// Common argument types found in trace events
export interface TracingStartedArgs {
  data: {
    frameTreeNodeId: number
    frames: Array<{
      frame: string
      isInPrimaryMainFrame: boolean
      isOutermostMainFrame: boolean
      name: string
      processId: number
      url: string
    }>
    persistentIds: boolean
  }
}

export interface UpdateLayerArgs {
  layerId: number
  layerTreeId: number
}

export interface NeedsBeginFrameChangedArgs {
  data: {
    needsBeginFrame: number
  }
  layerTreeId: number
}

export interface RunTaskArgs {
  [key: string]: unknown
}

// Thread and process name arguments
export interface ThreadNameArgs {
  name: string
}

export interface ProcessNameArgs {
  name: string
}

export interface ProcessUptimeArgs {
  uptime: string
}