Feature request: Programmatic callback API for agentation

Issue-thing.md

Feature Request: Programmatic Callback API

Context

I'm exploring integrating agentation into Navigator, a browser automation tool for AI agents. Navigator has a "paired mode" where agents work alongside users in their browser — agentation's annotation UX would be a perfect fit for letting users visually mark elements for agents to interact with.

Current Limitation

Agentation currently outputs annotations via navigator.clipboard.writeText(). For integration into other tools, this requires intercepting the clipboard API, which is:

• Fragile (depends on internal implementation details)
• Potentially conflicts with user's actual clipboard usage
• Requires parsing markdown output back into structured data

Proposed API

A callback prop that fires when annotations are captured:

<Agentation
  onAnnotation={(annotation: Annotation) => {
    // Structured data, no parsing needed
    console.log(annotation)
  }}
  // Optional: control whether clipboard copy still happens
  copyToClipboard={false}
/>

Where Annotation might look like:

interface Annotation {
  selector: string
  element: {
    tag: string
    id?: string
    classes: string[]
    text?: string
  }
  position: {
    x: number
    y: number
    width: number
    height: number
  }
  note?: string
  timestamp: number
}

Benefits

• Programmatic integration: Tools can consume annotations directly without clipboard interception
• Type safety: Structured data instead of parsing markdown
• Flexibility: Users can still copy to clipboard OR handle programmatically OR both
• MCP integration: This would make the Claude Code MCP integration (Issue #15) much cleaner

Alternatives Considered

1. Clipboard interception — Works but hacky, fragile
2. Custom events — Would also work, but callback prop is more React-idiomatic
3. Ref with imperative handle — More complex, callback is simpler for this use case

Willingness to Contribute

Happy to submit a PR if you're open to this direction. The implementation should be straightforward — just adding an optional callback invocation alongside the existing clipboard logic.

---

Thanks for building agentation! The annotation UX is really nice.