@visulima/dev-toolbar 1.0.0-alpha.13 → 1.0.0-alpha.15

package/dist/packem_shared/global-api.d-DG2WYakl.d.ts

@@ -0,0 +1,547 @@
+import { D as DevToolbarApp, T as ToolbarSettings } from "./app.d-SmKEDxsI.js";
+import { ViteDevServer } from 'vite';
+/**
+* Severity levels for timeline events.
+*/
+type TimelineEventLevel = "info" | "warning" | "error";
+/**
+* A single captured event displayed in the timeline panel.
+*/
+interface TimelineEvent {
+  /**
+  * Optional event data
+  */
+  data?: Record<string, any>;
+  /**
+  * Optional duration (milliseconds)
+  */
+  duration?: number;
+  /**
+  * Unique event ID
+  */
+  id: string;
+  /**
+  * Event level
+  */
+  level?: TimelineEventLevel;
+  /**
+  * Optional subtitle
+  */
+  subtitle?: string;
+  /**
+  * Timestamp (milliseconds since epoch)
+  */
+  time: number;
+  /**
+  * Event title
+  */
+  title: string;
+}
+/**
+* A named group that holds related timeline events.
+*/
+interface TimelineGroup {
+  /**
+  * Group color (hex or CSS color)
+  */
+  color?: string;
+  /**
+  * Events in this group
+  */
+  events: TimelineEvent[];
+  /**
+  * Group ID
+  */
+  id: string;
+  /**
+  * Group label
+  */
+  label: string;
+}
+/**
+* Default timeline groups
+*/
+declare const DEFAULT_TIMELINE_GROUPS: ReadonlyArray<TimelineGroup>;
+/**
+* Hook event definitions
+*/
+interface HookEvents {
+  [key: string]: (...args: any[]) => void;
+  /**
+  * 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:close": () => void;
+  /**
+  * DevTools initialized.
+  */
+  "devtools:init": () => void;
+  /**
+  * DevTools opened.
+  * @param appId ID of the opened app.
+  */
+  "devtools:open": (appId: string) => void;
+  /**
+  * Timeline event added.
+  * @param event Timeline event.
+  */
+  "timeline:event": (event: TimelineEvent) => void;
+}
+/**
+* Dev toolbar hook interface.
+* Exposed as window.__DEV_TOOLBAR_HOOK__
+*/
+interface DevToolbarHook {
+  /**
+  * Adds a timeline event.
+  * @param groupId Timeline group ID.
+  * @param event Timeline event.
+  */
+  addTimelineEvent: (groupId: string, event: TimelineEvent) => void;
+  /**
+  * Emits an event.
+  * @param event Event name.
+  * @param args Event arguments.
+  */
+  emit: <T extends keyof HookEvents>(event: T, ...args: Parameters<HookEvents[T]>) => void;
+  /**
+  * 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;
+  /**
+  * 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;
+  /**
+  * Subscribes to an event once.
+  * @param event Event name.
+  * @param handler Event handler.
+  */
+  once: <T extends keyof HookEvents>(event: T, handler: HookEvents[T]) => void;
+  /**
+  * Registers a custom app.
+  * @param app App definition.
+  */
+  registerApp: (app: DevToolbarApp) => void;
+}
+/**
+* Global hook declaration
+*/
+declare global {
+  interface Window {
+    /**
+    * Dev toolbar hook for library integrations.
+    */
+    __DEV_TOOLBAR_HOOK__?: DevToolbarHook;
+  }
+}
+interface StaticAsset {
+  /** Last-modified timestamp (ms since epoch) */
+  mtime: number;
+  /** Public URL path (e.g. "/images/logo.png") */
+  publicPath: string;
+  /** File size in bytes */
+  size: number;
+  /** Asset type category */
+  type: "audio" | "font" | "image" | "other" | "text" | "video";
+}
+interface SerializableModuleNode {
+  id: string;
+  importerCount: number;
+  importerUrls: string[];
+  url: string;
+}
+interface TailwindConfigResult {
+  /** CSS files that \@import tailwindcss */
+  cssFiles: string[];
+  /** User-defined \@theme overrides/extensions */
+  customTheme: Record<string, string>;
+  /** Full default Tailwind theme tokens */
+  defaultTheme: Record<string, string>;
+  /** Detected Tailwind version */
+  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
+*/
+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
+  */
+  getViteConfig: () => Promise<Record<string, any>>;
+  /**
+  * Open file in editor
+  * @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, 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
+*/
+interface ClientFunctions {
+  [key: string]: (...args: any[]) => void;
+  /**
+  * Notify client of config change
+  * @param config New Vite config
+  */
+  onConfigChange: (config: Record<string, unknown>) => void;
+  /**
+  * Notify client of HMR update
+  * @param payload HMR payload
+  */
+  onHMRUpdate: (payload: unknown) => void;
+  /**
+  * Notify client of module update
+  * @param module Updated module node
+  */
+  onModuleUpdate: (module: SerializableModuleNode) => void;
+}
+/**
+* RPC context for server-side
+*/
+interface ServerRPCContext {
+  /**
+  * Call a client function
+  * @param name Function name
+  * @param args Function arguments
+  */
+  callClient: <K extends keyof ClientFunctions>(name: K, ...args: Parameters<ClientFunctions[K]>) => void;
+  /**
+  * Register a server function
+  * @param name Function name
+  * @param fn Function implementation
+  */
+  registerFunction: <K extends keyof ServerFunctions>(name: K, function_: ServerFunctions[K]) => void;
+  /**
+  * Vite dev server instance
+  */
+  server: ViteDevServer;
+}
+/**
+* RPC context for client-side
+*/
+interface ClientRPCContext {
+  /**
+  * Call a server function
+  * @param name Function name
+  * @param args Function arguments
+  */
+  callServer: <K extends keyof ServerFunctions>(name: K, ...args: Parameters<ServerFunctions[K]>) => Promise<ReturnType<ServerFunctions[K]>>;
+  /**
+  * Register a client function
+  * @param name Function name
+  * @param function_ Function implementation
+  */
+  registerFunction: <K extends keyof ClientFunctions>(name: K, function_: ClientFunctions[K]) => void;
+}
+/**
+* Global DevTools API interface.
+* Exposed as window.__VISULIMA_DEVTOOLS__
+*/
+interface VisulimaDevTools {
+  /**
+  * Clears notification for an app.
+  */
+  clearNotification: (appId: string) => void;
+  /**
+  * Closes the currently active app.
+  */
+  closeApp: () => Promise<void>;
+  /**
+  * Gets the currently active app ID.
+  */
+  getActiveApp: () => string | undefined;
+  /**
+  * Gets all registered apps.
+  */
+  getApps: () => DevToolbarApp[];
+  /**
+  * Gets current toolbar settings.
+  */
+  getSettings: () => ToolbarSettings;
+  /**
+  * Hides the toolbar.
+  */
+  hide: () => void;
+  /**
+  * Hook instance for event subscriptions.
+  */
+  hook: DevToolbarHook;
+  /**
+  * Shows a notification for an app.
+  */
+  notify: (appId: string, level: "info" | "warning" | "error") => void;
+  /**
+  * Opens an app by ID.
+  */
+  openApp: (appId: string) => Promise<void>;
+  /**
+  * Registers a custom app.
+  */
+  registerApp: (app: DevToolbarApp) => void;
+  /**
+  * RPC client for calling server functions.
+  */
+  rpc: ServerFunctions;
+  /**
+  * 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;
+  /**
+  * Toggles toolbar visibility.
+  */
+  toggle: () => void;
+  /**
+  * Unregisters an app by ID.
+  */
+  unregisterApp: (appId: string) => void;
+  /**
+  * Updates toolbar settings.
+  */
+  updateSettings: (settings: Partial<ToolbarSettings>) => void;
+  /**
+  * Package version.
+  */
+  version: string;
+}
+/**
+* Global API declaration
+*/
+declare global {
+  interface Window {
+    /**
+    * Visulima DevTools global API.
+    */
+    __VISULIMA_DEVTOOLS__?: VisulimaDevTools;
+  }
+}
+export { AccessibilityInfo as A, BoundingBox as B, ClientFunctions as C, DevToolbarHook as D, FrameworkContext as F, HookEvents as H, ServerFunctions as S, TimelineEvent as T, UpdateAnnotationData as U, VisulimaDevTools as V, ClientRPCContext as a, ServerRPCContext as b, TimelineGroup as c, Annotation as d, AnnotationIntent as e, AnnotationSeverity as f, AnnotationStatus as g, CreateAnnotationData as h, DEFAULT_TIMELINE_GROUPS as i, ThreadMessage as j, TimelineEventLevel as k };