Svelte Agentation

v0.2.2

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.

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.

Typed prop-driven mount

Keep a typed props object in your layout or playground and spread it into Agentation so explicit props stay in charge of toolbar behavior.

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 the explicit prop value, or to bottom-right when uncontrolled.
`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.

Props

After the examples, this is the full prop reference for copy modes, route-aware sessions, and local callbacks.

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'`	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.

Behavior Props

Copy output, toolbar behavior, and capture detail controls.

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

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.