solid-agentation

A visual annotation tool for providing structured feedback to AI coding agents. Click or drag-select UI elements, add comments, and copy rich Markdown output containing element selectors, component hierarchy, computed styles, and accessibility info.

SolidJS port of agentation with Solid component detection via solid-devtools.

Installation

bun add solid-agentation

Usage

import { Agentation } from "solid-agentation"

export function App() {
  return (
    <>
      <Router>{/* ... */}</Router>
      {import.meta.env.DEV && <Agentation />}
    </>
  )
}

For Solid component detection, configure Vite:

// vite.config.ts
import devtools from "solid-devtools/vite"

export default defineConfig({
  plugins: [
    devtools({
      autoname: true,
      locator: { jsxLocation: true, componentLocation: true },
    }),
    // ...
  ],
})

And import devtools in your entry file:

// entry.tsx
import "solid-devtools"

Features

| Feature | Description | |---------|-------------| | Single-click | Click element, type feedback, marker placed | | Multi-select | Drag rectangle to select multiple elements | | Text selection | Selected text included in output | | Deep freeze | F4 or freeze button freezes page state (keeps dropdowns/modals open for annotation) | | Alt+Click | Hold Alt and click to force-annotate interactive elements | | Block interactions | Toggle to prevent page clicks from firing native behavior | | Solid detection | Output includes <ComponentA> <ComponentB> hierarchy | | Output levels | Compact, Standard, Detailed, Forensic | | Fixed elements | Markers stay fixed for fixed/sticky positioned elements | | Persistence | Annotations saved to localStorage per page (7-day retention) | | Draggable toolbar | Toolbar can be repositioned anywhere | | Dark/light mode | Theme toggle in settings panel | | Marker colors | 7 color options for annotation markers |

Interaction Modes

Default

Click any non-interactive element to annotate it. Interactive elements (buttons, links, inputs) pass through normally.

Block Page Interactions

Toggle in settings. All page clicks create annotations instead of firing native behavior. Toolbar remains fully interactive.

Alt+Click

Hold Alt and click any element to force-annotate it, including buttons, links, and inputs. No mode switching needed.

Deep Freeze (F4)

For annotating dynamic UI (dropdowns, modals, tooltips):

1. Open the dropdown/modal on the page
2. Press F4 or click the freeze button (pause icon)
3. Page freezes: animations paused, pointer events blocked
4. Click any frozen element to annotate it
5. Press F4 again to unfreeze

Output Detail Levels

Compact

1. **button "Submit"**: Button color too dark

Standard

### 1. <Form> <SubmitButton> button "Submit"
**Location:** .form-container > form > button
**Feedback:** Button color too dark

Detailed

### 1. <Form> <SubmitButton> button "Submit"
**Location:** .form-container > form > button
**Classes:** btn, btn-primary, submit-btn
**Position:** 450px, 320px (120x40px)
**Context:** [before: "Email"] [after: "Cancel"]
**Feedback:** Button color too dark

Forensic

### 1. button "Submit"
**Solid Components:** Form > SubmitButton
**Full DOM Path:** body > div.app > main.content > form.login-form > button.submit-btn
**CSS Classes:** btn, btn-primary, submit-btn
**Computed Styles:** background-color: rgb(59, 130, 246) #3b82f6; color: rgb(255, 255, 255) #ffffff; ...
**Accessibility:** role="button", focusable
**Selection Bounds:** x:450, y:320 (120x40px)
**Annotation at:** 35.2% from left, 320px from top
**Feedback:** Button color too dark

API

<Agentation>

Main component. Renders a floating toolbar and annotation system in a Portal.

interface AgentationProps {
  onAnnotationAdd?: (annotation: Annotation) => void
  onAnnotationDelete?: (annotation: Annotation) => void
  onAnnotationUpdate?: (annotation: Annotation) => void
  onAnnotationsClear?: (annotations: Annotation[]) => void
  onCopy?: (markdown: string) => void
  copyToClipboard?: boolean  // default: true

  // Demo mode
  demoAnnotations?: DemoAnnotation[]
  demoDelay?: number
  enableDemoMode?: boolean
}

<AnnotationPopup>

Standalone popup for custom annotation UIs.

interface AnnotationPopupProps {
  element: string
  selectedText?: string
  computedStyles?: Map<string, string>
  placeholder?: string
  initialValue?: string
  submitLabel?: string
  onSubmit: (text: string) => void
  onCancel: () => void
  style?: JSX.CSSProperties
  accentColor?: string
  isExiting?: boolean
  lightMode?: boolean
  ref?: (handle: AnnotationPopupHandle) => void
}

interface AnnotationPopupHandle {
  shake: () => void
}

Keyboard Shortcuts

| Key | Action | |-----|--------| | Escape | Close popup / exit feedback mode | | F4 | Toggle deep freeze | | Alt + Click | Force-annotate any element |

License

MIT - Copyright (c) 2026 Dr. Skill Issue

Derivative of agentation by Benji Taylor (PolyForm Shield 1.0.0)