Skip to content

feat: add priorityAttribute support for element identification #51

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
JungHoe wants to merge 1 commit into
base: main
Choose a base branch
from
Open

feat: add priorityAttribute support for element identification #51

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 38 additions & 14 deletions _package-export/example/src/app/api/page.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,54 +60,80 @@ export default function APIPage() {
<div className="prop-item">
<div className="prop-header">
<code className="prop-name">onAnnotationAdd</code>
<span className="prop-type">(annotation: Annotation) =&gt; void</span>
<span className="prop-type">
(annotation: Annotation) =&gt; void
</span>
</div>
<p className="prop-desc">Called when an annotation is created</p>
</div>
<div className="prop-item">
<div className="prop-header">
<code className="prop-name">onAnnotationDelete</code>
<span className="prop-type">(annotation: Annotation) =&gt; void</span>
<span className="prop-type">
(annotation: Annotation) =&gt; void
</span>
</div>
<p className="prop-desc">Called when an annotation is deleted</p>
</div>
<div className="prop-item">
<div className="prop-header">
<code className="prop-name">onAnnotationUpdate</code>
<span className="prop-type">(annotation: Annotation) =&gt; void</span>
<span className="prop-type">
(annotation: Annotation) =&gt; void
</span>
</div>
<p className="prop-desc">Called when an annotation comment is edited</p>
<p className="prop-desc">
Called when an annotation comment is edited
</p>
</div>
<div className="prop-item">
<div className="prop-header">
<code className="prop-name">onAnnotationsClear</code>
<span className="prop-type">(annotations: Annotation[]) =&gt; void</span>
<span className="prop-type">
(annotations: Annotation[]) =&gt; void
</span>
</div>
<p className="prop-desc">Called when all annotations are cleared</p>
<p className="prop-desc">
Called when all annotations are cleared
</p>
</div>
<div className="prop-item">
<div className="prop-header">
<code className="prop-name">onCopy</code>
<span className="prop-type">(markdown: string) =&gt; void</span>
</div>
<p className="prop-desc">Callback with the markdown output when copy is clicked</p>
<p className="prop-desc">
Callback with the markdown output when copy is clicked
</p>
</div>
<div className="prop-item">
<div className="prop-header">
<code className="prop-name">copyToClipboard</code>
<span className="prop-type">boolean</span>
<span className="prop-default">default: true</span>
</div>
<p className="prop-desc">Set to false to prevent writing to clipboard (if handling via onCopy)</p>
<p className="prop-desc">
Set to false to prevent writing to clipboard (if handling via
onCopy)
</p>
</div>
<div className="prop-item">
<div className="prop-header">
<code className="prop-name">priorityAttribute</code>
<span className="prop-type">string</span>
<span className="prop-default">default: "data-testid"</span>
</div>
<p className="prop-desc">
Attribute used for highest priority element identification (e.g.
"data-cy", "data-test-id")
</p>
</div>
</div>
</section>

<section>
<h2>Basic usage</h2>
<p>
Receive annotation data directly in your code:
</p>
<p>Receive annotation data directly in your code:</p>
<CodeBlock
code={`import { Agentation, Annotation } from "agentation";

Expand Down Expand Up @@ -162,9 +188,7 @@ function App() {

<section>
<h2>TypeScript</h2>
<p>
Types are exported for full TypeScript support:
</p>
<p>Types are exported for full TypeScript support:</p>
<CodeBlock
code={`import type { Annotation, AgentationProps } from "agentation";`}
/>
Expand Down
176 changes: 142 additions & 34 deletions _package-export/example/src/app/page.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,71 +21,145 @@ export default function AgentationDocs() {

<section>
<p>
Agentation (<span style={{ color: 'rgba(0,0,0,0.5)' }}>agent + annotation</span>) is a dev tool that lets you annotate elements on your webpage
and generate structured feedback for AI coding agents.
Agentation (
<span style={{ color: "rgba(0,0,0,0.5)" }}>agent + annotation</span>
) is a dev tool that lets you annotate elements on your webpage and
generate structured feedback for AI coding agents.
</p>
<p>
Click elements, select text, add notes, and paste the output into Claude Code, Cursor, or
any agent that has access to your codebase. It&rsquo;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&rsquo;s fully agent-agnostic, so the markdown output works with
any AI tool. Zero dependencies beyond React.
</p>
<p>
The key insight: agents can find and fix code much faster when they
know exactly which element you&rsquo;re referring to. Agentation captures
class names, selectors, and positions so the agent can locate the corresponding
source files.
know exactly which element you&rsquo;re referring to. Agentation
captures class names, selectors, and positions so the agent can
locate the corresponding source files.
</p>
<p>
It grew out of <a href="https://benji.org/annotating" className="styled-link" target="_blank" rel="noopener noreferrer">a post by Benji Taylor</a> exploring
how to give better feedback to AI coding agents.
It grew out of{" "}
<a
href="https://benji.org/annotating"
className="styled-link"
target="_blank"
rel="noopener noreferrer"
>
a post by Benji Taylor
</a>{" "}
exploring how to give better feedback to AI coding agents.
</p>
</section>

<section>
<h2>Quick start</h2>
<ol>
<li>Click the <svg style={{ display: 'inline-block', verticalAlign: '-0.45em', width: '1.5em', height: '1.5em', margin: '0 -0.1em' }} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round"><path d="M11.5 12L5.5 12" /><path d="M18.5 6.75L5.5 6.75" /><path d="M9.25 17.25L5.5 17.25" /><path d="M16 12.75L16.5179 13.9677C16.8078 14.6494 17.3506 15.1922 18.0323 15.4821L19.25 16L18.0323 16.5179C17.3506 16.8078 16.8078 17.3506 16.5179 18.0323L16 19.25L15.4821 18.0323C15.1922 17.3506 14.6494 16.8078 13.9677 16.5179L12.75 16L13.9677 15.4821C14.6494 15.1922 15.1922 14.6494 15.4821 13.9677L16 12.75Z" /></svg> icon in the bottom-right corner to activate</li>
<li><strong>Hover</strong> over elements to see their names highlighted</li>
<li><strong>Click</strong> any element to add an annotation</li>
<li>Write your feedback and click <strong>Add</strong></li>
<li>Click <svg style={{ display: 'inline-block', verticalAlign: '-0.45em', width: '1.5em', height: '1.5em', margin: '0 -0.1em' }} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round"><path d="M4.75 11.25C4.75 10.4216 5.42157 9.75 6.25 9.75H12.75C13.5784 9.75 14.25 10.4216 14.25 11.25V17.75C14.25 18.5784 13.5784 19.25 12.75 19.25H6.25C5.42157 19.25 4.75 18.5784 4.75 17.75V11.25Z" /><path d="M17.25 14.25H17.75C18.5784 14.25 19.25 13.5784 19.25 12.75V6.25C19.25 5.42157 18.5784 4.75 17.75 4.75H11.25C10.4216 4.75 9.75 5.42157 9.75 6.25V6.75" /></svg> to copy formatted markdown</li>
<li>
Click the{" "}
<svg
style={{
display: "inline-block",
verticalAlign: "-0.45em",
width: "1.5em",
height: "1.5em",
margin: "0 -0.1em",
}}
viewBox="0 0 24 24"
fill="none"
stroke="currentColor"
strokeWidth="1.5"
strokeLinecap="round"
strokeLinejoin="round"
>
<path d="M11.5 12L5.5 12" />
<path d="M18.5 6.75L5.5 6.75" />
<path d="M9.25 17.25L5.5 17.25" />
<path d="M16 12.75L16.5179 13.9677C16.8078 14.6494 17.3506 15.1922 18.0323 15.4821L19.25 16L18.0323 16.5179C17.3506 16.8078 16.8078 17.3506 16.5179 18.0323L16 19.25L15.4821 18.0323C15.1922 17.3506 14.6494 16.8078 13.9677 16.5179L12.75 16L13.9677 15.4821C14.6494 15.1922 15.1922 14.6494 15.4821 13.9677L16 12.75Z" />
</svg>{" "}
icon in the bottom-right corner to activate
</li>
<li>
<strong>Hover</strong> over elements to see their names
highlighted
</li>
<li>
<strong>Click</strong> any element to add an annotation
</li>
<li>
Write your feedback and click <strong>Add</strong>
</li>
<li>
Click{" "}
<svg
style={{
display: "inline-block",
verticalAlign: "-0.45em",
width: "1.5em",
height: "1.5em",
margin: "0 -0.1em",
}}
viewBox="0 0 24 24"
fill="none"
stroke="currentColor"
strokeWidth="1.5"
strokeLinecap="round"
>
<path d="M4.75 11.25C4.75 10.4216 5.42157 9.75 6.25 9.75H12.75C13.5784 9.75 14.25 10.4216 14.25 11.25V17.75C14.25 18.5784 13.5784 19.25 12.75 19.25H6.25C5.42157 19.25 4.75 18.5784 4.75 17.75V11.25Z" />
<path d="M17.25 14.25H17.75C18.5784 14.25 19.25 13.5784 19.25 12.75V6.25C19.25 5.42157 18.5784 4.75 17.75 4.75H11.25C10.4216 4.75 9.75 5.42157 9.75 6.25V6.75" />
</svg>{" "}
to copy formatted markdown
</li>
<li>Paste into your agent</li>
</ol>
</section>

<section>
<h2>How it works with agents</h2>
<p>
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.):
</p>
<ol>
<li>You see a bug or want a change in your running app</li>
<li>Use Agentation to annotate the element with your feedback</li>
<li>Copy the output and paste it into your agent</li>
<li>The agent uses the class names and selectors to <strong>search your codebase</strong></li>
<li>
The agent uses the class names and selectors to{" "}
<strong>search your codebase</strong>
</li>
<li>It finds the relevant component/file and makes the fix</li>
</ol>
<p>
Without Agentation, you&rsquo;d have to describe the element (&ldquo;the blue button
in the sidebar&rdquo;) and hope the agent guesses right. With Agentation, you give it
<code>.sidebar &gt; .nav-actions &gt; button.primary</code> and it can grep for that directly.
Without Agentation, you&rsquo;d have to describe the element
(&ldquo;the blue button in the sidebar&rdquo;) and hope the agent
guesses right. With Agentation, you give it
<code>.sidebar &gt; .nav-actions &gt; button.primary</code> and it
can grep for that directly.
</p>
</section>

{/* Interactive Demo Section - hidden on mobile since tool is desktop-only */}
<section className="demo-section hide-on-mobile">
<h2>Try it</h2>
<p>
The toolbar is active on this page. Try annotating these demo elements:
The toolbar is active on this page. Try annotating these demo
elements:
</p>

<div className="demo-elements">
<div className="button-group">
<button className="demo-button" onClick={() => alert("Primary clicked!")}>
<button
className="demo-button"
onClick={() => alert("Primary clicked!")}
data-testid="demo-primary-button"
>
Primary Button
</button>
<button className="demo-button secondary" onClick={() => alert("Secondary clicked!")}>
<button
className="demo-button secondary"
onClick={() => alert("Secondary clicked!")}
>
Secondary Button
</button>
</div>
Expand All @@ -98,11 +172,13 @@ export default function AgentationDocs() {
onChange={(e) => setInputValue(e.target.value)}
/>

<div className="demo-card">
<div className="demo-card" data-testid="example-card">
<h3>Example Card</h3>
<p>
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{" "}
<code>data-testid="example-card"</code>) or select this text to
create an annotation. The output will include the element path
and your feedback.
</p>
</div>
</div>
Expand All @@ -112,7 +188,25 @@ export default function AgentationDocs() {
<section className="demo-section hide-on-mobile">
<h2>Animation pause demo</h2>
<p>
Click <svg style={{ display: 'inline-block', verticalAlign: '-0.45em', width: '1.5em', height: '1.5em', margin: '0 -0.1em' }} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round"><path d="M8 6L8 18" /><path d="M16 18L16 6" /></svg> in the toolbar to freeze this animation:
Click{" "}
<svg
style={{
display: "inline-block",
verticalAlign: "-0.45em",
width: "1.5em",
height: "1.5em",
margin: "0 -0.1em",
}}
viewBox="0 0 24 24"
fill="none"
stroke="currentColor"
strokeWidth="1.5"
strokeLinecap="round"
>
<path d="M8 6L8 18" />
<path d="M16 18L16 6" />
</svg>{" "}
in the toolbar to freeze this animation:
</p>
<div className="animation-demo">
<div className="progress-bar-demo">
Expand All @@ -124,14 +218,28 @@ export default function AgentationDocs() {
<section>
<h2>Best practices</h2>
<ul>
<li><strong>Be specific</strong> &mdash; &ldquo;Button text unclear&rdquo; is better than &ldquo;fix this&rdquo;</li>
<li><strong>One issue per annotation</strong> &mdash; easier for the agent to address individually</li>
<li><strong>Include context</strong> &mdash; mention what you expected vs. what you see</li>
<li><strong>Use text selection</strong> &mdash; for typos or content issues, select the exact text</li>
<li><strong>Pause animations</strong> &mdash; to annotate a specific animation frame</li>
<li>
<strong>Be specific</strong> &mdash; &ldquo;Button text
unclear&rdquo; is better than &ldquo;fix this&rdquo;
</li>
<li>
<strong>One issue per annotation</strong> &mdash; easier for the
agent to address individually
</li>
<li>
<strong>Include context</strong> &mdash; mention what you expected
vs. what you see
</li>
<li>
<strong>Use text selection</strong> &mdash; for typos or content
issues, select the exact text
</li>
<li>
<strong>Pause animations</strong> &mdash; to annotate a specific
animation frame
</li>
</ul>
</section>

</article>

<Footer />
Expand Down
Loading