@visulima/dev-toolbar 1.0.0-alpha.1 → 1.0.0-alpha.10

package/dist/types/annotations.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Annotation intent — describes what the user wants to communicate.
+ */
+export type AnnotationIntent = "approve" | "change" | "fix" | "question";
+/**
+ * Annotation severity — how urgent or important the annotation is.
+ */
+export type AnnotationSeverity = "blocking" | "important" | "suggestion";
+/**
+ * Annotation status — lifecycle state.
+ */
+export type AnnotationStatus = "acknowledged" | "dismissed" | "pending" | "resolved";
+/**
+ * A single message in a conversation thread attached to an annotation.
+ */
+export 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.
+ */
+export interface BoundingBox {
+    height: number;
+    width: number;
+    x: number;
+    y: number;
+}
+/**
+ * Detected framework component information.
+ */
+export 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.
+ */
+export 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`.
+ */
+export 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).
+ */
+export type CreateAnnotationData = Omit<Annotation, "createdAt" | "id" | "resolvedAt" | "resolvedBy" | "status" | "thread" | "updatedAt">;
+/**
+ * Fields that can be updated on an existing annotation.
+ */
+export 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;
+}

package/dist/types/app.d.ts

@@ -73,11 +73,10 @@ export interface DevToolbarApp {
      */
     beforeTogglingOff?: (canvas: ShadowRoot) => boolean | Promise<boolean>;
     /**
-     * Called when the app is unregistered / removed from the toolbar.
-     * Use this for final cleanup (event listeners, timers, subscriptions).
-     * @param canvas Shadow root of the app
+     * Preact component for rendering (alternative to init)
+     * If provided, this will be used instead of init
      */
-    destroy?: (canvas: ShadowRoot) => Promise<void> | void;
+    component?: ComponentType<AppComponentProps>;
     /**
      * When true, this app is automatically activated when the toolbar opens for
      * the first time (or when no other app has been activated yet).
@@ -86,17 +85,11 @@ export interface DevToolbarApp {
      */
     defaultOpen?: boolean;
     /**
-     * Preact component for rendering (alternative to init)
-     * If provided, this will be used instead of init
-     */
-    component?: ComponentType<AppComponentProps>;
-    /**
-     * Optional hover tooltip component — renders a compact live preview when the
-     * user hovers over this app's button in the toolbar pill.
-     * The component should be small (≤280px wide) and self-contained.
-     * If omitted, hovering shows the native title tooltip only.
+     * Called when the app is unregistered / removed from the toolbar.
+     * Use this for final cleanup (event listeners, timers, subscriptions).
+     * @param canvas Shadow root of the app
      */
-    tooltip?: ComponentType<AppTooltipProps>;
+    destroy?: (canvas: ShadowRoot) => Promise<void> | void;
     /**
      * Icon HTML string (SVG)
      */
@@ -116,6 +109,25 @@ export interface DevToolbarApp {
      * Display name of the app
      */
     name: string;
+    /**
+     * Action button callback — called when the button is activated (active: false → true).
+     * When present, clicking the toolbar button will NOT open a panel.
+     * Instead the button toggles its active state and calls onClick (activate)
+     * or onDeactivate (deactivate).
+     */
+    onClick?: () => Promise<void> | void;
+    /**
+     * Called when the action button is deactivated (active: true → false).
+     * Only meaningful when onClick is also provided.
+     */
+    onDeactivate?: () => Promise<void> | void;
+    /**
+     * Optional hover tooltip component — renders a compact live preview when the
+     * user hovers over this app's button in the toolbar pill.
+     * The component should be small (≤280px wide) and self-contained.
+     * If omitted, hovering shows the native title tooltip only.
+     */
+    tooltip?: ComponentType<AppTooltipProps>;
     /**
      * App rendering mode
      */

package/dist/types/global-api.d.ts

@@ -1,84 +1,79 @@
 import type { DevToolbarApp } from "./app.d.ts";
-import type { ToolbarSettings } from "./toolbar.d.ts";
 import type { DevToolbarHook } from "./hooks.d.ts";
 import type { ServerFunctions } from "./rpc.d.ts";
+import type { ToolbarSettings } from "./toolbar.d.ts";
 /**
- * Global DevTools API interface
+ * Global DevTools API interface.
  * Exposed as window.__VISULIMA_DEVTOOLS__
  */
-export interface VisulimaDevTools {
+interface VisulimaDevTools {
     /**
-     * Clear notification for an app
-     * @param appId App ID
+     * Clears notification for an app.
      */
     clearNotification: (appId: string) => void;
     /**
-     * Close the currently active app
+     * Closes the currently active app.
      */
     closeApp: () => Promise<void>;
     /**
-     * Get the currently active app ID
-     * @returns Active app ID or null
+     * Gets the currently active app ID.
      */
-    getActiveApp: () => string | null;
+    getActiveApp: () => string | undefined;
     /**
-     * Get all registered apps
-     * @returns Array of app definitions
+     * Gets all registered apps.
      */
     getApps: () => DevToolbarApp[];
     /**
-     * Get current toolbar settings
-     * @returns Toolbar settings
+     * Gets current toolbar settings.
      */
     getSettings: () => ToolbarSettings;
     /**
-     * Hide the toolbar
+     * Hides the toolbar.
      */
     hide: () => void;
     /**
-     * Hook instance for event subscriptions
+     * Hook instance for event subscriptions.
      */
     hook: DevToolbarHook;
     /**
-     * Show a notification for an app
-     * @param appId App ID
-     * @param level Notification level
+     * Shows a notification for an app.
      */
     notify: (appId: string, level: "info" | "warning" | "error") => void;
     /**
-     * Open an app
-     * @param appId App ID to open
+     * Opens an app by ID.
      */
     openApp: (appId: string) => Promise<void>;
     /**
-     * Register a custom app
-     * @param app App definition
+     * Registers a custom app.
      */
     registerApp: (app: DevToolbarApp) => void;
     /**
-     * RPC client for calling server functions
+     * RPC client for calling server functions.
      */
     rpc: ServerFunctions;
     /**
-     * Show the toolbar
+     * Directly sets the active state of an action button without invoking callbacks.
+     * Useful for deactivating a button from async work running outside the toolbar.
+     */
+    setAppActive: (appId: string, active: boolean) => void;
+    /**
+     * Shows the toolbar.
      */
     show: () => void;
     /**
-     * Toggle toolbar visibility
+     * Toggles toolbar visibility.
      */
     toggle: () => void;
     /**
-     * Unregister an app
-     * @param appId App ID to unregister
+     * Unregisters an app by ID.
      */
     unregisterApp: (appId: string) => void;
     /**
-     * Update toolbar settings
-     * @param settings Partial settings to update
+     * Updates toolbar settings.
      */
     updateSettings: (settings: Partial<ToolbarSettings>) => void;
     /**
-     * Package version
+     * Package version.
      */
     version: string;
 }
@@ -88,8 +83,9 @@ export interface VisulimaDevTools {
 declare global {
     interface Window {
         /**
-         * Visulima DevTools global API
+         * Visulima DevTools global API.
          */
         __VISULIMA_DEVTOOLS__?: VisulimaDevTools;
     }
 }
+export type { VisulimaDevTools };

package/dist/types/hooks.d.ts

@@ -3,75 +3,72 @@ import type { TimelineEvent } from "./timeline.d.ts";
 /**
  * Hook event definitions
  */
-export interface HookEvents {
-    /**
-     * Extension point for custom events
-     */
+interface HookEvents {
     [key: string]: (...args: any[]) => void;
     /**
-     * App error occurred
-     * @param error Error object
-     * @param appId Optional app ID where error occurred
+     * App error occurred.
+     * @param error Error object.
+     * @param appId Optional app ID where error occurred.
      */
     "app:error": (error: Error, appId?: string) => void;
     /**
-     * DevTools closed
+     * DevTools closed.
      */
     "devtools:close": () => void;
     /**
-     * DevTools initialized
+     * DevTools initialized.
      */
     "devtools:init": () => void;
     /**
-     * DevTools opened
-     * @param appId ID of the opened app
+     * DevTools opened.
+     * @param appId ID of the opened app.
      */
     "devtools:open": (appId: string) => void;
     /**
-     * Timeline event added
-     * @param event Timeline event
+     * Timeline event added.
+     * @param event Timeline event.
      */
     "timeline:event": (event: TimelineEvent) => void;
 }
 /**
- * Dev toolbar hook interface
+ * Dev toolbar hook interface.
  * Exposed as window.__DEV_TOOLBAR_HOOK__
  */
-export interface DevToolbarHook {
+interface DevToolbarHook {
     /**
-     * Add a timeline event
-     * @param groupId Timeline group ID
-     * @param event Timeline event
+     * Adds a timeline event.
+     * @param groupId Timeline group ID.
+     * @param event Timeline event.
      */
     addTimelineEvent: (groupId: string, event: TimelineEvent) => void;
     /**
-     * Emit an event
-     * @param event Event name
-     * @param args Event arguments
+     * Emits an event.
+     * @param event Event name.
+     * @param args Event arguments.
      */
     emit: <T extends keyof HookEvents>(event: T, ...args: Parameters<HookEvents[T]>) => void;
     /**
-     * Unsubscribe from an event
-     * @param event Event name
-     * @param handler Optional specific handler to remove
+     * Unsubscribes from an event.
+     * @param event Event name.
+     * @param handler Optional specific handler to remove.
      */
     off: <T extends keyof HookEvents>(event: T, handler?: HookEvents[T]) => void;
     /**
-     * Subscribe to an event
-     * @param event Event name
-     * @param handler Event handler
-     * @returns Unsubscribe function
+     * Subscribes to an event.
+     * @param event Event name.
+     * @param handler Event handler.
+     * @returns Unsubscribe function.
      */
     on: <T extends keyof HookEvents>(event: T, handler: HookEvents[T]) => () => void;
     /**
-     * Subscribe to an event once
-     * @param event Event name
-     * @param handler Event handler
+     * Subscribes to an event once.
+     * @param event Event name.
+     * @param handler Event handler.
      */
     once: <T extends keyof HookEvents>(event: T, handler: HookEvents[T]) => void;
     /**
-     * Register a custom app
-     * @param app App definition
+     * Registers a custom app.
+     * @param app App definition.
      */
     registerApp: (app: DevToolbarApp) => void;
 }
@@ -81,8 +78,9 @@ export interface DevToolbarHook {
 declare global {
     interface Window {
         /**
-         * Dev toolbar hook for library integrations
+         * Dev toolbar hook for library integrations.
          */
         __DEV_TOOLBAR_HOOK__?: DevToolbarHook;
     }
 }
+export type { DevToolbarHook, HookEvents };

package/dist/types/index.d.ts

@@ -1,6 +1,7 @@
 /**
  * Public type exports
  */
+export type { AccessibilityInfo, Annotation, AnnotationIntent, AnnotationSeverity, AnnotationStatus, BoundingBox, CreateAnnotationData, FrameworkContext, ThreadMessage, UpdateAnnotationData, } from "./annotations.d.ts";
 export type { AppView, DevToolbarApp, DevToolbarAppState, ServerFunctions, ServerHelpers, ToolbarAppEventTarget } from "./app.d.ts";
 export type { VisulimaDevTools } from "./global-api.d.ts";
 export type { DevToolbarHook, HookEvents } from "./hooks.d.ts";

package/dist/types/messaging.d.ts

@@ -33,11 +33,11 @@ export interface MessageChannel<TEvents extends Record<string, (...args: any[])
  */
 export type ChannelFactory<TEvents extends Record<string, (...args: any[]) => void>> = () => MessageChannel<TEvents>;
 /**
- * Message channel context
+ * Factory result providing a method to instantiate named message channels.
  */
 export interface MessageChannelContext<TEvents extends Record<string, (...args: any[]) => void>> {
     /**
-     * Create a new channel instance
+     * Creates and returns a new channel instance.
      */
     createChannel: () => MessageChannel<TEvents>;
 }

package/dist/types/rpc.d.ts

@@ -1,5 +1,8 @@
 import type { ViteDevServer } from "vite";
+import type { StaticAsset } from "../rpc/functions/assets.d.ts";
 import type { SerializableModuleNode } from "../rpc/functions/module-graph.d.ts";
+import type { TailwindConfigResult } from "../rpc/functions/tailwind-config.d.ts";
+import type { Annotation, CreateAnnotationData, UpdateAnnotationData } from "./annotations.d.ts";
 /**
  * Server-side RPC functions
  * These can be called from the client
@@ -9,10 +12,37 @@ export interface ServerFunctions {
      * Extension point for custom server functions
      */
     [key: string]: (...args: any[]) => Promise<any>;
+    /**
+     * Create a new annotation
+     * @param data Annotation data (id, timestamps, status are generated server-side)
+     */
+    createAnnotation: (data: CreateAnnotationData) => Promise<Annotation>;
+    /**
+     * Delete an annotation and its screenshot
+     * @param id Annotation ID
+     */
+    deleteAnnotation: (id: string) => Promise<boolean>;
+    /**
+     * Get all annotations
+     */
+    getAnnotations: () => Promise<Annotation[]>;
     /**
      * Get module dependency graph
      */
     getModuleGraph: () => Promise<SerializableModuleNode[]>;
+    /**
+     * Get a screenshot as a base64 data URL
+     * @param annotationId Annotation ID
+     */
+    getScreenshot: (annotationId: string) => Promise<string | null>;
+    /**
+     * Get all static assets from the public directory
+     */
+    getStaticAssets: () => Promise<StaticAsset[]>;
+    /**
+     * Get full Tailwind CSS theme (default + user overrides)
+     */
+    getTailwindConfig: () => Promise<TailwindConfigResult>;
     /**
      * Get Vite configuration
      */
@@ -22,33 +52,44 @@ export interface ServerFunctions {
      * @param file File path
      * @param line Line number (1-based)
      * @param column Column number (1-based)
+     * @param editor Editor override (e.g. "code", "webstorm") — empty string means auto-detect
      */
-    openInEditor: (file: string, line?: number, column?: number) => Promise<void>;
+    openInEditor: (file: string, line?: number, column?: number, editor?: string) => Promise<void>;
     /**
      * Read file contents
      * @param path File path
      */
     readFile: (path: string) => Promise<string>;
+    /**
+     * Save a screenshot for an annotation
+     * @param annotationId Annotation ID
+     * @param dataUrl Base64 data URL (PNG, JPEG, WebP, or SVG)
+     * @returns Relative path within .devtoolbar/
+     */
+    saveScreenshot: (annotationId: string, dataUrl: string) => Promise<string>;
+    /**
+     * Update an existing annotation
+     * @param id Annotation ID
+     * @param data Fields to update
+     */
+    updateAnnotation: (id: string, data: UpdateAnnotationData) => Promise<Annotation | null>;
 }
 /**
  * Client-side RPC functions
  * These can be called from the server
  */
 export interface ClientFunctions {
-    /**
-     * Extension point for custom client functions
-     */
     [key: string]: (...args: any[]) => void;
     /**
      * Notify client of config change
      * @param config New Vite config
      */
-    onConfigChange: (config: Record<string, any>) => void;
+    onConfigChange: (config: Record<string, unknown>) => void;
     /**
      * Notify client of HMR update
      * @param payload HMR payload
      */
-    onHMRUpdate: (payload: any) => void;
+    onHMRUpdate: (payload: unknown) => void;
     /**
      * Notify client of module update
      * @param module Updated module node
@@ -89,7 +130,8 @@ export interface ClientRPCContext {
     /**
      * Register a client function
      * @param name Function name
-     * @param fn Function implementation
+     * @param function_ Function implementation
      */
     registerFunction: <K extends keyof ClientFunctions>(name: K, function_: ClientFunctions[K]) => void;
 }
+export { type StaticAsset } from "../rpc/functions/assets.d.ts";

package/dist/types/timeline.d.ts

@@ -1,9 +1,9 @@
 /**
- * Timeline event level
+ * Severity levels for timeline events.
  */
 export type TimelineEventLevel = "info" | "warning" | "error";
 /**
- * Timeline event
+ * A single captured event displayed in the timeline panel.
  */
 export interface TimelineEvent {
     /**
@@ -36,7 +36,7 @@ export interface TimelineEvent {
     title: string;
 }
 /**
- * Timeline group
+ * A named group that holds related timeline events.
  */
 export interface TimelineGroup {
     /**

package/dist/types/toolbar.d.ts

@@ -34,7 +34,7 @@ export interface FrameState {
     top: number;
 }
 /**
- * Toolbar settings
+ * Configuration options controlling the toolbar's initial appearance.
  */
 export interface ToolbarSettings {
     /**

package/dist/ui/components/alert.d.ts

@@ -0,0 +1,19 @@
+import type { ComponentChildren, JSX } from "preact";
+type AlertVariant = "default" | "destructive" | "info" | "success" | "warning";
+interface AlertProps extends JSX.HTMLAttributes<HTMLDivElement> {
+    children?: ComponentChildren;
+    class?: string;
+    variant?: AlertVariant;
+}
+interface AlertTitleProps extends JSX.HTMLAttributes<HTMLHeadingElement> {
+    children?: ComponentChildren;
+    class?: string;
+}
+interface AlertDescriptionProps extends JSX.HTMLAttributes<HTMLDivElement> {
+    children?: ComponentChildren;
+    class?: string;
+}
+declare const Alert: ({ children, class: className, variant, ...rest }: AlertProps) => JSX.Element;
+declare const AlertTitle: ({ children, class: className, ...rest }: AlertTitleProps) => JSX.Element;
+declare const AlertDescription: ({ children, class: className, ...rest }: AlertDescriptionProps) => JSX.Element;
+export { Alert, AlertDescription, AlertTitle };

package/dist/ui/components/badge.d.ts

@@ -0,0 +1,9 @@
+import type { ComponentChildren, JSX } from "preact";
+type BadgeVariant = "default" | "destructive" | "info" | "outline" | "secondary" | "success" | "warning";
+interface BadgeProps extends JSX.HTMLAttributes<HTMLDivElement> {
+    children?: ComponentChildren;
+    class?: string;
+    variant?: BadgeVariant;
+}
+declare const Badge: ({ children, class: className, variant, ...rest }: BadgeProps) => JSX.Element;
+export default Badge;

package/dist/ui/components/button.d.ts

@@ -0,0 +1,11 @@
+import type { ComponentChildren, JSX } from "preact";
+type ButtonSize = "default" | "icon" | "lg" | "sm";
+type ButtonVariant = "default" | "destructive" | "ghost" | "link" | "outline" | "secondary";
+interface ButtonProps extends JSX.ButtonHTMLAttributes {
+    children?: ComponentChildren;
+    class?: string;
+    size?: ButtonSize;
+    variant?: ButtonVariant;
+}
+declare const Button: ({ children, class: className, size, type, variant, ...rest }: ButtonProps) => JSX.Element;
+export default Button;