michaelschiemer/docs/claude/livecomponents-dom-badges.md

# LiveComponents DOM Badges System

**Visual component overlays for real-time monitoring and debugging.**

## Overview

The DOM Badges system provides visual overlays on LiveComponent elements, displaying component IDs, names, and activity counters directly on the page. This enables developers to quickly identify and debug components without opening the DevTools panel.

## Features

### Visual Component Identification
- **Component Name**: Shows the component's display name
- **Component ID**: Truncated ID (first 8 characters) for identification
- **Icon Indicator**: ⚡ icon for visual consistency

### Real-Time Activity Tracking
- **Action Counter**: Tracks number of actions executed on the component
- **Activity Animation**: Badge pulses with green highlight when actions are triggered
- **Live Updates**: Counter updates in real-time as actions execute

### Interactive Features
- **Click to Focus**: Click badge to open DevTools and focus on that component
- **Hover Highlight**: Hover over badge to highlight the component element with blue outline
- **DevTools Integration**: Clicking badge scrolls to component in tree and expands details

### Badge Management
- **Toggle Visibility**: Badge button in DevTools header to show/hide all badges
- **Auto-Positioning**: Badges automatically position at top-left of component elements
- **Dynamic Updates**: Badges track DOM changes and update positions accordingly

## Architecture

### Badge Data Structure
```javascript
{
    badge: HTMLElement,      // Badge DOM element
    element: HTMLElement,    // Component element
    actionCount: number      // Number of actions executed
}
```

### Badge Lifecycle
1. **Initialization**: `initializeDomBadges()` sets up MutationObserver
2. **Creation**: `createDomBadge()` creates badge for each component
3. **Positioning**: `positionBadge()` calculates fixed position
4. **Updates**: `updateBadgeActivity()` increments counter and triggers animation
5. **Cleanup**: `cleanupRemovedBadges()` removes badges for destroyed components

## Usage

### Automatic Badge Creation
Badges are automatically created when:
- DevTools is opened and components exist in DOM
- New components are added to the page (via MutationObserver)
- Badge visibility is toggled on

### Toggle Badge Visibility
```javascript
// Via DevTools UI: Click "⚡ Badges" button in header

// Programmatically
devTools.toggleBadges();
```

### Badge Interactions

**Click Badge**:
- Opens DevTools if closed
- Switches to Components tab
- Scrolls to component in tree
- Expands component details

**Hover Badge**:
- Shows blue outline around component element
- Highlights component boundaries for easy identification

## Styling

### Badge Appearance
- **Background**: Dark semi-transparent (#1e1e1e with 95% opacity)
- **Border**: Blue (#007acc) that changes to green (#4ec9b0) on hover
- **Backdrop Filter**: 4px blur for modern glass-morphism effect
- **Box Shadow**: Subtle shadow for depth

### Active Animation
```css
@keyframes badge-pulse {
    0%   { transform: scale(1);   box-shadow: default }
    50%  { transform: scale(1.1); box-shadow: green glow }
    100% { transform: scale(1);   box-shadow: default }
}
```

### Color Coding
- **Component Name**: Blue (#569cd6) - VS Code variable color
- **Component ID**: Gray (#858585) - subdued identifier
- **Action Count**: Yellow (#dcdcaa) - VS Code function color
- **Active Border**: Green (#4ec9b0) - VS Code string color

## Technical Implementation

### MutationObserver Integration
```javascript
const observer = new MutationObserver(() => {
    this.updateDomBadges();
});

observer.observe(document.body, {
    childList: true,
    subtree: true,
    attributes: true,
    attributeFilter: ['data-component-id']
});
```

### Position Calculation
Badges use `fixed` positioning with `getBoundingClientRect()`:
```javascript
const rect = element.getBoundingClientRect();
badge.style.position = 'fixed';
badge.style.top = `${rect.top + window.scrollY}px`;
badge.style.left = `${rect.left + window.scrollX}px`;
```

### Activity Tracking Integration
```javascript
// In logAction() method
logAction(componentId, ...) {
    // ... log action ...

    // Update badge
    this.updateBadgeActivity(componentId);
}
```

## Performance Considerations

### Efficient Updates
- **Deduplication**: Checks if badge already exists before creating
- **Position Updates**: Only updates position for existing badges
- **Cleanup**: Removes badges for destroyed components to prevent memory leaks

### Throttled DOM Operations
- **MutationObserver**: Batches DOM changes
- **Single Reflow**: Badge creation/positioning minimizes layout thrashing
- **Display None**: Hidden badges use `display: none` instead of removal

## Best Practices

### When to Use Badges
✅ **Good Use Cases**:
- Debugging component layout and positioning
- Identifying which components are active on a page
- Tracking component action frequency
- Visual confirmation of component presence

❌ **Avoid**:
- Production environments (only enabled in development)
- Pages with 50+ components (visual clutter)
- When precise layout debugging is needed (use browser DevTools instead)

### Badge Visibility Toggle
- Keep badges **enabled** when actively debugging components
- **Disable** badges when focusing on other DevTools tabs
- Badges automatically show when DevTools opens

## Integration with DevTools Features

### Component Tree
- Clicking badge navigates to component in tree
- Badge highlights component row with blue background
- Component details automatically expand

### Action Log
- Badge counter matches action log entries
- Activity animation syncs with action execution
- Both show real-time component behavior

### Event System
- Badges react to component lifecycle events
- Auto-created on `component:initialized`
- Auto-removed on `component:destroyed`

## Keyboard Shortcuts

No direct keyboard shortcuts for badges, but:
- **Ctrl+Shift+D**: Toggle DevTools (shows/creates badges)
- **Click Badge**: Focus component in DevTools

## Browser Compatibility

- **Modern Browsers**: Full support (Chrome, Firefox, Safari, Edge)
- **MutationObserver**: Required (IE11+ supported)
- **CSS Animations**: Fallback to no animation on older browsers
- **Backdrop Filter**: Graceful degradation without blur effect

## Troubleshooting

### Badges Not Appearing
1. Check if DevTools is enabled (`data-env="development"`)
2. Verify components have `data-component-id` attribute
3. Ensure badges are enabled (check button opacity in header)
4. Look for JavaScript errors in console

### Badges in Wrong Position
1. Check if component element has proper layout (not `display: none`)
2. Verify parent containers don't have `transform` CSS
3. Badge position updates on DOM mutations
4. Manually refresh badges with toggle button

### Performance Issues
1. Reduce number of active components
2. Disable badges when not actively debugging
3. Check MutationObserver frequency in console
4. Consider using Components tab instead for many components

## Future Enhancements

Potential improvements for DOM badges:
- **State Preview**: Show current component state in badge tooltip
- **Network Indicator**: Visual indicator when component is loading
- **Error State**: Red badge when component has errors
- **Badge Groups**: Collapsible badges for nested components
- **Custom Badge Colors**: User-configurable color schemes
- **Badge Size Options**: Small/Medium/Large badge sizes
- **Filter by Type**: Show only specific component types

## Summary

DOM badges provide a powerful visual debugging tool that complements the DevTools overlay. They enable:
- **Instant Component Identification**: See what's on the page without opening DevTools
- **Real-Time Activity Monitoring**: Track action execution as it happens
- **Quick Navigation**: Click to jump to component in DevTools
- **Visual Feedback**: Animations and highlights for enhanced UX

The badge system is designed to be non-intrusive, performant, and seamlessly integrated with the LiveComponent lifecycle and DevTools features.