Svelte Agentation

v0.2.1

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

Star on GitHub

Installation

npm i sv-agentation

Try It

The toolbar is active on this page. Press i to activate or deactivate it.

Usage

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

Features

The current release focuses on page-based annotations, compact toolbar settings, and copy modes that fit local AI workflows.

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.
Copy output in compact, standard, detailed, or forensic modes.
Use the denser floating toolbar with compact settings and output cycling.
Hook into local callbacks for note events and copy output.
Mount it only in development with browser-only setup.

Props

The public API now covers copy modes, route-aware sessions, and local callbacks without pushing routing work onto the host app.

Core Props

Mounting, source opening, and route/session controls.

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'`	Initial preset for the floating toolbar position.
`pageSessionKey`	`string \| null`	Optional advanced override for route scoping. Normal usage does not need this.

Behavior Props

Copy output, toolbar behavior, and capture detail controls.

Prop	Type	Description
`outputMode`	`'compact' \| 'standard' \| 'detailed' \| 'forensic'`	Controls how much annotation context is copied.
`pauseAnimations`	`boolean`	Pauses host-page animations while the inspector is active.
`clearOnCopy`	`boolean`	Clears current page notes after a successful copy.
`includeComponentContext`	`boolean`	Includes component-chain context when available.
`includeComputedStyles`	`boolean`	Includes computed-style metadata when the output mode allows it.
`copyToClipboard`	`boolean`	Lets you intercept copy output without writing to the clipboard.

Lifecycle Callbacks

Local integration hooks for notes and copy output.

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

Examples

These examples focus on the newer surface area added after the first alpha: page-based annotations, richer copy behavior, and callback-driven local integrations.

Behavior controls

Set a default output mode, pause animations, and keep component context enabled for richer local reviews.

Lifecycle callbacks

Use annotation and copy callbacks to feed your own local tooling, metrics, or AI workflow prompts.

Advanced session override

Use pageSessionKey only when you want to manually scope notes. Most apps can rely on automatic route tracking.

Shortcuts

These are the keyboard shortcuts and selection gestures currently used by the inspector.

Shortcut	Action	Description
`i`	Toggle inspector	Open or close the inspector toolbar and annotation mode.
`c`	Copy all notes	Copy notes as Markdown when at least one note exists.
`r`	Reset toolbar position	Move the floating toolbar back to its default bottom-right placement.
`o`	Open source	Open the currently hovered source location when the inspector is active.
`esc`	Cancel current action	Clear transient selections, close the composer, or close settings/delete state.
`shiftctrl/cmdclick`	Build a group selection	Add or remove elements from a grouped annotation target before releasing the modifiers.