FABRIC/docs/FileHeatmap-Integration.md

FileHeatmap Integration Summary

Overview

The FileHeatmap component is fully integrated into the FABRIC TUI application, providing real-time visualization of file modification patterns and collision detection.

Integration Points

1. Component Instantiation

Location: src/tui/app.ts:136-143

this.fileHeatmap = new FileHeatmap({
  parent: this.screen,
  top: 1,
  left: 0,
  width: '100%',
  bottom: 1,
});
this.fileHeatmap.getElement().hide();

2. Keyboard Shortcut

Key: H (uppercase) Location: src/tui/app.ts:270-272

• Toggles between default view and heatmap view
• Pressing H again or Escape returns to default view

3. Data Aggregation

Location: src/tui/app.ts:401-404, 673-679

The heatmap aggregates file access counts from the event store:

this.fileHeatmap.updateData(
  (opts) => this.store.getFileHeatmap(opts),
  () => this.store.getFileHeatmapStats()
);

Store Methods:

• getFileHeatmap(options) - Returns sorted file entries (src/store.ts:501-585)
• getFileHeatmapStats() - Returns aggregate statistics (src/store.ts:590-637)

4. Features

• Real-time updates: Heatmap updates automatically when new events are added
• Multiple sort modes:
  • Modifications (default)
  • Recent activity
  • Worker count
  • Collision priority
• Filtering:
  • Collisions only mode (c key)
  • Directory filtering
• Heat levels:
  • Cold (1-2 modifications)
  • Warm (3-5 modifications)
  • Hot (6-10 modifications)
  • Critical (11+ modifications)
• Worker tracking: Shows which workers are modifying each file
• Collision detection: Highlights files with concurrent modifications

5. View Management

Location: src/tui/app.ts:388-409

View mode state machine:

• default - Worker grid + Activity stream
• heatmap - Full-screen file heatmap
• dag - Dependency DAG view
• replay - Session replay
• errors - Error groups

6. Help Text

Location: src/tui/app.ts:601-614

Heatmap View:
  s       - Cycle sort mode
  c       - Toggle collisions only
  Esc     - Return to default view

Test Coverage

Component Tests

• FileHeatmap.test.ts: 51 tests covering UI component behavior
• fileHeatmap.test.ts: 20 tests covering heatmap logic
• FileHeatmap.test.tsx: 15 tests covering web frontend
• app.test.ts: 44 tests including heatmap integration

Total: 130 tests covering FileHeatmap functionality Status: ✅ All tests passing

Usage

1. Start FABRIC TUI: npm start or npm run tui
2. Press H to open the file heatmap view
3. Use s to cycle through sort modes:
   • Modifications (default)
   • Recent activity
   • Worker count
   • Collision priority
4. Press c to filter for files with collisions only
5. Use j/k or arrow keys to navigate files
6. Press Esc to return to the default view

Technical Details

Data Flow

LogEvents → Store.add() → FileModificationTracker
                              ↓
                    Store.getFileHeatmap()
                              ↓
                    FileHeatmap.updateData()
                              ↓
                      FileHeatmap.render()

Performance

• File modifications tracked in-memory with Map<string, FileModificationTracker>
• Efficient O(1) lookups for file access patterns
• Configurable max entries limit (default: 50)
• Timestamps stored for interval calculations

Collision Detection

The heatmap integrates with the collision detection system to highlight:

• Active collisions (⚠ red): Multiple workers modifying same file within 5s window
• Potential collisions (⚡ yellow): Multiple workers actively working on same file
• Safe files (no indicator): Single worker or no recent conflicts

Related Files

• Component: src/tui/components/FileHeatmap.ts
• Integration: src/tui/app.ts
• Store logic: src/store.ts
• Tests: src/tui/components/FileHeatmap.test.ts, src/tui/app.test.ts
• Types: src/types.ts (FileHeatmapEntry, FileHeatmapStats, HeatmapOptions)

Completion Status

✅ COMPLETE - FileHeatmap is fully integrated and functional

• Keyboard shortcut 'H' working
• Data aggregation from store working
• Real-time updates working
• All tests passing (943 total)
• Help documentation included