@visulima/dev-toolbar 1.0.0-alpha.14 → 1.0.0-alpha.16

package/CHANGELOG.md

@@ -1,3 +1,16 @@
+## @visulima/dev-toolbar [1.0.0-alpha.16](https://github.com/visulima/visulima/compare/@visulima/dev-toolbar@1.0.0-alpha.15...@visulima/dev-toolbar@1.0.0-alpha.16) (2026-05-06)
+
+### Miscellaneous Chores
+
+* **dev-toolbar:** apply prettier and eslint quote-style auto-fix ([3bb9b50](https://github.com/visulima/visulima/commit/3bb9b50337d5bbc0e3a1bd372a69ceebad1fb188))
+* **dev-toolbar:** housekeeping cleanup ([d7c5ed5](https://github.com/visulima/visulima/commit/d7c5ed5518069405476212d8a9814af50cf2ef15))
+
+## @visulima/dev-toolbar [1.0.0-alpha.15](https://github.com/visulima/visulima/compare/@visulima/dev-toolbar@1.0.0-alpha.14...@visulima/dev-toolbar@1.0.0-alpha.15) (2026-05-04)
+
+### Miscellaneous Chores
+
+* **dev-toolbar:** allow zod v4 and align eslint-plugin-zod with catalog ([70733ad](https://github.com/visulima/visulima/commit/70733ad6155c3bc460d2bc0943f88af59b7b6725))
+
 ## @visulima/dev-toolbar [1.0.0-alpha.14](https://github.com/visulima/visulima/compare/@visulima/dev-toolbar@1.0.0-alpha.13...@visulima/dev-toolbar@1.0.0-alpha.14) (2026-04-30)
 
 ### Miscellaneous Chores

package/dist/apps/inspector/index.js

@@ -18,7 +18,7 @@ var Bn=Object.defineProperty;var ae=(e,t)=>Bn(e,"name",{value:t,configurable:!0}
 
 No annotations found.`;if(t==="compact"){const o=[`# Annotations (${e.length})`,""];for(const i of e){const r=i.elementLabel??i.elementTag,a=i.selectedText?` (re: "${i.selectedText.slice(0,30)}...")`:"";o.push(`- **${r}:** ${i.comment}${a}`)}return o.join(`
 `)}const n=["# Annotations","",`> ${e.length} annotation(s)`,""];for(const[o,i]of e.entries()){const r=i.elementLabel??i.elementTag;if(n.push(`## ${o+1}. [${i.intent.toUpperCase()}] ${i.severity} — ${r}`,"",`**Status:** ${i.status}`,`**URL:** ${i.url}`),i.elementPath&&n.push(`**Selector:** \`${i.elementPath}\``),i.source&&n.push(`**Source:** \`${i.source}\``),i.frameworkContext){const a=i.frameworkContext;n.push(`**Component:** ${a.componentName} (${a.framework})`),a.componentStack&&a.componentStack.length>1&&n.push(`**Stack:** ${a.componentStack.join(" > ")}`),a.sourceFile&&n.push(`**File:** \`${a.sourceFile}${a.sourceLine?`:${a.sourceLine}`:""}\``)}i.selectedText&&n.push(`**Selected:** "${i.selectedText}"`),(t==="detailed"||t==="forensic")&&(i.cssClasses&&n.push(`**Classes:** \`${i.cssClasses}\``),i.nearbyText&&n.push(`**Context:** ${i.nearbyText}`),i.fullPath&&n.push(`**DOM Path:** \`${i.fullPath}\``)),t==="forensic"&&(i.accessibility?.role&&n.push(`**Role:** ${i.accessibility.role}`),i.nearbyElements&&n.push(`**Nearby:** ${i.nearbyElements}`),i.computedStyles&&n.push(`**Styles:** \`${i.computedStyles}\``)),n.push("",i.comment,"","---","")}return n.join(`
-`)},"annotationsToMarkdown"),Vn=Object.defineProperty({__proto__:null,annotationsToMarkdown:Ct,captureAccessibility:dn,captureComputedStyles:wt,captureElementScreenshot:un,cleanCssClasses:rn,deepElementFromPoint:_e,detectFrameworkComponent:pn,generateSelector:nn,getElementBoundingBoxes:gn,getElementLabel:Tt,getElementsInRect:mn,getFullDomPath:an,getNearbyElements:sn,getNearbyText:ln,getParentElement:en,getSelectedText:cn,getViewportRect:st,isElementFixed:tn,pierceElementFromPoint:rt},Symbol.toStringTag,{value:"Module"});var Yn=Object.defineProperty,ue=ae((e,t)=>Yn(e,"name",{value:t,configurable:!0}),"r$1");const Xn=["id^='__vdt_'","class*='__vdt_'"],xt=Xn.flatMap(e=>[`:not([${e}])`,`:not([${e}] *)`]).join(""),$t="__vdt_freeze_styles",ht="__vdt_freeze_state",ce=1e3,Un=ue(()=>{if(globalThis.window===void 0)return{frozen:!1,frozenRAFQueue:[],frozenTimeoutQueue:[],installed:!0,origRAF:ue((()=>0),"origRAF"),origSetInterval:ue((()=>0),"origSetInterval"),origSetTimeout:ue((()=>0),"origSetTimeout"),pausedAnimations:[]};const e=globalThis;return e[ht]||(e[ht]={frozen:!1,frozenRAFQueue:[],frozenTimeoutQueue:[],installed:!1,origRAF:null,origSetInterval:null,origSetTimeout:null,pausedAnimations:[]}),e[ht]},"getState"),E=Un();globalThis.window!==void 0&&!E.installed&&(E.origSetTimeout=globalThis.setTimeout.bind(globalThis),E.origSetInterval=globalThis.setInterval.bind(globalThis),E.origRAF=globalThis.requestAnimationFrame.bind(globalThis),globalThis.setTimeout=(e,t,...n)=>typeof e=="string"?E.origSetTimeout(e,t):E.origSetTimeout((...o)=>{E.frozen?E.frozenTimeoutQueue.length<ce?E.frozenTimeoutQueue.push(()=>e(...o)):E.frozenTimeoutQueue.length===ce&&(E.frozenTimeoutQueue.push(()=>{}),console.warn(`[dev-toolbar] frozenTimeoutQueue exceeded ${ce} entries — further callbacks are being dropped.`)):e(...o)},t,...n),globalThis.setInterval=(e,t,...n)=>typeof e=="string"?E.origSetInterval(e,t):E.origSetInterval((...o)=>{E.frozen||e(...o)},t,...n),globalThis.requestAnimationFrame=e=>E.origRAF(t=>{E.frozen?E.frozenRAFQueue.length<ce?E.frozenRAFQueue.push(e):E.frozenRAFQueue.length===ce&&(E.frozenRAFQueue.push(()=>{}),console.warn(`[dev-toolbar] frozenRAFQueue exceeded ${ce} entries — further callbacks are being dropped.`)):e(t)}),E.installed=!0);const xn=E.origSetTimeout,Qn=ue(()=>E.frozen,"isFrozen"),Kn=ue(()=>{if(typeof document>"u"||E.frozen)return;E.frozen=!0,E.frozenTimeoutQueue=[],E.frozenRAFQueue=[];let e=document.getElementById($t);e||(e=document.createElement("style"),e.id=$t),e.textContent=`
+`)},"annotationsToMarkdown"),Vn=Object.defineProperty({__proto__:null,annotationsToMarkdown:Ct,captureAccessibility:dn,captureComputedStyles:wt,captureElementScreenshot:un,cleanCssClasses:rn,deepElementFromPoint:_e,detectFrameworkComponent:pn,generateSelector:nn,getElementBoundingBoxes:gn,getElementLabel:Tt,getElementsInRect:mn,getFullDomPath:an,getNearbyElements:sn,getNearbyText:ln,getParentElement:en,getSelectedText:cn,getViewportRect:st,isElementFixed:tn,pierceElementFromPoint:rt},Symbol.toStringTag,{value:"Module"});var Yn=Object.defineProperty,ue=ae((e,t)=>Yn(e,"name",{value:t,configurable:!0}),"r$1");const Xn=["id^='__vdt_'","class*='__vdt_'"],xt=Xn.flatMap(e=>[`:not([${e}])`,`:not([${e}] *)`]).join(""),$t="__vdt_freeze_styles",ht="__vdt_freeze_state",ce=1e3,Un=ue(()=>{if(globalThis.window===void 0)return{frozen:!1,frozenRAFQueue:[],frozenTimeoutQueue:[],installed:!0,origRAF:ue(()=>0,"origRAF"),origSetInterval:ue((()=>0),"origSetInterval"),origSetTimeout:ue((()=>0),"origSetTimeout"),pausedAnimations:[]};const e=globalThis;return e[ht]||(e[ht]={frozen:!1,frozenRAFQueue:[],frozenTimeoutQueue:[],installed:!1,origRAF:null,origSetInterval:null,origSetTimeout:null,pausedAnimations:[]}),e[ht]},"getState"),E=Un();globalThis.window!==void 0&&!E.installed&&(E.origSetTimeout=globalThis.setTimeout.bind(globalThis),E.origSetInterval=globalThis.setInterval.bind(globalThis),E.origRAF=globalThis.requestAnimationFrame.bind(globalThis),globalThis.setTimeout=(e,t,...n)=>typeof e=="string"?E.origSetTimeout(e,t):E.origSetTimeout((...o)=>{E.frozen?E.frozenTimeoutQueue.length<ce?E.frozenTimeoutQueue.push(()=>e(...o)):E.frozenTimeoutQueue.length===ce&&(E.frozenTimeoutQueue.push(()=>{}),console.warn(`[dev-toolbar] frozenTimeoutQueue exceeded ${ce} entries — further callbacks are being dropped.`)):e(...o)},t,...n),globalThis.setInterval=(e,t,...n)=>typeof e=="string"?E.origSetInterval(e,t):E.origSetInterval((...o)=>{E.frozen||e(...o)},t,...n),globalThis.requestAnimationFrame=e=>E.origRAF(t=>{E.frozen?E.frozenRAFQueue.length<ce?E.frozenRAFQueue.push(e):E.frozenRAFQueue.length===ce&&(E.frozenRAFQueue.push(()=>{}),console.warn(`[dev-toolbar] frozenRAFQueue exceeded ${ce} entries — further callbacks are being dropped.`)):e(t)}),E.installed=!0);const xn=E.origSetTimeout,Qn=ue(()=>E.frozen,"isFrozen"),Kn=ue(()=>{if(typeof document>"u"||E.frozen)return;E.frozen=!0,E.frozenTimeoutQueue=[],E.frozenRAFQueue=[];let e=document.getElementById($t);e||(e=document.createElement("style"),e.id=$t),e.textContent=`
         *${xt},
         *${xt}::before,
         *${xt}::after {

package/dist/index.d.ts

@@ -1,54 +1,11 @@
 import { D as DevToolbarApp, T as ToolbarSettings } from "./packem_shared/app.d-SmKEDxsI.js";
 export { A as AppView, b as DEFAULT_TOOLBAR_SETTINGS, a as DevToolbarAppState, F as FrameState, N as NotificationLevel, P as PositionAnchor, S as ServerFunctions, c as ServerHelpers, d as ToolbarAppEventTarget, e as ToolbarPlacement } from "./packem_shared/app.d-SmKEDxsI.js";
-import { T as TimelineEvent, D as DevToolbarHook, C as ClientFunctions, a as ClientRPCContext, S as ServerFunctions, b as ServerRPCContext, c as TimelineGroup } from "./packem_shared/global-api.d-BLfn-OUA.js";
-export { A as AccessibilityInfo, d as Annotation, e as AnnotationIntent, f as AnnotationSeverity, g as AnnotationStatus, B as BoundingBox, h as CreateAnnotationData, i as DEFAULT_TIMELINE_GROUPS, F as FrameworkContext, H as HookEvents, j as ThreadMessage, k as TimelineEventLevel, U as UpdateAnnotationData, V as VisulimaDevTools } from "./packem_shared/global-api.d-BLfn-OUA.js";
+import { T as TimelineEvent, D as DevToolbarHook, C as ClientFunctions, a as ClientRPCContext, S as ServerFunctions, b as ServerRPCContext, c as TimelineGroup } from "./packem_shared/global-api.d-DG2WYakl.js";
+export { A as AccessibilityInfo, d as Annotation, e as AnnotationIntent, f as AnnotationSeverity, g as AnnotationStatus, B as BoundingBox, h as CreateAnnotationData, i as DEFAULT_TIMELINE_GROUPS, F as FrameworkContext, H as HookEvents, j as ThreadMessage, k as TimelineEventLevel, U as UpdateAnnotationData, V as VisulimaDevTools } from "./packem_shared/global-api.d-DG2WYakl.js";
 import { ViteDevServer } from 'vite';
 export { DevToolbar } from "./toolbar/index.js";
 import 'preact';
 /**
-* Message channel interface for bidirectional communication
-*/
-interface MessageChannel<TEvents extends Record<string, (...args: any[]) => void>> {
-  /**
-  * Unsubscribe from an event
-  * @param event Event name
-  * @param handler Optional specific handler to remove
-  */
-  off: <K extends keyof TEvents>(event: K, handler?: TEvents[K]) => void;
-  /**
-  * Subscribe to an event
-  * @param event Event name
-  * @param handler Event handler
-  * @returns Unsubscribe function
-  */
-  on: <K extends keyof TEvents>(event: K, handler: TEvents[K]) => () => void;
-  /**
-  * Subscribe to an event once
-  * @param event Event name
-  * @param handler Event handler
-  */
-  once: <K extends keyof TEvents>(event: K, handler: TEvents[K]) => void;
-  /**
-  * Send a message/event
-  * @param event Event name
-  * @param data Event data
-  */
-  send: <K extends keyof TEvents>(event: K, ...args: Parameters<TEvents[K]>) => void;
-}
-/**
-* Channel factory function
-*/
-type ChannelFactory<TEvents extends Record<string, (...args: any[]) => void>> = () => MessageChannel<TEvents>;
-/**
-* Factory result providing a method to instantiate named message channels.
-*/
-interface MessageChannelContext<TEvents extends Record<string, (...args: any[]) => void>> {
-  /**
-  * Creates and returns a new channel instance.
-  */
-  createChannel: () => MessageChannel<TEvents>;
-}
-/**
 * Creates a dev toolbar hook instance.
 * @param onRegisterApp Callback when app is registered.
 * @param onTimelineEvent Callback when timeline event is added.
@@ -125,6 +82,49 @@ declare class TimelineStore {
 */
 declare const getTimelineStore: () => TimelineStore;
 /**
+* Message channel interface for bidirectional communication
+*/
+interface MessageChannel<TEvents extends Record<string, (...args: any[]) => void>> {
+  /**
+  * Unsubscribe from an event
+  * @param event Event name
+  * @param handler Optional specific handler to remove
+  */
+  off: <K extends keyof TEvents>(event: K, handler?: TEvents[K]) => void;
+  /**
+  * Subscribe to an event
+  * @param event Event name
+  * @param handler Event handler
+  * @returns Unsubscribe function
+  */
+  on: <K extends keyof TEvents>(event: K, handler: TEvents[K]) => () => void;
+  /**
+  * Subscribe to an event once
+  * @param event Event name
+  * @param handler Event handler
+  */
+  once: <K extends keyof TEvents>(event: K, handler: TEvents[K]) => void;
+  /**
+  * Send a message/event
+  * @param event Event name
+  * @param data Event data
+  */
+  send: <K extends keyof TEvents>(event: K, ...args: Parameters<TEvents[K]>) => void;
+}
+/**
+* Channel factory function
+*/
+type ChannelFactory<TEvents extends Record<string, (...args: any[]) => void>> = () => MessageChannel<TEvents>;
+/**
+* Factory result providing a method to instantiate named message channels.
+*/
+interface MessageChannelContext<TEvents extends Record<string, (...args: any[]) => void>> {
+  /**
+  * Creates and returns a new channel instance.
+  */
+  createChannel: () => MessageChannel<TEvents>;
+}
+/**
 * Loads settings from localStorage, merging with defaults.
 * @returns Toolbar settings.
 */

package/dist/toolbar/index.d.ts

@@ -1,5 +1,5 @@
 import { D as DevToolbarApp, a as DevToolbarAppState } from "../packem_shared/app.d-SmKEDxsI.js";
-import "../packem_shared/global-api.d-BLfn-OUA.js";
+import "../packem_shared/global-api.d-DG2WYakl.js";
 import 'vite';
 import 'preact';
 /**

package/dist/vite-plugin.d.ts

@@ -1,6 +1,6 @@
 import { Plugin } from 'vite';
 import { D as DevToolbarApp, S as ServerFunctions } from "./packem_shared/app.d-SmKEDxsI.js";
-import "./packem_shared/global-api.d-BLfn-OUA.js";
+import "./packem_shared/global-api.d-DG2WYakl.js";
 import '@babel/generator';
 import 'preact';
 interface InjectSourceIgnore {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@visulima/dev-toolbar",
-  "version": "1.0.0-alpha.14",
+  "version": "1.0.0-alpha.16",
   "description": "Devtools is a set of tools for building advanced devtools for your application",
   "keywords": [
     "dev-toolbar",
@@ -10,6 +10,11 @@
   "bugs": {
     "url": "https://github.com/visulima/visulima/issues"
   },
+  "license": "MIT",
+  "author": {
+    "name": "Daniel Bannert",
+    "email": "d.bannert@anolilab.de"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/visulima/visulima.git",
@@ -25,13 +30,17 @@
       "url": "https://anolilab.com/support"
     }
   ],
-  "license": "MIT",
-  "author": {
-    "name": "Daniel Bannert",
-    "email": "d.bannert@anolilab.de"
+  "bin": {
+    "visulima-dev-toolbar-mcp": "./bin/mcp.js"
   },
-  "sideEffects": false,
+  "files": [
+    "bin",
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
   "type": "module",
+  "sideEffects": false,
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -103,18 +112,13 @@
     },
     "./package.json": "./package.json"
   },
-  "bin": {
-    "visulima-dev-toolbar-mcp": "./bin/mcp.js"
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
   },
-  "files": [
-    "bin",
-    "dist",
-    "README.md",
-    "CHANGELOG.md"
-  ],
   "dependencies": {
     "@babel/generator": "^7.29.1",
-    "@babel/parser": "7.29.2",
+    "@babel/parser": "7.29.3",
     "@babel/traverse": "^7.29.0",
     "@floating-ui/dom": "^1.7.6",
     "launch-editor": "2.13.2",
@@ -124,7 +128,7 @@
     "@modelcontextprotocol/sdk": "^1.0.0",
     "axe-core": "4.11.4",
     "vite": "^6 || ^7 || ^8",
-    "zod": "^3.0.0"
+    "zod": "^3.25.0 || ^4.0.0"
   },
   "peerDependenciesMeta": {
     "@modelcontextprotocol/sdk": {
@@ -139,9 +143,5 @@
   },
   "engines": {
     "node": "^22.14.0 || >=24.10.0"
-  },
-  "publishConfig": {
-    "access": "public",
-    "provenance": true
   }
 }

package/dist/packem_shared/{global-api.d-BLfn-OUA.d.ts → global-api.d-DG2WYakl.d.ts}

@@ -1,162 +1,6 @@
 import { D as DevToolbarApp, T as ToolbarSettings } from "./app.d-SmKEDxsI.js";
 import { ViteDevServer } from 'vite';
 /**
-* Annotation intent — describes what the user wants to communicate.
-*/
-type AnnotationIntent = "approve" | "change" | "fix" | "question";
-/**
-* Annotation severity — how urgent or important the annotation is.
-*/
-type AnnotationSeverity = "blocking" | "important" | "suggestion";
-/**
-* Annotation status — lifecycle state.
-*/
-type AnnotationStatus = "acknowledged" | "dismissed" | "pending" | "resolved";
-/**
-* A single message in a conversation thread attached to an annotation.
-*/
-interface ThreadMessage {
-  /** Message text */
-  content: string;
-  /** Unique message identifier */
-  id?: string;
-  /** Who wrote it — e.g. "human", "agent", or a specific agent name */
-  role: string;
-  /** ISO 8601 timestamp */
-  timestamp: string;
-}
-/**
-* Bounding box of the annotated element relative to the viewport.
-*/
-interface BoundingBox {
-  height: number;
-  width: number;
-  x: number;
-  y: number;
-}
-/**
-* Detected framework component information.
-*/
-interface FrameworkContext {
-  /** Component name */
-  componentName?: string;
-  /** Full component stack (e.g. ["App", "Layout", "Header", "Button"]) */
-  componentStack?: string[];
-  /** Additional framework-specific data (e.g. props) */
-  data?: Record<string, unknown>;
-  /** Framework identifier (react, vue, svelte, etc.) */
-  framework: string;
-  /** Source file path */
-  sourceFile?: string;
-  /** Source line number */
-  sourceLine?: number;
-}
-/**
-* Captured accessibility attributes for an element.
-*/
-interface AccessibilityInfo {
-  /** aria-describedby content */
-  ariaDescribedBy?: string;
-  /** aria-label value */
-  ariaLabel?: string;
-  /** Whether the element is focusable */
-  focusable: boolean;
-  /** ARIA role (explicit or implicit) */
-  role?: string;
-  /** tabindex value */
-  tabindex?: number;
-}
-/**
-* A visual annotation placed on a page element during development.
-* Stored in `.devtoolbar/annotations.json`.
-*/
-interface Annotation {
-  /** Captured accessibility attributes */
-  accessibility?: AccessibilityInfo;
-  /** Element bounding box at annotation time */
-  boundingBox?: BoundingBox;
-  /** User feedback / description */
-  comment: string;
-  /** Key computed CSS properties for forensic context */
-  computedStyles?: string;
-  /** ISO 8601 creation timestamp */
-  createdAt: string;
-  /** CSS classes on the annotated element (module hashes cleaned) */
-  cssClasses?: string;
-  /** Bounding boxes for multi-select annotations */
-  elementBoundingBoxes?: BoundingBox[];
-  /** Human-readable element label (e.g. 'button "Submit"') */
-  elementLabel?: string;
-  /** CSS selector path to the element */
-  elementPath?: string;
-  /** HTML tag name of the annotated element */
-  elementTag: string;
-  /** Detected framework component context */
-  frameworkContext?: FrameworkContext;
-  /** Full DOM ancestry path (e.g. "body > main > article > p") */
-  fullPath?: string;
-  /** Unique identifier (crypto.randomUUID) */
-  id: string;
-  /** What the user wants — fix, change, question, or approve */
-  intent: AnnotationIntent;
-  /** Whether the element has fixed/sticky positioning */
-  isFixed?: boolean;
-  /** Whether this is a multi-select (drag) annotation */
-  isMultiSelect?: boolean;
-  /** Sibling elements for spatial context */
-  nearbyElements?: string;
-  /** Text near the annotated element for additional context */
-  nearbyText?: string;
-  /** ISO 8601 resolution timestamp */
-  resolvedAt?: string;
-  /** Who resolved it — "human" or "agent" (or a specific agent name) */
-  resolvedBy?: string;
-  /** Path to screenshot file relative to .devtoolbar/ (e.g. "screenshots/&lt;id>.png") */
-  screenshot?: string;
-  /** Text the user had selected when annotating */
-  selectedText?: string;
-  /** Severity level */
-  severity: AnnotationSeverity;
-  /** Source file location from data-vdt-source (file:line:col) */
-  source?: string;
-  /** Lifecycle status */
-  status: AnnotationStatus;
-  /** Conversation thread (human ↔ AI agent) */
-  thread?: ThreadMessage[];
-  /** ISO 8601 last-updated timestamp */
-  updatedAt: string;
-  /** Page URL where the annotation was created */
-  url: string;
-  /** Click X as percentage of viewport width (0-100) — survives resize */
-  x: number;
-  /**
-  * Click Y as absolute page position (pixels from document top) — survives scroll.
-  *  For fixed/sticky elements, Y is viewport-relative instead.
-  */
-  y: number;
-}
-/**
-* Data required to create a new annotation (server-generated fields omitted).
-*/
-type CreateAnnotationData = Omit<Annotation, "createdAt" | "id" | "resolvedAt" | "resolvedBy" | "status" | "thread" | "updatedAt">;
-/**
-* Fields that can be updated on an existing annotation.
-*/
-interface UpdateAnnotationData {
-  /** Updated comment text */
-  comment?: string;
-  /** Updated intent */
-  intent?: AnnotationIntent;
-  /** Who resolved the annotation */
-  resolvedBy?: string;
-  /** Updated severity */
-  severity?: AnnotationSeverity;
-  /** New status */
-  status?: AnnotationStatus;
-  /** Append a thread message */
-  threadMessage?: ThreadMessage;
-}
-/**
 * Severity levels for timeline events.
 */
 type TimelineEventLevel = "info" | "warning" | "error";
@@ -328,6 +172,162 @@ interface TailwindConfigResult {
   version: "v3" | "v4" | "unknown";
 }
 /**
+* Annotation intent — describes what the user wants to communicate.
+*/
+type AnnotationIntent = "approve" | "change" | "fix" | "question";
+/**
+* Annotation severity — how urgent or important the annotation is.
+*/
+type AnnotationSeverity = "blocking" | "important" | "suggestion";
+/**
+* Annotation status — lifecycle state.
+*/
+type AnnotationStatus = "acknowledged" | "dismissed" | "pending" | "resolved";
+/**
+* A single message in a conversation thread attached to an annotation.
+*/
+interface ThreadMessage {
+  /** Message text */
+  content: string;
+  /** Unique message identifier */
+  id?: string;
+  /** Who wrote it — e.g. "human", "agent", or a specific agent name */
+  role: string;
+  /** ISO 8601 timestamp */
+  timestamp: string;
+}
+/**
+* Bounding box of the annotated element relative to the viewport.
+*/
+interface BoundingBox {
+  height: number;
+  width: number;
+  x: number;
+  y: number;
+}
+/**
+* Detected framework component information.
+*/
+interface FrameworkContext {
+  /** Component name */
+  componentName?: string;
+  /** Full component stack (e.g. ["App", "Layout", "Header", "Button"]) */
+  componentStack?: string[];
+  /** Additional framework-specific data (e.g. props) */
+  data?: Record<string, unknown>;
+  /** Framework identifier (react, vue, svelte, etc.) */
+  framework: string;
+  /** Source file path */
+  sourceFile?: string;
+  /** Source line number */
+  sourceLine?: number;
+}
+/**
+* Captured accessibility attributes for an element.
+*/
+interface AccessibilityInfo {
+  /** aria-describedby content */
+  ariaDescribedBy?: string;
+  /** aria-label value */
+  ariaLabel?: string;
+  /** Whether the element is focusable */
+  focusable: boolean;
+  /** ARIA role (explicit or implicit) */
+  role?: string;
+  /** tabindex value */
+  tabindex?: number;
+}
+/**
+* A visual annotation placed on a page element during development.
+* Stored in `.devtoolbar/annotations.json`.
+*/
+interface Annotation {
+  /** Captured accessibility attributes */
+  accessibility?: AccessibilityInfo;
+  /** Element bounding box at annotation time */
+  boundingBox?: BoundingBox;
+  /** User feedback / description */
+  comment: string;
+  /** Key computed CSS properties for forensic context */
+  computedStyles?: string;
+  /** ISO 8601 creation timestamp */
+  createdAt: string;
+  /** CSS classes on the annotated element (module hashes cleaned) */
+  cssClasses?: string;
+  /** Bounding boxes for multi-select annotations */
+  elementBoundingBoxes?: BoundingBox[];
+  /** Human-readable element label (e.g. 'button "Submit"') */
+  elementLabel?: string;
+  /** CSS selector path to the element */
+  elementPath?: string;
+  /** HTML tag name of the annotated element */
+  elementTag: string;
+  /** Detected framework component context */
+  frameworkContext?: FrameworkContext;
+  /** Full DOM ancestry path (e.g. "body > main > article > p") */
+  fullPath?: string;
+  /** Unique identifier (crypto.randomUUID) */
+  id: string;
+  /** What the user wants — fix, change, question, or approve */
+  intent: AnnotationIntent;
+  /** Whether the element has fixed/sticky positioning */
+  isFixed?: boolean;
+  /** Whether this is a multi-select (drag) annotation */
+  isMultiSelect?: boolean;
+  /** Sibling elements for spatial context */
+  nearbyElements?: string;
+  /** Text near the annotated element for additional context */
+  nearbyText?: string;
+  /** ISO 8601 resolution timestamp */
+  resolvedAt?: string;
+  /** Who resolved it — "human" or "agent" (or a specific agent name) */
+  resolvedBy?: string;
+  /** Path to screenshot file relative to .devtoolbar/ (e.g. "screenshots/&lt;id>.png") */
+  screenshot?: string;
+  /** Text the user had selected when annotating */
+  selectedText?: string;
+  /** Severity level */
+  severity: AnnotationSeverity;
+  /** Source file location from data-vdt-source (file:line:col) */
+  source?: string;
+  /** Lifecycle status */
+  status: AnnotationStatus;
+  /** Conversation thread (human ↔ AI agent) */
+  thread?: ThreadMessage[];
+  /** ISO 8601 last-updated timestamp */
+  updatedAt: string;
+  /** Page URL where the annotation was created */
+  url: string;
+  /** Click X as percentage of viewport width (0-100) — survives resize */
+  x: number;
+  /**
+  * Click Y as absolute page position (pixels from document top) — survives scroll.
+  *  For fixed/sticky elements, Y is viewport-relative instead.
+  */
+  y: number;
+}
+/**
+* Data required to create a new annotation (server-generated fields omitted).
+*/
+type CreateAnnotationData = Omit<Annotation, "createdAt" | "id" | "resolvedAt" | "resolvedBy" | "status" | "thread" | "updatedAt">;
+/**
+* Fields that can be updated on an existing annotation.
+*/
+interface UpdateAnnotationData {
+  /** Updated comment text */
+  comment?: string;
+  /** Updated intent */
+  intent?: AnnotationIntent;
+  /** Who resolved the annotation */
+  resolvedBy?: string;
+  /** Updated severity */
+  severity?: AnnotationSeverity;
+  /** New status */
+  status?: AnnotationStatus;
+  /** Append a thread message */
+  threadMessage?: ThreadMessage;
+}
+/**
 * Server-side RPC functions
 * These can be called from the client
 */