# DAP Browser Extension UI Improvements

**Status:** Implemented  
**Date:** January 2026  
**Related:** [dap-browser-extension.md](./dap-browser-extension.md), [dap-debugging.md](./dap-debugging.md)

## Overview

This document describes UI improvements made to the DAP browser extension debugger based on designer feedback. The original implementation inserted the debugger pane inline between workflow steps, causing it to "bounce around" as the user stepped through the job. The new implementation uses fixed positioning with two layout options.

## Problem Statement

The original debugger UI had these issues:
1. **Bouncing pane**: The debugger pane was inserted between steps in the DOM, so it moved position each time the user stepped to a new step
2. **No layout flexibility**: Users couldn't choose where they wanted the debugger positioned
3. **No breakpoint indicator**: There was no visual indication of which step the debugger was currently paused at

## Solution

Implemented two fixed-position layout options inspired by browser DevTools:

### 1. Bottom Panel Layout (Default)
- Fixed at the bottom of the viewport
- Height: 280px
- Variables panel on left (33%), Console on right (67%)
- Control buttons in the header row (right side)
- Similar to Chrome/Firefox DevTools

```
+------------------------------------------------------------------+
| Debugger   [step info]              [controls] [layout] [X]      |
+------------------------------------------------------------------+
|  Variables (1/3)      |  Console (2/3)                           |
|  > github             |  Welcome message...                      |
|  > env                |  > command output                        |
|  > runner             |                                          |
|                       |  [input field                         ]  |
+------------------------------------------------------------------+
```

### 2. Sidebar Layout
- Fixed on the right side of the viewport
- Width: 350px
- Full height of viewport
- Variables on top, Console in middle, Controls at bottom

```
+------------------+
| Debugger     [X] |
| [layout btns]    |
+------------------+
| Variables        |
| > github         |
| > env            |
+------------------+
| Console          |
| output...        |
|                  |
| [input        ]  |
+------------------+
| [  controls   ]  |
+------------------+
```

### 3. Breakpoint Indicator
Visual marker showing the current step where the debugger is paused:
- Red accent bar on the right edge of the step row
- Red bottom border on the step header
- Triangle pointer pointing toward the debugger panel
- Subtle gradient background highlight

## Implementation Details

### Files Modified

| File | Changes |
|------|---------|
| `browser-ext/content/content.js` | Complete refactor: new layout system, breakpoint indicator, layout toggle |
| `browser-ext/content/content.css` | New styles for layouts, breakpoint indicator, toggle buttons |

### Key Functions Added (`content.js`)

#### Layout Management
```javascript
// Load layout preference from chrome.storage.local
async function loadLayoutPreference()

// Save layout preference to chrome.storage.local  
function saveLayoutPreference(layout)

// Switch between 'bottom' and 'sidebar' layouts
// Preserves console output and variable tree state during switch
function switchLayout(newLayout)

// Create the bottom panel HTML structure
function createBottomPaneHTML()

// Create the sidebar panel HTML structure
function createSidebarPaneHTML()
```

#### Breakpoint Indicator
```javascript
// Highlights the current step with CSS class 'dap-current-step'
function updateBreakpointIndicator(stepElement)

// Clears the indicator from all steps
function clearBreakpointIndicator()
```

#### Panel Controls
```javascript
// Close the debugger panel and clear indicators
function closeDebuggerPane()

// Update layout toggle button active states
function updateLayoutToggleButtons()
```

### CSS Classes Added (`content.css`)

| Class | Purpose |
|-------|---------|
| `.dap-debugger-bottom` | Bottom panel layout (fixed position) |
| `.dap-debugger-sidebar` | Sidebar layout (fixed position) |
| `.dap-layout-toggles` | Container for layout toggle buttons |
| `.dap-layout-btn` | Individual layout toggle button |
| `.dap-layout-btn.active` | Active state for selected layout |
| `.dap-close-btn` | Close button styling |
| `check-step.dap-current-step` | Breakpoint indicator on step element |

### State Variables

```javascript
let currentLayout = 'bottom';      // 'bottom' | 'sidebar'
let currentStepElement = null;     // Track current step for breakpoint indicator
```

### Storage

Layout preference is persisted to `chrome.storage.local` under the key `debuggerLayout`.

## Removed Functionality

- `moveDebuggerPane()` - No longer needed since debugger uses fixed positioning
- Inline pane injection between steps - Replaced with fixed position panels

## Design Mockups Reference

The implementation was based on these mockup frames:
- **Frame 4/5/6**: Sidebar layout on right side
- **Frame 7**: Bottom panel layout with controls in header
- All frames showed the breakpoint indicator as a red/orange accent on the current step

## Future Improvements

Potential enhancements for future iterations:

1. **Resizable panels**: Allow users to drag to resize the panel width/height
2. **Minimize/maximize**: Add ability to minimize the panel to just a header bar
3. **Detached window**: Option to pop out debugger into separate browser window
4. **Keyboard shortcuts**: Add shortcuts for layout switching and panel toggle
5. **Remember panel size**: Persist user's preferred panel dimensions
6. **Breakpoint list**: Show list of all breakpoints with ability to navigate
7. **Step indicator in panel**: Show step name/number in the panel header with prev/next navigation

## Testing Checklist

- [ ] Bottom panel displays correctly at viewport bottom
- [ ] Sidebar panel displays correctly on right side
- [ ] Layout toggle buttons switch between layouts
- [ ] Layout preference persists across page reloads
- [ ] Close button removes panel and updates Debug button state
- [ ] Breakpoint indicator appears on current step when paused
- [ ] Breakpoint indicator moves when stepping to next step
- [ ] Breakpoint indicator clears when disconnected/terminated
- [ ] Console output preserves when switching layouts
- [ ] Variables tree preserves when switching layouts
- [ ] Works correctly in both light and dark mode
- [ ] Panel doesn't interfere with page scrolling
- [ ] Step scrolls into view when breakpoint changes

## Architecture Notes

### Why Fixed Positioning?

The original inline injection approach had issues:
1. Required complex DOM manipulation to move the pane between steps
2. Caused layout shifts in the GitHub page
3. Made it difficult to maintain console scroll position
4. Required finding the correct insertion point for each step

Fixed positioning solves these:
1. Panel stays in place - no DOM movement needed
2. No layout shifts in the main page content
3. Panel state (console, variables) naturally preserved
4. Simpler CSS and JavaScript

### Layout Toggle UX

The toggle is a button group in the panel header showing both layout options:
- Sidebar icon (vertical split)
- Bottom icon (horizontal split)

The active layout is highlighted. Clicking the other option triggers `switchLayout()`.

### Breakpoint Indicator Implementation

Uses CSS class `.dap-current-step` added to the `<check-step>` element:
- `::after` pseudo-element creates the red accent bar
- `::before` pseudo-element creates the triangle pointer
- Direct child selectors style the step header background and border

The indicator is updated in `handleStoppedEvent()` when the debugger pauses at a new step.