Svelte Agentation

v0.3.0

Svelte Agentation turns UI annotations into structured context that AI coding agents can understand and act on. Click any element, add a note, and paste the output into Claude Code, Cursor, or any AI tool.

Changelog

Sponsor Star on GitHub

Installation

pnpm add sv-agentation

Try It

The toolbar is active on this page. Press i to activate or deactivate it, then use the new preview button to scan saved notes or hover a marker to preview the exact area before opening it.

Works for shadow DOM too!

The inspector pierces open shadow roots, so elements inside web components are fully hoverable, clickable, and annotatable just like the rest of the page.

Usage

Mount the component only in development and only in the browser. Route-scoped sessions are now automatic, so the default setup stays small.

Examples

After the basic mount, these are the most common ways to configure the inspector for real project workflows.

Typed prop-driven mount

Start with one typed props object and spread it into Agentation when you want a small, predictable setup.

Behavior controls

Set default copy and capture behavior up front so every review starts with the same output shape.

Lifecycle callbacks

Tap into save and copy events when you want to forward notes into your own local tooling or prompts.

Advanced session override

Only reach for manual session scoping when route-based note isolation is not enough for your app.

Keyboard Shortcuts

These are the default keyboard shortcuts and selection gestures used by the inspector. The keyboard actions can be overridden with the keyBindings prop.

Shortcut	Action	Description
`i`	Inspect	Toggle the inspector toolbar and annotation mode. Configurable with keyBindings.inspect.
`c`	Copy	Copy notes as Markdown when at least one note exists. Configurable with keyBindings.copy.
`r`	Reset	Reset the floating toolbar position. Configurable with keyBindings.reset.
`o`	Open	Open the currently hovered source location when the inspector is active. Configurable with keyBindings.open.
`d`	Delete	Delete the currently edited note from the composer. Configurable with keyBindings.delete.
`esc`	Cancel	Clear transient selections, close the composer, or close settings/delete state. Configurable with keyBindings.cancel.
`enter`	Submit	Submit the current note from the composer. Configurable with keyBindings.submit.
`shiftctrl/cmdclick`	Build a group selection	Add or remove elements from a grouped annotation target before releasing the modifiers. This pointer gesture stays fixed in v1.

Props

Start here for the core mount and routing options that most apps touch first.

Prop	Type	Description
`workspaceRoot`	`string \| null`	Absolute project root for source lookup and editor links.
`selector`	`string \| null`	Optional selector to scope inspectable elements.
`vscodeScheme`	`'vscode' \| 'vscode-insiders'`	Choose the VS Code URL scheme for open-in-editor actions.
`openSourceOnClick`	`boolean`	Open source directly on click instead of only showing metadata.
`deleteAllDelayMs`	`number`	Confirmation delay for delete-all notes.
`toolbarPosition`	`'top-left' \| 'top-center' \| 'top-right' \| 'mid-right' \| 'mid-left' \| 'bottom-left' \| 'bottom-center' \| 'bottom-right'`	When provided, keeps the toolbar anchored to this preset and overrides saved toolbar placements.
`pageSessionKey`	`string \| null`	Optional advanced override for route scoping. Normal usage does not need this.
`keyBindings`	`Partial<Record<'inspect' \| 'copy' \| 'reset' \| 'open' \| 'delete' \| 'cancel' \| 'submit', string \| null>>`	Override or disable keyboard actions without changing saved toolbar settings.

Behavior Props

Use these when you want to tune output mode, capture detail, and copy behavior.

Prop	Type	Description
`outputMode`	`'compact' \| 'standard' \| 'detailed' \| 'forensic'`	When provided, controls the copy mode and overrides saved toolbar settings.
`pauseAnimations`	`boolean`	When provided, controls animation pausing and overrides saved toolbar settings.
`clearOnCopy`	`boolean`	When provided, controls note clearing after copy and overrides saved toolbar settings.
`includeComponentContext`	`boolean`	When provided, controls component-context capture and overrides saved toolbar settings.
`includeComputedStyles`	`boolean`	When provided, controls computed-style capture and overrides saved toolbar settings.
`copyToClipboard`	`boolean`	Lets you intercept copy output without writing to the clipboard.

Lifecycle Callbacks

These hooks let you react to note creation, updates, deletes, clears, and copy events.

Prop	Type	Description
`onAnnotationAdd`	`(annotation: Annotation) => void`	Fires when a new annotation is saved.
`onAnnotationUpdate`	`(annotation: Annotation) => void`	Fires when an existing annotation is edited.
`onAnnotationDelete`	`(annotation: Annotation) => void`	Fires when one annotation is removed.
`onAnnotationsClear`	`(annotations: Annotation[]) => void`	Fires after the current page notes are cleared.
`onCopy`	`(markdown: string, payload: AnnotationPayload) => void`	Receives the generated markdown and structured export payload.

Features

The tool stays small on purpose, but still covers the key annotation and review flows needed for daily local work.

Inspect source-aware DOM elements and jump to their files quickly.
Annotate elements, text ranges, grouped targets, and selected areas.
Keep notes isolated per page automatically as routes change.
Hover saved note markers to preview the exact area that will be updated.
Copy output in compact, standard, detailed, or forensic modes.
Use the denser floating toolbar with compact settings and output cycling.
Composer add, save, cancel, and delete flows now close with smoother fade-out motion.
Hook into local callbacks for note events and copy output.
Mount it only in development with browser-only setup.