SDK ReferenceOverlay Renderer

Overlay Renderer (renderer.ts)

The OverlayRenderer class directly paints vectors onto the 2D Canvas overlay, providing all visual interaction affordances.

OverlayRenderer

Constructor

const renderer = new OverlayRenderer(canvas: HTMLCanvasElement, style?: Partial<OverlayStyle>)

The renderer operates on the HTML5 Canvas 2D Context. It draws:

  • Primary/secondary element borders with glow effects
  • Grab handles (8-directional resize anchors)
  • Margin/padding spacer handles with coordinate value tooltips
  • Layout mode badges (flex, grid, block) and JS badges
  • Grid track visualization
  • Alignment snap guides
  • Marquee selection boundaries
  • Drop zone highlights and insertion indicators
  • Drag/resize coordinate tooltips

Helper Functions

anchorCursor(anchor)

Returns the appropriate CSS cursor indicator for a resize handle direction.

function anchorCursor(anchor: ResizeAnchor | null): string
// e.g., anchorCursor('nw') → 'nwse-resize'
// anchorCursor(null) → 'default'

computeAlignmentGuides(movingRect, otherRects, threshold?)

Generates alignment snap guides by comparing a moving element’s edges (left, center, right, top, middle, bottom) against all other element rects.

function computeAlignmentGuides(
  movingRect: Readonly<Rect>,
  otherRects: ReadonlyArray<Readonly<Rect>>,
  threshold?: number,    // Default: 5 canvas-space px
): Guide[]

Returns an array of Guide objects representing alignment lines where snapping should occur.

computeSnappedPosition(movingRect, otherRects, threshold?)

Computes the final snapped position based on alignment targets. If any edge or center of the moving rect is within threshold of an alignment target, the returned position snaps exactly onto that target.

function computeSnappedPosition(
  movingRect: Readonly<Rect>,
  otherRects: ReadonlyArray<Readonly<Rect>>,
  threshold?: number,    // Default: 5 canvas-space px
): Vec2

isContainerNode(node)

Returns whether a node is structurally or behaviorally a container node (can hold children or is layout container).

function isContainerNode(node: ResolvedNode): boolean

Type Definitions

Guide

An alignment snap guide line in canvas-space.

interface Guide {
  /** Which axis the guide runs along. "x" = vertical line, "y" = horizontal line. */
  axis: "x" | "y"
  /** Canvas-space coordinate on the perpendicular axis. */
  position: number
}

OverlayFrame

The complete description of a single overlay frame. Passed to OverlayRenderer.render() each time the workspace state changes.

interface OverlayFrame {
  /** Current viewport transform. */
  viewport: ViewportMatrix
  /** All mounted nodes with their canvas-space rects and hierarchy data. */
  nodes: ReadonlyArray<ResolvedNode>
  /** Set of currently selected node IDs. */
  selectedIds: ReadonlySet<string>
  /** ID of the node under the cursor (hover), or null. */
  hoveredId: string | null
  /** The resize anchor currently being dragged, or null. */
  activeAnchor: ResizeAnchor | null
  /** Alignment guides to render. */
  guides: ReadonlyArray<Guide>
  /** ID of the node currently being dragged, or null. */
  draggedNodeId?: string | null
  /** ID of the node currently being resized, or null. */
  resizedNodeId?: string | null
 
  // Layout overlays
  /** Layout mode badges to render on selected containers. */
  layoutBadges?: ReadonlyArray<LayoutBadgeInfo>
  /** Grid track overlays to render on selected grid containers. */
  gridOverlays?: ReadonlyArray<GridOverlayInfo>
 
  // Drag & Drop overlays
  /** Active drop zone target container and index. */
  activeDropTarget?: DropTarget | null
 
  // UX Controls
  /** Active marquee selection rect in canvas-space. */
  marqueeRect?: Rect | null
  /** Active spacing adjusters to render. */
  spacingAdjusters?: ReadonlyArray<SpacingAdjusterInfo>
  /** Active drawing element bounds in canvas-space. */
  drawingRect?: Rect | null
  /** Active drawing element HTML tag name. */
  drawingTag?: string | null
  /** Active or hovered corner radius handle name (tl, tr, bl, br). */
  activeRadiusCorner?: string | null
}

LayoutBadgeInfo

Badge label and position for a layout container or a guest JavaScript interactive element.

interface LayoutBadgeInfo {
  /** Canvas-space rect of the container. */
  rect: Rect
  /** Short label like "FLEX →", "GRID", "BLOCK". */
  label: string
  /** True if this is a script/JS badge (renders in amber). */
  isJS?: boolean
}

GridOverlayInfo

Grid track overlay data for CSS Grid containers.

interface GridOverlayInfo {
  /** Canvas-space rect of the container. */
  rect: Rect
  /** Column tracks (offsets relative to container padding edge). */
  columns: ReadonlyArray<GridTrack>
  /** Row tracks. */
  rows: ReadonlyArray<GridTrack>
}

SpacingAdjusterType

The type of spacing adjuster being rendered or interacted with.

type SpacingAdjusterType =
  | "padding-top"
  | "padding-right"
  | "padding-bottom"
  | "padding-left"
  | "margin-top"
  | "margin-right"
  | "margin-bottom"
  | "margin-left"

SpacingAdjusterInfo

Data for rendering a single spacing adjuster handle.

interface SpacingAdjusterInfo {
  /** Which spacing property this adjuster controls. */
  type: SpacingAdjusterType
  /** Bounding box of the handle bar in canvas-space. */
  rect: Rect
  /** Visual bounding box representing the actual spacing dimensions exactly. */
  visualRect: Rect
  /** Spacing value in pixels. */
  value: number
  /** Whether the adjuster is currently hovered. */
  isHovered: boolean
  /** Whether the adjuster is actively being dragged. */
  isActive: boolean
}

Padding adjusters are drawn in green (rgba(34, 197, 94, ...)), margin adjusters in orange (rgba(249, 115, 22, ...)). Active adjusters show a live numeric tooltip with the current pixel value.

Layout IntrospectionDrop Zone & DnD