ui-operations

name: ui-operations description: UI Core and Web Components operations for building 3Lens UI panels and components. Use when creating UI panels, integrating UI Core components, or debugging UI issues.

UI Operations

UI operations cover building UI components, panels, and integrating with UI Core for framework-agnostic UI development.

When to Use

• Creating new UI panels
• Building UI Core components
• Integrating Web Components
• Debugging UI issues
• Understanding UI architecture

UI Architecture

UI Core (Framework-Agnostic)

packages/ui/core/
├── dock.ts          # Dock interface
├── overlay.ts       # Overlay interface
├── panel.ts         # Panel interface
└── types.ts         # Type definitions

UI Web (Web Components)

packages/ui/web/
├── elements/
�?  ├── ThreeLensDock.ts      # Dock Web Component
�?  ├── ThreeLensOverlay.ts   # Overlay Web Component
�?  └── ThreeLensPanel.ts     # Panel Web Component
└── styles.ts                 # Shared styles

Commands

Scaffold a Panel

# Create a new UI panel
3lens scaffold panel my-panel

# Create panel in specific addon
3lens scaffold panel my-panel --addon my-addon

Generates:

• Panel source file
• Query hooks
• Contract compliance checklist
• Test file template

Panel Development

Panel Structure

// packages/ui-core/src/panels/my-panel.ts
import { Panel, PanelConfig } from '../types';
import { LensClient } from '@3lens/runtime';

export interface MyPanelConfig extends PanelConfig {
  // Panel-specific config
}

export function createMyPanel(client: LensClient, config: MyPanelConfig): Panel {
  return {
    id: 'my-panel',
    name: 'My Panel',
    
    render(container: HTMLElement) {
      // Render panel UI
    },
    
    onSelectionChange(selection: Selection) {
      // React to selection changes
    },
    
    dispose() {
      // Cleanup
    }
  };
}

Panel Requirements

Every panel MUST:

1. Answer a Clear Question

   • What question does this panel answer?
   • What entities does it display?

2. Show Fidelity Badges

   function renderMetric(value: number, fidelity: Fidelity) {
     return `
       <span class="metric">
         ${value}
         <span class="fidelity-badge fidelity-${fidelity}">
           ${fidelity}
         </span>
       </span>
     `;
   }
   

3. Route Through Inspector

   // When user clicks something
   client.select(entityId, { source: 'my-panel' });
   
   // When selection changes
   onSelectionChange(selection) {
     this.highlightEntities(selection.entity_ids);
   }
   

4. Support Offline Traces

   const data = client.isLive 
     ? await client.queryLive(query, params)
     : await client.queryTrace(query, params);
   

5. Include Attribution Paths

   function renderHotspot(hotspot) {
     return `
       <div onclick="selectEntity('${hotspot.entityId}')">
         ${hotspot.gpuTime}ms
         <span class="attribution">
           ${hotspot.attribution.map(a => a.entityId).join(', ')}
         </span>
       </div>
     `;
   }
   

Web Components

Using UI Web Components

<!-- Dock mode -->
<three-lens-dock>
  <three-lens-panel id="inspector"></three-lens-panel>
  <three-lens-panel id="perf"></three-lens-panel>
</three-lens-dock>

<!-- Overlay mode -->
<three-lens-overlay>
  <three-lens-panel id="inspector"></three-lens-panel>
</three-lens-overlay>

Custom Panel Component

// Custom panel Web Component
import { ThreeLensPanel } from '@3lens/ui-web';

class MyCustomPanel extends ThreeLensPanel {
  connectedCallback() {
    super.connectedCallback();
    // Custom initialization
  }
  
  render(client: LensClient) {
    // Custom rendering
  }
}

customElements.define('my-custom-panel', MyCustomPanel);

UI Modes

Dock Mode

// Dock interface
interface Dock {
  addPanel(panel: Panel): void;
  removePanel(panelId: string): void;
  show(): void;
  hide(): void;
}

Overlay Mode

// Overlay interface
interface Overlay {
  showPanel(panelId: string): void;
  hidePanel(panelId: string): void;
  toggle(): void;
}

Agent Use Cases

1. New panel: "Create a performance timeline panel"
2. UI integration: "How do I integrate 3Lens UI into my app?"
3. Custom component: "Create a custom panel component"
4. Debugging: "My panel isn't rendering, help debug"

Post-Scaffold Steps

After scaffolding, follow the playbook:

• .cursor/playbooks/add-a-panel.md

Additional Resources

• Contract: .cursor/contracts/ui-surfaces.md
• Contract: .cursor/contracts/inspector.md
• Rule: .cursor/rules/ui-standards.mdc
• Command: .cursor/commands/scaffold-panel.md
• Skill: scaffold-operations