Merge pull request certinia#712 from lukecotter/feat-timeline-minimap

feat: timeline minimap

Author: lcottercertinia

CHANGELOG.md

@@ -9,27 +9,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- **⚡ Performance**: Improved performance to handle huge Apex debug logs; Zoom + pan are **7X faster** with smoother motion; Adaptive level-of-detail bucketing reveals richer timeline detail as you zoom while keeping the view clean and fast.
-  - **Visual Display**: Dynamic labels on Timeline events for faster log scanning; Time axis auto-spaces markers intelligently and more naturally as you zoom; Search + highlight dims non-matches for fast scanning.
-
 - ⚡ **Timeline**: A brand new **experimental** timeline Flame Chart built for massive logs and up to **7X faster**. ([#446] [#251] [#92] [#564])
-  - Full feature parity with the original Timeline including:
-    - Zoom and pan navigation (mouse + keyboard)
-    - Search with result highlighting
-    - Frame tooltips on hover
-    - Markers for errors, skipped lines, and truncation
-    - Click to navigate to Call Tree (now on key press of `J` or `Cmd/Ctrl+Click`)
   - **⚡ Performance**: Improved performance to handle huge Apex debug logs.
     - Zoom + pan are **7X faster** with smoother motion.
-  - **Visual Display**:
-    - Adaptive level-of-detail bucketing reveals richer timeline detail as you zoom while keeping the view clean and fast.
-    - Dynamic labels on Timeline events for faster log scanning. ([#92])
-    - Time axis auto-spaces markers intelligently and more naturally as you zoom.
-    - Search + highlight dims non-matches for fast scanning.
-  - **🎨 Themes**:
-    - 18 curated timeline themes plus the default theme has been improved for better contrast and readability.
-    - Add your own multiple custom themes via **Settings -> Apex Log Analyzer -> Timeline -> Custom Themes**.
-    - Fast theme switching via **Command Palette**: **Log: Timeline Theme** or **Settings -> Apex Log Analyzer -> Timeline -> Active Theme**.
+  - **Minimap**: Navigate massive logs at a glance with the new minimap overview. ([#245] [#446])
+    - **Skyline Overview**: Density-based visualization shows stack depth and event distribution across the entire timeline. Color-coded categories and logarithmic opacity reveal hotspots instantly.
+    - **Viewport Lens**: A window highlights exactly what's visible in the main timeline — both time range and depth. Drag to create zoom selections, resize edges to adjust, or teleport with `Cmd/Ctrl+Click`.
+    - **Cursor Mirroring**: Hover on the minimap to see a guide line on the main timeline.
+    - **Rich Interactions**:
+      - **Drag anywhere** → draw a new zoom selection
+      - **Drag lens edges** → resize the viewport
+      - **Shift+Drag inside lens** → pan the viewport
+      - **Cmd/Ctrl+Click** → instantly teleport the lens
+      - **Scroll** → zoom (vertical) or pan (horizontal)
+      - **Double-click** → reset to full timeline view
+    - **Keyboard shortcuts** (when hovering minimap): Arrow keys pan, `W`/`S` zoom, `Home`/`End` jump, `0` resets.
+  - **Adaptive Frame Bucketing**: Reveals nested frame detail and stack structure as you zoom, automatically adjusting frame granularity to understand complex call hierarchies.
+  - **Dynamic Frame Labels**: Labels automatically appear on timeline frames as you zoom and pan, making log scanning and navigation effortless without manually hovering to see event details. ([#92])
   - **Keyboard and Mouse Navigation**: Comprehensive interaction controls for the timeline. ([#573] [#366] [#296] [#295] [#535])
     - **Selection & Focus**:
       - **Frame Selection**: Click to select and highlight a frame without navigating away.
@@ -49,6 +45,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
       - **Copy**: `Cmd/Ctrl+C` copies the selected frame name.
       - **Marker Navigation**: Click markers to select; arrow Left/Right to navigate between markers.
       - **Clear Selection**: Press `Escape` to deselect the current frame or marker.
+  - **Visual Display**:
+    - Time axis auto-spaces markers intelligently and more naturally as you zoom.
+    - Search + highlight dims non-matches for fast scanning.
+  - **🎨 Themes**:
+    - 18 curated timeline themes plus the default theme has been improved for better contrast and readability.
+    - Add your own multiple custom themes via **Settings -> Apex Log Analyzer -> Timeline -> Custom Themes**.
+    - Fast theme switching via **Command Palette**: **Log: Timeline Theme** or **Settings -> Apex Log Analyzer -> Timeline -> Active Theme**.
+  - **Full support for all original Timeline features** including:
+    - Zoom and pan navigation (mouse + keyboard)
+    - Search with result highlighting
+    - Frame tooltips on hover
+    - Markers for errors, skipped lines, and truncation
+    - Click to navigate to Call Tree (now on key press of `J` or `Cmd/Ctrl+Click`)
   - **Legacy Support**: Toggle the legacy timeline anytime via **Settings -> Apex Log Analyzer -> Timeline -> Legacy**.
 
 ### Changed
@@ -450,6 +459,7 @@ Skipped due to adopting odd numbering for pre releases and even number for relea
 
 <!-- Unreleased -->
 
+[#245]: https://github.com/certinia/debug-log-analyzer/issues/245
 [#164]: https://github.com/certinia/debug-log-analyzer/issues/164
 [#535]: https://github.com/certinia/debug-log-analyzer/issues/535
 [#295]: https://github.com/certinia/debug-log-analyzer/issues/295

README.md

@@ -12,15 +12,15 @@ Apex Log Analyzer is a blazing-fast VS Code extension for Salesforce developers.
 
 [Installation](#%EF%B8%8F-installation 'Install Apex Log Analyzer in VS Code') |
 [Debug Log Levels](#%EF%B8%8F-recommended-debug-log-levels 'Go to Recommended Debug Log Levels') |
-[Features](#-flame-chart-timeline 'Go to Features') |
+[Features](#-timeline 'Go to Features') |
 [Customization](#-customization 'Go to Customization') |
 [Documentation](#-documentation 'Go to Documentation') |
 [Contributors](#%EF%B8%8F-contributors 'Go to Contributors') |
 [License](#-license 'Go to License')
 
 ## 🚀 Key Features
 
-- **🔥 [Flame Chart Timeline](#-flame-chart-timeline)** – Visualize every method, SOQL query, and DML operation in your Apex logs.
+- **🔥 [Timeline](#-timeline)** – Visualize every method, SOQL query, and DML operation in your Apex logs with an interactive flame chart and minimap navigation.
 - **🌲 [Interactive Call Tree](#-call-tree)** – Dive into execution stacks with timing, row counts, and DML/ SOQL metrics.
 - **📊 [Apex](#-apex-analysis) + [Database](#%EF%B8%8F-database-analysis) Analysis** – Identify slow-performing SOQL, high-impact DML, and time-heavy Apex methods.
 - **🧠 Smart Filtering + Sorting** – Focus on what matters: filter by namespace, event type, or duration.
@@ -81,20 +81,21 @@ Use `Log: Retrieve Apex Log And Show Analysis` from the Command Palette.
 - Avoid truncated logs — they can result in incomplete or misleading analysis.
 - Recommended settings for a good balance of detail and performance: `APEX_CODE,FINE; APEX_PROFILING,FINE; CALLOUT,INFO; DB,FINEST; NBA,INFO; SYSTEM,DEBUG; VALIDATION,INFO; VISUALFORCE,FINE; WAVE,INFO; WORKFLOW,FINE`
 
-## 🔥 Flame Chart Timeline
+## 🔥 Timeline
 
-The Flame Chart view shows a timeline of the Salesforce Apex log execution — including methods, SOQL queries, DML operations, workflows, flows, and more.
+The Timeline view shows a live visualization of your Salesforce Apex log execution — including methods, SOQL queries, DML operations, workflows, flows, and more.
 
 - **⚡ Fast** – Blazing-fast zoom, pan, and rendering even on massive logs (500k+ lines).
 - **🎯 Frame Selection & Navigation** – Click to select frames, use arrow keys to navigate the call stack, double-click or press `Enter` to zoom and focus.
 - **Zoom & Pan** – Navigate your logs down to 0.001 ms with precision zoom. `W`/`S` keys or scroll wheel for zoom; `A`/`D` keys or drag for pan.
+- **Dynamic Frame Labels** – Instantly see method names on timeline frames for faster scanning.
+- **🗺️ Minimap** – Bird's-eye view with skyline overview showing call stack depth, viewport lens for navigation, and instant teleport to any position.
 - **📏 Measure Range** – `Shift+Drag` to measure the duration between any two points. Resize edges, double-click to zoom.
 - **🔍 Area Zoom** – `Alt/Option+Drag` to select a region and instantly zoom to fit.
-- **Dynamic Labels** – Instantly see method names on timeline events for faster scanning.
-- **19 Curated Themes** – Choose from beautiful, optimized color themes or create your own via Settings.
-- **Smart Interaction** – Right-click for context actions; `Cmd/Ctrl+Click` to jump directly to the Call Tree; `Cmd/Ctrl+C` to copy frame names.
 - **Tooltips** – Hover for duration, event name, SOQL/DML/Exception counts, SOQL/DML rows, and more.
-- **Adaptive Detail** – Level-of-detail bucketing reveals richer detail as you zoom while keeping performance snappy.
+- **Cotext Menu Actions** – Right-click for context actions; `Cmd/Ctrl+Click` to jump directly to the Call Tree; `Cmd/Ctrl+C` to copy frame names.
+- **19 Curated Themes** – Choose from beautiful, optimized color themes or create your own via Settings.
+- **Adaptive Frame Detail** – Level-of-detail bucketing reveals richer detail as you zoom while keeping performance snappy.
 - **Stacked by Time** – See how execution time is distributed across nested method calls and system events.
 
 ![Flame Chart](https://raw.githubusercontent.com/certinia/debug-log-analyzer/main/lana/assets/v1.18/lana-timeline.png)

lana-docs-site/docs/docs/features/timeline.md

@@ -1,7 +1,7 @@
 ---
 id: timeline
 title: Timeline
-description: Use the Timeline to visualize code execution, event durations, and performance bottlenecks. Zoom, pan, measure time ranges, and interact with detailed tooltips for efficient Salesforce Apex log analysis and debugging.
+description: Use the Timeline to visualize code execution, event durations, and performance bottlenecks. Zoom, pan, measure time ranges, and navigate massive logs with the minimap overview for efficient Salesforce Apex log analysis and debugging.
 keywords:
   [
     salesforce apex log analysis,
@@ -12,23 +12,80 @@ keywords:
     apex performance analysis,
     measure time range,
     area zoom selection,
+    timeline minimap,
+    log navigation,
   ]
 image: https://raw.githubusercontent.com/certinia/debug-log-analyzer/main/lana/assets/v1.18/lana-timeline.png
 hide_title: true
 ---
 
 ## 🔥 Timeline / Flame Chart
 
-Use the Timeline to visualize code execution, event durations, and performance bottlenecks. Zoom, pan, and interact with detailed tooltips for efficient Salesforce apex log analysis and debugging.
+Use the Timeline to visualize code execution, event durations, and performance bottlenecks. Zoom, pan, navigate with the minimap overview, and interact with detailed tooltips for efficient Salesforce apex log analysis and debugging.
 
 ![Timeline view screenshot showing a color-coded flame chart of Salesforce event types such as DB, Method, and SOQL, visualizing code execution duration and performance](https://raw.githubusercontent.com/certinia/debug-log-analyzer/main/lana/assets/v1.18/lana-timeline.png)
 
-The new experimental timeline is up to **7X faster** than the legacy timeline, with improved performance especially for large logs. It includes text labels on events, faster zoom/pan operations, and a more natural time axis scaling.
+The new experimental timeline is up to **7X faster** than the legacy timeline, with improved performance especially for large logs. It includes text labels on frames, faster zoom/pan operations, and a more natural time axis scaling.
 
 :::tip Legacy Timeline
 To revert to the legacy timeline, navigate to **Settings → Apex Log Analyzer → Timeline → Legacy** and enable it.
 :::
 
+## Minimap
+
+The minimap gives you instant context of your entire log. Spot hotspots at a glance, jump anywhere with a click, and always know exactly where you are—all without scrolling.
+
+### What the Minimap Shows
+
+- **Skyline Chart**: A density-based visualization:
+  - **Height** = maximum call stack depth at that point
+  - **Color** = dominant event category (method, SOQL, DML, etc.)
+  - **Opacity** = event density (brighter = more events)
+- **Viewport Lens**: A window showing exactly what's visible in the main timeline (time range horizontal, depth range vertical)
+- **Time Axis**: Time reference markers at the top
+- **Markers**: Error, skip, and truncation markers from the main timeline
+- **Cursor Mirroring**: Hover to see a guide line on the main timeline
+
+### Mouse Interactions
+
+| Action           | Mouse                 | Result                              |
+| ---------------- | --------------------- | ----------------------------------- |
+| Create Zoom      | Drag anywhere         | Draw a viewport area and zoom to it |
+| Resize Viewport  | Drag lens edge        | Adjust zoom range                   |
+| Move Viewport    | Drag top/`Shift+Drag` | Pan the viewport                    |
+| Teleport Lens    | `Cmd/Ctrl+Click`      | Center the lens on click position   |
+| Zoom In/Out      | Scroll (vertical)     | Zoom at cursor position             |
+| Pan Horizontally | Scroll (horizontal)   | Move viewport left/right            |
+| Pan Depth        | Drag (vertical)       | Scroll the main timeline up/down    |
+| Reset            | Double-click          | Zoom out to fit entire timeline     |
+
+:::tip Teleport Navigation
+`Cmd/Ctrl+Click` is the fastest way to jump to any point in a massive log. The lens teleports to center on your click while preserving the current zoom level.
+:::
+
+### Keyboard Shortcuts
+
+When your mouse is hovering over the minimap, these keyboard shortcuts are available:
+
+| Key             | Action                                      |
+| --------------- | ------------------------------------------- |
+| `Arrow Left`    | Pan viewport left (10% of selection width)  |
+| `Arrow Right`   | Pan viewport right (10% of selection width) |
+| `Arrow Up`      | Pan depth up (show deeper frames)           |
+| `Arrow Down`    | Pan depth down (show shallower frames)      |
+| `W` / `+` / `=` | Zoom in (narrow the lens)                   |
+| `S` / `-`       | Zoom out (widen the lens)                   |
+| `Home`          | Jump to timeline start                      |
+| `End`           | Jump to timeline end                        |
+| `0` / `Escape`  | Reset zoom (fit entire timeline)            |
+
+### Lens Label
+
+When hovering over the viewport lens or dragging, a label appears showing:
+
+- The **duration** of the selected time range (e.g., "1.23s")
+- The **time range** start and end (e.g., "0.5s - 1.73s")
+
 ## Navigation
 
 ### Zoom + Pan

lana/src/commands/LogView.ts

@@ -64,15 +64,15 @@ export class LogView {
           }
 
           case 'openPath': {
-            const filePath = <string>payload;
+            const filePath = payload as string;
             if (filePath) {
               context.display.showFile(filePath);
             }
             break;
           }
 
           case 'openType': {
-            const symbol = <string>payload;
+            const symbol = payload as string;
             if (symbol) {
               OpenFileInPackage.openFileForSymbol(context, symbol);
             }
@@ -94,9 +94,10 @@ export class LogView {
           }
 
           case 'saveFile': {
-            const { fileContent, options } = <
-              { fileContent: string; options: { defaultFileName?: string } }
-            >payload;
+            const { fileContent, options } = payload as {
+              fileContent: string;
+              options: { defaultFileName?: string };
+            };
 
             if (fileContent && options?.defaultFileName) {
               const defaultWorkspace = (workspace.workspaceFolders || [])[0];
@@ -116,7 +117,7 @@ export class LogView {
           }
 
           case 'showError': {
-            const { text } = <{ text: string }>payload;
+            const { text } = payload as { text: string };
             if (text) {
               vscWindow.showErrorMessage(text);
             }

lana/tsconfig.json

@@ -13,6 +13,7 @@
 
     "strict": true,
     "noUncheckedIndexedAccess": true,
+    "erasableSyntaxOnly": true,
 
     "moduleResolution": "Bundler",
     "module": "ESNext",

log-viewer/src/__tests__/ApexLogParser.test.ts

@@ -424,7 +424,7 @@ describe('parseLog tests', () => {
       '09:19:13.82 (51595120059)|EXECUTION_FINISHED\n';
 
     const apexLog = parse(log);
-    const execEvent = <MethodEntryLine>apexLog.children[0];
+    const execEvent = apexLog.children[0] as MethodEntryLine;
     expect(execEvent).toBeInstanceOf(ExecutionStartedLine);
 
     expect(execEvent.children.length).toEqual(1);

log-viewer/src/core/utility/Util.ts

@@ -63,6 +63,25 @@ function round(value: number, precision: number): number {
   return Math.round(value * precision) / precision;
 }
 
+/**
+ * Formats a time range showing start and end times with an arrow separator.
+ *
+ * Used by measurement overlay and minimap lens labels for consistent formatting.
+ *
+ * @param startTimeNs - Start time in nanoseconds
+ * @param endTimeNs - End time in nanoseconds
+ * @returns Formatted string like "1.2 s → 3.7 s"
+ *
+ * @example
+ * ```typescript
+ * formatTimeRange(1200000000, 3700000000);  // "1.2 s → 3.7 s"
+ * formatTimeRange(0, 150000000);            // "0 ms → 150 ms"
+ * ```
+ */
+export function formatTimeRange(startTimeNs: number, endTimeNs: number): string {
+  return `${formatDuration(startTimeNs)} → ${formatDuration(endTimeNs)}`;
+}
+
 export function debounce<T extends unknown[]>(callBack: (...args: T) => unknown) {
   let requestId: number = 0;
 

log-viewer/src/features/timeline/__tests__/keyboard-handler.test.ts

@@ -53,6 +53,14 @@ describe('KeyboardHandler', () => {
       onJumpToCallTree: jest.fn(),
       onFocus: jest.fn(),
       onCopy: jest.fn(),
+      // Minimap keyboard callbacks
+      isInMinimapArea: jest.fn().mockReturnValue(false),
+      onMinimapPanViewport: jest.fn(),
+      onMinimapPanDepth: jest.fn(),
+      onMinimapZoom: jest.fn(),
+      onMinimapJumpStart: jest.fn(),
+      onMinimapJumpEnd: jest.fn(),
+      onMinimapResetZoom: jest.fn(),
     };
 
     handler = new KeyboardHandler(container, viewport, callbacks);

log-viewer/src/features/timeline/__tests__/search-highlight.test.ts

@@ -66,6 +66,7 @@ describe('SearchHighlightRenderer', () => {
       timeEnd: timestamp + duration,
       depth,
       duration,
+      selfDuration: duration,
       category: 'Method',
     };
     return {
@@ -94,6 +95,14 @@ describe('SearchHighlightRenderer', () => {
       hasNext: jest.fn(() => currentIndex < matches.length - 1),
       hasPrev: jest.fn(() => currentIndex > 0),
       getMatchedEventIds: jest.fn(() => new Set(matches.map((m) => m.event.id))),
+      getMatchedEventsInfo: jest.fn(() =>
+        matches.map((m) => ({
+          timestamp: m.event.timestamp,
+          duration: m.event.duration,
+          depth: m.depth,
+          category: m.event.subCategory ?? '',
+        })),
+      ),
     };
   };
 

log-viewer/src/features/timeline/components/TimelineView.ts

@@ -62,7 +62,7 @@ export class TimelineView extends LitElement {
         flex: 1;
         position: relative;
         width: 100%;
-        height: 80%;
+        height: 90%;
       }
     `,
   ];