From 5befd994a9789b837cd5d9f341b2b9a1113f6e61 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EC=9D=B4JungHoe?= Date: Mon, 26 Jan 2026 14:47:09 +0900 Subject: [PATCH] feat: add priorityAttribute support for element identification --- _package-export/example/src/app/api/page.tsx | 52 ++-- _package-export/example/src/app/page.tsx | 176 ++++++++++--- .../src/utils/element-identification.ts | 237 ++++++++++++++---- 3 files changed, 370 insertions(+), 95 deletions(-) diff --git a/_package-export/example/src/app/api/page.tsx b/_package-export/example/src/app/api/page.tsx index 504a68c..acb1631 100644 --- a/_package-export/example/src/app/api/page.tsx +++ b/_package-export/example/src/app/api/page.tsx @@ -60,37 +60,51 @@ export default function APIPage() {
onAnnotationAdd - (annotation: Annotation) => void + + (annotation: Annotation) => void +

Called when an annotation is created

onAnnotationDelete - (annotation: Annotation) => void + + (annotation: Annotation) => void +

Called when an annotation is deleted

onAnnotationUpdate - (annotation: Annotation) => void + + (annotation: Annotation) => void +
-

Called when an annotation comment is edited

+

+ Called when an annotation comment is edited +

onAnnotationsClear - (annotations: Annotation[]) => void + + (annotations: Annotation[]) => void +
-

Called when all annotations are cleared

+

+ Called when all annotations are cleared +

onCopy (markdown: string) => void
-

Callback with the markdown output when copy is clicked

+

+ Callback with the markdown output when copy is clicked +

@@ -98,16 +112,28 @@ export default function APIPage() { boolean default: true
-

Set to false to prevent writing to clipboard (if handling via onCopy)

+

+ Set to false to prevent writing to clipboard (if handling via + onCopy) +

+
+
+
+ priorityAttribute + string + default: "data-testid" +
+

+ Attribute used for highest priority element identification (e.g. + "data-cy", "data-test-id") +

Basic usage

-

- Receive annotation data directly in your code: -

+

Receive annotation data directly in your code:

TypeScript

-

- Types are exported for full TypeScript support: -

+

Types are exported for full TypeScript support:

diff --git a/_package-export/example/src/app/page.tsx b/_package-export/example/src/app/page.tsx index 5dc07d6..0f0eed2 100644 --- a/_package-export/example/src/app/page.tsx +++ b/_package-export/example/src/app/page.tsx @@ -21,34 +21,95 @@ export default function AgentationDocs() {

- Agentation (agent + annotation) is a dev tool that lets you annotate elements on your webpage - and generate structured feedback for AI coding agents. + Agentation ( + agent + annotation + ) is a dev tool that lets you annotate elements on your webpage and + generate structured feedback for AI coding agents.

- Click elements, select text, add notes, and paste the output into Claude Code, Cursor, or - any agent that has access to your codebase. It’s fully agent-agnostic, so the - markdown output works with any AI tool. Zero dependencies beyond React. + Click elements, select text, add notes, and paste the output into + Claude Code, Cursor, or any agent that has access to your codebase. + It’s fully agent-agnostic, so the markdown output works with + any AI tool. Zero dependencies beyond React.

The key insight: agents can find and fix code much faster when they - know exactly which element you’re referring to. Agentation captures - class names, selectors, and positions so the agent can locate the corresponding - source files. + know exactly which element you’re referring to. Agentation + captures class names, selectors, and positions so the agent can + locate the corresponding source files.

- It grew out of a post by Benji Taylor exploring - how to give better feedback to AI coding agents. + It grew out of{" "} + + a post by Benji Taylor + {" "} + exploring how to give better feedback to AI coding agents.

Quick start

    -
  1. Click the icon in the bottom-right corner to activate
    2. -
  2. Hover over elements to see their names highlighted
    3. -
  3. Click any element to add an annotation
    4. -
  4. Write your feedback and click Add
    5. -
  5. Click to copy formatted markdown
    6. +
  6. + Click the{" "} + + + + + + {" "} + icon in the bottom-right corner to activate +
    7. +
  7. + Hover over elements to see their names + highlighted +
    8. +
  8. + Click any element to add an annotation +
    9. +
  9. + Write your feedback and click Add +
    10. +
  10. + Click{" "} + + + + {" "} + to copy formatted markdown +
  11. Paste into your agent
@@ -56,20 +117,25 @@ export default function AgentationDocs() {

How it works with agents

- Agentation works best with AI tools that have access to your codebase - (Claude Code, Cursor, Windsurf, etc.): + Agentation works best with AI tools that have access to your + codebase (Claude Code, Cursor, Windsurf, etc.):

  1. You see a bug or want a change in your running app
  2. Use Agentation to annotate the element with your feedback
  3. Copy the output and paste it into your agent
    4. -
  4. The agent uses the class names and selectors to search your codebase
    5. +
  5. + The agent uses the class names and selectors to{" "} + search your codebase +
  6. It finds the relevant component/file and makes the fix

- Without Agentation, you’d have to describe the element (“the blue button - in the sidebar”) and hope the agent guesses right. With Agentation, you give it - .sidebar > .nav-actions > button.primary and it can grep for that directly. + Without Agentation, you’d have to describe the element + (“the blue button in the sidebar”) and hope the agent + guesses right. With Agentation, you give it + .sidebar > .nav-actions > button.primary and it + can grep for that directly.

@@ -77,15 +143,23 @@ export default function AgentationDocs() {

Try it

- The toolbar is active on this page. Try annotating these demo elements: + The toolbar is active on this page. Try annotating these demo + elements:

- -
@@ -98,11 +172,13 @@ export default function AgentationDocs() { onChange={(e) => setInputValue(e.target.value)} /> -
+

Example Card

- Click on this card or select this text to create an annotation. - The output will include the element path and your feedback. + Click on this card (it has a{" "} + data-testid="example-card") or select this text to + create an annotation. The output will include the element path + and your feedback.

@@ -112,7 +188,25 @@ export default function AgentationDocs() {

Animation pause demo

- Click in the toolbar to freeze this animation: + Click{" "} + + + + {" "} + in the toolbar to freeze this animation:

@@ -124,14 +218,28 @@ export default function AgentationDocs() {

Best practices

    -
  • Be specific — “Button text unclear” is better than “fix this”
    • -
  • One issue per annotation — easier for the agent to address individually
    • -
  • Include context — mention what you expected vs. what you see
    • -
  • Use text selection — for typos or content issues, select the exact text
    • -
  • Pause animations — to annotate a specific animation frame
    • +
  • + Be specific — “Button text + unclear” is better than “fix this” +
    • +
  • + One issue per annotation — easier for the + agent to address individually +
    • +
  • + Include context — mention what you expected + vs. what you see +
    • +
  • + Use text selection — for typos or content + issues, select the exact text +
    • +
  • + Pause animations — to annotate a specific + animation frame +
-