Overlay and Picker

The @domscribe/overlay package provides the in-browser UI for Domscribe. It renders an element picker, annotation panel, and draggable tab inside your running application using Lit web components in shadow DOM.

Architecture

The overlay is implemented as a <ds-overlay> web component built with Lit. It renders inside a shadow root, which provides full CSS and JavaScript isolation:

This package is usually installed automatically by a framework adapter (@domscribe/next, @domscribe/nuxt, @domscribe/react, @domscribe/vue) rather than added directly.

Display Modes

The overlay has three display modes:

Collapsed

Only the draggable tab is visible on the right edge of the viewport. Click the tab to expand the sidebar.

Expanded

The sidebar panel is open, showing annotations and element details. From here you can view annotation history, see element context, and submit new change requests.

Capturing

The element picker is active. Clicking any element on the page selects it and captures its runtime context (props, state, DOM snapshot, source location). After selecting an element, you can type an instruction and submit it as an annotation.

Draggable Tab

The collapsed tab can be dragged vertically along the right edge of the viewport. Its position is persisted in localStorage under the key domscribe:tabOffsetY (stored as a 0-100 percentage value, defaulting to 50 which centers the tab). A 4px drag threshold distinguishes a click (which toggles the sidebar) from a drag (which repositions the tab).

Configuration

The overlay accepts the following options:

interface OverlayOptions {
  initialMode?: 'collapsed' | 'expanded' | 'capturing';
  debug?: boolean;
  sidebarWidth?: number;
}
OptionTypeDefaultDescription
initialModestring'collapsed'Initial display mode. collapsed shows just the tab, expanded shows the sidebar, capturing activates the element picker.
debugbooleanfalseEnable debug logging for overlay events and WebSocket messages.
sidebarWidthnumber360Sidebar width in pixels.

WebSocket Connection

The overlay connects to the Domscribe relay via WebSocket to receive real-time updates. It listens for annotation creation and update events to keep the UI in sync with agent activity. See Real-time Feedback for details on the WebSocket event system.

Related