@u-devtools/core 0.1.6 → 0.2.0

package/dist/index.d.ts

@@ -1,46 +1,209 @@
 import { PluginOption } from 'vite';
+import { z } from 'zod';
 
 /**
- * AppBridge provides a standardized way for plugins to communicate
- * between the application runtime (window) and the DevTools iframe.
+ * AppBridge - Typed communication bridge between App context (main window) and Client context (DevTools iframe).
+ *
+ * Communication: App ↔ Client via BroadcastChannel API
+ *
+ * Provides type-safe event-based communication with automatic state synchronization.
+ *
+ * @template Protocol - Type definition for events and their handlers
+ *
+ * @example
+ * ```typescript
+ * import { AppBridge } from '@u-devtools/core';
+ *
+ * // Define protocol for type-safe communication
+ * interface MyPluginProtocol {
+ *   'element-selected': (data: { id: string; html: string }) => void;
+ *   'toggle-inspector': (data: { state: boolean }) => void;
+ * }
+ *
+ * const typedBridge = new AppBridge<MyPluginProtocol>('my-plugin');
+ *
+ * // Send events (type-safe)
+ * typedBridge.send('element-selected', { id: 'el-1', html: '<div>...</div>' });
+ *
+ * // Listen to events (type-safe)
+ * typedBridge.on('toggle-inspector', ({ state }) => {
+ *   // state is automatically typed as { state: boolean }
+ *   console.log('Inspector toggled:', state);
+ * });
+ *
+ * // Create synced state
+ * const selectedElement = typedBridge.state<HTMLElement | null>('selectedElement', null);
+ * selectedElement.value = document.getElementById('my-element');
+ * ```
  */
-export declare class AppBridge {
+export declare class AppBridge<Protocol = Record<string, (...args: any[]) => any>> {
+    private transport;
     namespace: string;
+    displayName: string;
+    constructor(namespace: string);
+    send<K extends keyof Protocol>(event: K, ...args: Protocol[K] extends (...args: infer P) => any ? P : []): void;
+    on<K extends keyof Protocol>(event: K, cb: Protocol[K] extends (...args: any[]) => any ? (data: Parameters<Protocol[K]>[0]) => void : never): () => void;
+    request<RequestData, ResponseData>(requestEvent: string, requestData: RequestData, responseEvent: string, timeout?: number, responseFilter?: (request: RequestData, response: ResponseData) => boolean): Promise<ResponseData>;
+    close(): void;
+    state<T>(key: string, initialValue: T): SyncedState<T>;
+}
+
+/**
+ * Transport based on BroadcastChannel
+ * Used for communication between App (window) and Client (iframe)
+ * Does not support RPC (call), only events (send/on)
+ */
+export declare class BroadcastTransport extends Transport {
     private channel;
-    private listeners;
+    private messageHandler?;
+    private namespace;
     constructor(namespace: string);
     /**
-     * Отправить событие "на ту сторону".
+     * Extract values from Vue reactive objects (ref, computed, reactive)
+     */
+    private unwrapVueReactive;
+    /**
+     * Send event (not RPC)
      */
     send(event: string, data?: unknown): void;
     /**
-     * Слушать события "с той стороны".
+     * RPC calls are not supported in BroadcastChannel
+     */
+    call<T = unknown>(_method: string, _payload?: unknown): Promise<T>;
+    protected sendMessage(_type: string, _data: unknown): void;
+    protected subscribe(event: string, handler: (data: unknown) => void): () => void;
+    protected unsubscribe(event: string, handler: (data: unknown) => void): void;
+    dispose(): void;
+    /**
+     * Close channel (alias for dispose)
      */
-    on<T = unknown>(event: string, cb: (data: T) => void): () => void;
     close(): void;
 }
 
+/**
+ * Typed Event Bus for inter-plugin communication
+ */
+/**
+ * EventBus events interface.
+ * Plugins can extend this interface through module augmentation.
+ *
+ * @example
+ * ```typescript
+ * // In your plugin
+ * declare module '@u-devtools/core' {
+ *   interface BusEvents {
+ *     'my-plugin:custom-event': { data: string };
+ *   }
+ * }
+ * ```
+ */
+export declare interface BusEvents {
+    'plugin:mounted': {
+        name: string;
+    };
+    'plugin:unmounted': {
+        name: string;
+    };
+    navigate: {
+        path: string;
+    };
+    'settings:changed': {
+        key: string;
+        value: unknown;
+    };
+    'storage:changed': {
+        key: string;
+        value: unknown;
+    };
+    [key: string]: unknown;
+}
+
+/**
+ * Client API - Main API object provided to plugins in Client context.
+ * Provides access to all DevTools services: RPC, storage, settings, notifications, etc.
+ *
+ * Available in: Client context (Vue 3 iframe)
+ *
+ * @example
+ * ```typescript
+ * import type { PluginClientInstance } from '@u-devtools/core';
+ *
+ * const plugin: PluginClientInstance = {
+ *   name: 'My Plugin',
+ *   icon: 'Cube',
+ *
+ *   renderMain(container, api) {
+ *     // Use api.storage for plugin state
+ *     api.storage.set('lastView', 'list');
+ *     const lastView = api.storage.get('lastView', 'default');
+ *
+ *     // Use api.settings for user preferences
+ *     api.settings.set('fontSize', 16);
+ *     const fontSize = api.settings.get('fontSize', 14);
+ *
+ *     // Navigation
+ *     api.navigation.openPlugin('other-plugin');
+ *
+ *     // Event bus
+ *     api.bus.on('other-plugin:event', (data) => {
+ *       console.log('Received event:', data);
+ *     });
+ *     api.bus.emit('my-plugin:event', { data: 'value' });
+ *
+ *     // Async operations (use async IIFE for await)
+ *     (async () => {
+ *       // Use api.rpc to call server methods
+ *       const data = await api.rpc.call('my-plugin:getData');
+ *
+ *       // Notifications
+ *       api.notify('Data saved successfully', 'success');
+ *
+ *       // Clipboard
+ *       await api.clipboard.copy('text to copy');
+ *
+ *       // Dialog
+ *       const confirmed = await api.dialog.confirm({
+ *         title: 'Confirm',
+ *         message: 'Are you sure?',
+ *       });
+ *     })();
+ *
+ *     return () => {}; // Cleanup function
+ *   }
+ * };
+ * ```
+ */
 export declare interface ClientApi {
+    /** RPC client for calling server methods */
     rpc: RpcClientInterface;
+    /** Show a notification to the user */
     notify: (msg: string, type?: 'info' | 'error' | 'success') => void;
+    /** Storage API for plugin-specific persistent state (e.g., last opened file) */
     storage: StorageApi;
+    /** Settings API for user-configurable preferences (e.g., font size, theme) */
     settings: SettingsApi;
+    /** Keyboard shortcuts API */
     shortcuts: ShortcutApi;
+    /** Clipboard operations API */
     clipboard: ClipboardApi;
+    /** Event bus for plugin-to-plugin communication */
     bus: EventBusApi;
+    /** Dialog API for confirmations and prompts */
     dialog: DialogApi;
+    /** Navigation API for switching between plugins */
+    navigation: NavigationApi;
 }
 
 export declare interface ClipboardApi {
     /**
-     * Скопировать текст в буфер обмена.
-     * @param text Текст для копирования
-     * @param successMessage Сообщение об успехе (опционально)
+     * Copy text to clipboard.
+     * @param text Text to copy
+     * @param successMessage Success message (optional)
      */
     copy(text: string, successMessage?: string): Promise<void>;
     /**
-     * Прочитать текст из буфера обмена.
-     * @returns Текст из буфера или пустая строка при ошибке
+     * Read text from clipboard.
+     * @returns Text from clipboard or empty string on error
      */
     read(): Promise<string>;
 }
@@ -51,54 +214,83 @@ export declare class DevToolsControl {
     private channel;
     constructor();
     /**
-     * Открыть DevTools
+     * Open DevTools
      */
     open(): void;
     /**
-     * Закрыть DevTools
+     * Close DevTools
      */
     close(): void;
     /**
-     * Переключить состояние
+     * Toggle state
      */
     toggle(): void;
     /**
-     * Получить текущее состояние (асинхронно)
+     * Get current state (asynchronously)
      */
     isOpen(): Promise<boolean>;
     /**
-     * Подписаться на изменение состояния
+     * Subscribe to state changes
      */
     onStateChange(cb: (isOpen: boolean) => void): () => void;
     /**
-     * Переключить на плагин по имени
+     * Switch to plugin by name
      */
     switchPlugin(pluginName: string): void;
     /**
-     * Переключить таб внутри плагина по имени таба
+     * Switch tab within plugin by tab name
      */
     switchTab(pluginName: string, tabName: string): void;
     destroy(): void;
 }
 
+/**
+ * DevTools Plugin Definition - Server-side plugin configuration.
+ * Defines a plugin's structure and entry points for all three execution contexts.
+ *
+ * Created using definePlugin() helper from @u-devtools/kit/define-plugin.
+ *
+ * @example
+ * ```ts
+ * import { definePlugin } from '@u-devtools/kit/define-plugin';
+ *
+ * export default definePlugin({
+ *   name: 'My Plugin',
+ *   root: import.meta.url,
+ *   client: './client',
+ *   app: './app',
+ *   server: './server',
+ * });
+ * ```
+ */
 export declare interface DevToolsPlugin {
+    /** Display name of the plugin */
     name: string;
+    /** Absolute path to client.ts file (Client context) */
     clientPath?: string;
+    /** Absolute path to app.ts file (App context - main window) */
     appPath?: string;
+    /**
+     * Server-side setup function (Server context - Node.js).
+     * Called when plugin is loaded to register RPC handlers.
+     * @param rpc - RPC server interface for handling requests
+     * @param ctx - Server context with root path and Vite server instance
+     */
     setupServer?: (rpc: RpcServerInterface, ctx: ServerContext) => void;
+    /** Plugin metadata (name, version, description, etc.) */
     meta?: PluginMetadata;
     /**
-     * Optional Vite plugins to be added to the Vite config
-     * These plugins will be merged with the main DevTools plugin
+     * Optional Vite plugins to be merged with the main DevTools plugin.
+     * These plugins will be added to the Vite configuration.
      */
     vitePlugins?: (() => PluginOption | PluginOption[])[];
 }
 
 export declare interface DialogApi {
     /**
-     * Показать диалог подтверждения.
-     * @param options Опции диалога
-     * @returns Promise с результатом (true если подтверждено)
+     * Show a confirmation dialog.
+     * @param options Dialog options
+     * @returns Promise with result (true if confirmed)
      */
     confirm(options: {
         title: string;
@@ -107,9 +299,9 @@ export declare interface DialogApi {
         cancelText?: string;
     }): Promise<boolean>;
     /**
-     * Показать диалог ввода.
-     * @param options Опции диалога
-     * @returns Promise с введенным текстом или null если отменено
+     * Show an input dialog.
+     * @param options Dialog options
+     * @returns Promise with entered text or null if cancelled
      */
     prompt(options: {
         title: string;
@@ -120,26 +312,85 @@ export declare interface DialogApi {
 
 export declare interface EventBusApi {
     /**
-     * Отправить событие.
-     * @param event Имя события
-     * @param data Данные события
+     * Emit an event.
+     * @param event Event name
+     * @param data Event data
      */
     emit(event: string, data?: unknown): void;
     /**
-     * Подписаться на событие.
-     * @param event Имя события
-     * @param handler Обработчик события
-     * @returns Функция для отписки
+     * Subscribe to an event.
+     * @param event Event name
+     * @param handler Event handler
+     * @returns Function to unsubscribe
      */
     on(event: string, handler: (data: unknown) => void): () => void;
     /**
-     * Отписаться от события.
-     * @param event Имя события
-     * @param handler Обработчик события
+     * Unsubscribe from an event.
+     * @param event Event name
+     * @param handler Event handler
      */
     off(event: string, handler: (data: unknown) => void): void;
 }
 
+/**
+ * Menu item for the "General" section in ActivityBar.
+ *
+ * Allows plugins to add their actions to the general menu, even if the plugin
+ * itself is hidden from the main ActivityBar menu.
+ *
+ * @example
+ * ```ts
+ * const plugin: PluginClientInstance = {
+ *   name: 'Plugins',
+ *   icon: 'Squares2X2',
+ *   hideFromMenu: true,
+ *   generalMenuItems: [
+ *     {
+ *       label: 'Extensions',
+ *       icon: 'Squares2X2',
+ *       action: (api) => {
+ *         api.navigation.openPlugin('Plugins');
+ *       }
+ *     }
+ *   ]
+ * };
+ * ```
+ */
+export declare interface GeneralMenuItem {
+    /** Menu item label text */
+    label: string;
+    /** Heroicons icon name (e.g., 'Cube', 'MagnifyingGlass') */
+    icon: string;
+    /**
+     * Action callback when menu item is clicked.
+     * @param api - Client API for interacting with DevTools
+     */
+    action: (api: ClientApi) => void;
+}
+
+/**
+ * Transport based on Vite HMR (Hot Module Replacement)
+ * Used for communication between client (iframe) and server (Node.js)
+ */
+export declare class HmrTransport extends Transport {
+    private hot;
+    private responseHandler?;
+    private eventHandler?;
+    constructor(hot: {
+        send: (event: string, data: unknown) => void;
+        on: (event: string, handler: (data: unknown) => void) => void;
+        off?: (event: string, handler: (data: unknown) => void) => void;
+    });
+    /**
+     * Override on() for HMR, as subscription is already set up in constructor
+     */
+    on(event: string, fn: (data: unknown) => void): () => void;
+    protected sendMessage(type: string, data: unknown): void;
+    protected subscribe(_type: string, _handler: (data: unknown) => void): () => void;
+    protected unsubscribe(_type: string, _handler: (data: unknown) => void): void;
+    dispose(): void;
+}
+
 export declare interface InspectorEvent {
     type: 'element-selected';
     data: {
@@ -154,36 +405,41 @@ export declare interface InspectorEvent {
     };
 }
 
-export declare const OVERLAY_EVENT = "u-devtools:register-menu-item";
+export declare interface NavigationApi {
+    /**
+     * Switch active plugin
+     */
+    openPlugin(pluginName: string): void;
+}
 
 export declare interface OverlayContext {
     /**
-     * Открыть основное окно DevTools
+     * Open the main DevTools window
      */
     open: () => void;
     /**
-     * Закрыть основное окно DevTools
+     * Close the main DevTools window
      */
     close: () => void;
     /**
-     * Переключить состояние окна
+     * Toggle window state
      */
     toggle: () => void;
     /**
-     * Текущее состояние
+     * Current state
      */
     isOpen: boolean;
     /**
-     * Переключить на плагин по имени
+     * Switch to plugin by name
      */
     switchPlugin: (pluginName: string) => void;
     /**
-     * Переключить таб внутри плагина по имени таба
+     * Switch tab within plugin by tab name
      */
     switchTab: (pluginName: string, tabName: string) => void;
     /**
-     * Создать временный мост для отправки сообщения.
-     * Полезно, если у вас нет доступа к глобальному мосту плагина в данной области видимости.
+     * Create a temporary bridge for sending messages.
+     * Useful if you don't have access to the plugin's global bridge in this scope.
      */
     createBridge: (namespace: string) => AppBridge;
 }
@@ -196,7 +452,7 @@ export declare interface OverlayMenuItem {
     iconUrl?: string;
     order?: number;
     /**
-     * Обработчики событий (принимают контекст)
+     * Event handlers (receive context)
      */
     onClick?: (ctx: OverlayContext, event: MouseEvent) => void;
     onDoubleClick?: (ctx: OverlayContext, event: MouseEvent) => void;
@@ -211,21 +467,95 @@ export declare interface OverlayMenuItem {
     onBlur?: (ctx: OverlayContext, event: FocusEvent) => void;
 }
 
+/**
+ * Plugin Client Instance - Definition of a plugin's UI and behavior in Client context.
+ * This is the main export from a plugin's client.ts file.
+ *
+ * @example
+ * ```ts
+ * import type { PluginClientInstance } from '@u-devtools/core';
+ *
+ * const plugin: PluginClientInstance = {
+ *   name: 'My Plugin',
+ *   icon: 'Cube',
+ *   settings: { },
+ *   commands: [ ],
+ *   renderMain(container, api) {
+ *     // Render your plugin UI
+ *     return () => { };
+ *   }
+ * };
+ *
+ * export default plugin;
+ * ```
+ */
 export declare interface PluginClientInstance {
+    /** Display name shown in DevTools UI */
     name: string;
+    /** Heroicons icon name (e.g., 'Cube', 'MagnifyingGlass', 'WrenchScrewdriver') */
     icon: string;
+    /**
+     * Hide plugin from main ActivityBar menu.
+     * Plugin will still be accessible via navigation API or generalMenuItems.
+     */
+    hideFromMenu?: boolean;
+    /** Settings schema for user-configurable options */
     settings?: PluginSettingsSchema;
+    /** Commands accessible via Command Palette (Cmd+K / Ctrl+K) */
     commands?: PluginCommand[];
-    renderSidebar?: (el: HTMLElement, api: ClientApi) => UnmountFn;
-    renderMain?: (el: HTMLElement, api: ClientApi) => UnmountFn;
-    renderSettings?: (el: HTMLElement, api: ClientApi) => UnmountFn;
+    /**
+     * Menu items for the "General" section in ActivityBar.
+     * Allows plugins to add their actions to the general menu.
+     */
+    generalMenuItems?: GeneralMenuItem[];
+    /**
+     * Render sidebar panel (optional).
+     * @param el - Container element to render into
+     * @param api - Client API for plugin functionality
+     * @param options - Additional options including AppBridge
+     * @returns Cleanup function called when plugin is unmounted
+     */
+    renderSidebar?: (el: HTMLElement, api: ClientApi, options: {
+        bridge: AppBridge<any>;
+    }) => UnmountFn;
+    /**
+     * Render main panel (optional).
+     * This is the primary UI for your plugin.
+     * @param el - Container element to render into
+     * @param api - Client API for plugin functionality
+     * @param options - Additional options including AppBridge
+     * @returns Cleanup function called when plugin is unmounted
+     */
+    renderMain?: (el: HTMLElement, api: ClientApi, options: {
+        bridge: AppBridge<any>;
+    }) => UnmountFn;
+    /**
+     * Render custom settings UI (optional).
+     * If not provided, settings will use the default form based on settings schema.
+     * @param el - Container element to render into
+     * @param api - Client API for plugin functionality
+     * @param options - Additional options including AppBridge
+     * @returns Cleanup function called when plugin is unmounted
+     */
+    renderSettings?: (el: HTMLElement, api: ClientApi, options: {
+        bridge: AppBridge<any>;
+    }) => UnmountFn;
 }
 
+/**
+ * Command definition for Command Palette (accessible via Cmd+K / Ctrl+K).
+ * Commands allow users to quickly access plugin functionality.
+ */
 export declare interface PluginCommand {
+    /** Unique command identifier (e.g., 'my-plugin:clear') */
     id: string;
+    /** Display label in command palette */
     label: string;
+    /** Heroicons icon name (optional) */
     icon?: string;
+    /** Action to execute when command is triggered */
     action: () => void | Promise<void>;
+    /** Keyboard shortcut keys (e.g., ['Meta', 'K', 'C']) */
     shortcut?: string[];
 }
 
@@ -235,92 +565,569 @@ export declare interface PluginMetadata {
     description?: string;
     author?: string;
     homepage?: string;
-    repo?: string;
+    repository?: string;
 }
 
+/**
+ * Plugin settings schema - defines all user-configurable settings for a plugin.
+ *
+ * Settings are automatically displayed in the DevTools settings panel and
+ * can be accessed via `api.settings.get()` and `api.settings.set()`.
+ *
+ * @example
+ * ```ts
+ * const plugin: PluginClientInstance = {
+ *   name: 'My Plugin',
+ *   icon: 'Cube',
+ *   settings: {
+ *     apiUrl: {
+ *       label: 'API URL',
+ *       type: 'string',
+ *       default: 'https://api.example.com'
+ *     },
+ *     timeout: {
+ *       label: 'Timeout (ms)',
+ *       type: 'number',
+ *       default: 5000
+ *     }
+ *   }
+ * };
+ * ```
+ */
 export declare interface PluginSettingsSchema {
     [key: string]: SettingSchemaDef;
 }
 
 /**
- * Функция для регистрации кнопки в оверлее (вызывается из app.ts плагина)
+ * Zod schema for plugin settings schema (record of setting definitions).
+ */
+export declare const PluginSettingsSchemaSchema: z.ZodRecord<z.ZodString, z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>>;
+
+/**
+ * Type inferred from PluginSettingsSchemaSchema
  */
-export declare function registerMenuItem(item: OverlayMenuItem): void;
+export declare type PluginSettingsSchemaType = z.infer<typeof PluginSettingsSchemaSchema>;
 
+/**
+ * RPC Client Interface for making remote procedure calls.
+ * Provides methods to call server methods and subscribe to events.
+ *
+ * Communication: Server ↔ Client via WebSocket (Vite HMR or custom WebSocket)
+ */
 export declare interface RpcClientInterface {
+    /**
+     * Call a remote method on the server.
+     * @param method - Method name (e.g., 'sys:getPlugins')
+     * @param payload - Optional payload data
+     * @returns Promise that resolves with the method result
+     * @template T - Return type of the method
+     */
     call<T = unknown>(method: string, payload?: unknown): Promise<T>;
+    /**
+     * Subscribe to events from the server.
+     * @param event - Event name
+     * @param callback - Callback function to handle events
+     * @returns Function to unsubscribe from the event
+     */
     on(event: string, callback: (data: unknown) => void): () => void;
+    /**
+     * Unsubscribe from events (optional, some transports may not support it).
+     * @param event - Event name
+     * @param callback - Callback function to remove
+     */
     off?(event: string, callback: (data: unknown) => void): void;
 }
 
+/**
+ * RPC message structure for communication between Server and Client contexts.
+ * Used for typed RPC over WebSocket (Server ↔ Client).
+ *
+ * @template T - Type of the payload data
+ */
 export declare interface RpcMessage<T = unknown> {
+    /** Unique message identifier */
     id: string;
+    /** Message type: 'request' for RPC calls, 'response' for replies, 'event' for broadcasts */
     type: 'request' | 'response' | 'event';
+    /** RPC method name (for requests) */
     method?: string;
+    /** Message payload data */
     payload?: T;
+    /** Error information (for error responses) */
     error?: unknown;
 }
 
+/**
+ * Zod schema for RPC message validation.
+ * Validates the structure of RPC messages used for communication between Server and Client contexts.
+ */
+export declare const RpcMessageSchema: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodEnum<{
+        request: "request";
+        response: "response";
+        event: "event";
+    }>;
+    method: z.ZodOptional<z.ZodString>;
+    payload: z.ZodOptional<z.ZodUnknown>;
+    error: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+
+/**
+ * Type inferred from RpcMessageSchema
+ */
+export declare type RpcMessageType = z.infer<typeof RpcMessageSchema>;
+
+/**
+ * RPC Server Interface - Interface for handling RPC requests from clients.
+ * Used in server-side plugin setup to register method handlers.
+ *
+ * @example
+ * ```ts
+ * export function setupServer(rpc: RpcServerInterface, ctx: ServerContext) {
+ *   rpc.handle('my-plugin:getData', async (payload) => {
+ *     // Handle RPC call
+ *     return { data: 'result' };
+ *   });
+ *
+ *   rpc.broadcast('my-plugin:update', { data: 'new' });
+ * }
+ * ```
+ */
 export declare interface RpcServerInterface {
+    /**
+     * Register a handler for an RPC method.
+     * @param method - Method name (e.g., 'my-plugin:getData')
+     * @param fn - Handler function that receives payload and returns result
+     */
     handle(method: string, fn: (payload: unknown) => Promise<unknown> | unknown): void;
+    /**
+     * Broadcast an event to all connected clients.
+     * @param event - Event name
+     * @param payload - Optional event data
+     */
     broadcast(event: string, payload?: unknown): void;
 }
 
+/**
+ * Server Context - Context object provided to server-side plugin setup.
+ * Available in: Server context (Node.js - Vite dev server)
+ */
 export declare interface ServerContext {
+    /** Project root directory path */
     root: string;
+    /** Vite dev server instance (for advanced use cases) */
     server: unknown;
 }
 
+/**
+ * Zod schema for setting option (used in select type).
+ */
+export declare const SettingOptionSchema: z.ZodObject<{
+    label: z.ZodString;
+    value: z.ZodUnknown;
+}, z.core.$strip>;
+
+/**
+ * Settings API for user-configurable plugin settings.
+ * Settings are displayed in DevTools settings panel and persist across sessions.
+ *
+ * @example
+ * ```typescript
+ * import type { SettingsApi } from '@u-devtools/core';
+ *
+ * function useSettings(api: SettingsApi) {
+ *   // Get setting with default
+ *   const fontSize = api.get('fontSize', 14);
+ *   const theme = api.get('theme', 'dark');
+ *   const enabled = api.get('enabled', true);
+ *
+ *   // Set settings
+ *   api.set('fontSize', 16);
+ *   api.set('theme', 'light');
+ *   api.set('enabled', false);
+ *
+ *   // Access all settings reactively (for Vue bindings)
+ *   const allSettings = api.all;
+ * }
+ * ```
+ */
 export declare interface SettingsApi {
     /**
-     * Получить значение настройки.
-     * @param key Ключ настройки (без префикса плагина)
-     * @param defaultValue Значение по умолчанию, если настройка не задана
+     * Get a setting value.
+     * @param key Setting key (without plugin prefix)
+     * @param defaultValue Default value if setting is not set
      */
     get<T>(key: string, defaultValue?: T): T;
     /**
-     * Установить значение настройки.
-     * @param key Ключ настройки
-     * @param value Новое значение
+     * Set a setting value.
+     * @param key Setting key
+     * @param value New value
      */
     set(key: string, value: unknown): void;
     /**
-     * Реактивный объект всех настроек (для UI биндингов)
+     * Reactive object of all settings (for UI bindings)
      */
     all: Record<string, unknown>;
 }
 
+/**
+ * Setting schema definition for a single setting.
+ * Used to define user-configurable settings that appear in the DevTools settings panel.
+ *
+ * @example
+ * ```typescript
+ * const pluginWithSettings: PluginClientInstance = {
+ *   name: 'My Plugin',
+ *   icon: 'Cube',
+ *
+ *   settings: {
+ *     fontSize: {
+ *       label: 'Font Size',
+ *       description: 'Base font size for the plugin',
+ *       type: 'number',
+ *       default: 14,
+ *     },
+ *     theme: {
+ *       label: 'Theme',
+ *       type: 'select',
+ *       default: 'dark',
+ *       options: [
+ *         { label: 'Dark', value: 'dark' },
+ *         { label: 'Light', value: 'light' },
+ *       ],
+ *     },
+ *   },
+ *
+ *   renderMain(container, api) {
+ *     // Access settings
+ *     const fontSize = api.settings.get('fontSize', 14);
+ *     const theme = api.settings.get('theme', 'dark');
+ *
+ *     return () => {};
+ *   }
+ * };
+ * ```
+ */
 export declare interface SettingSchemaDef {
+    /** Display label for the setting */
     label: string;
+    /** Optional description/tooltip text */
     description?: string;
+    /** Setting type (determines input component) */
     type: SettingType;
+    /** Default value */
     default?: unknown;
+    /** Options for 'select' type settings */
     options?: {
         label: string;
         value: unknown;
     }[];
+    /** Schema for array items (for 'array' type with object items) */
     items?: Record<string, SettingSchemaDef>;
+    /** Item type for 'array' type with primitive items ('string' or 'number') */
     itemType?: 'string' | 'number';
 }
 
+/**
+ * Zod schema for setting schema definition.
+ * Recursive schema using z.lazy for items field.
+ */
+export declare const SettingSchemaDefSchema: z.ZodType<any>;
+
+/**
+ * Type inferred from SettingSchemaDefSchema
+ */
+export declare type SettingSchemaDefType = z.infer<typeof SettingSchemaDefSchema>;
+
+/**
+ * Setting type for plugin settings schema.
+ * Defines the input type for user-configurable settings.
+ */
 export declare type SettingType = 'string' | 'number' | 'boolean' | 'select' | 'array';
 
+/**
+ * Zod schema for setting type validation.
+ */
+export declare const SettingTypeSchema: z.ZodEnum<{
+    string: "string";
+    number: "number";
+    boolean: "boolean";
+    select: "select";
+    array: "array";
+}>;
+
 export declare interface ShortcutApi {
     /**
-     * Зарегистрировать горячую клавишу.
-     * @param keys Массив клавиш (например, ['Meta', 'K'])
-     * @param action Действие при нажатии
-     * @returns Функция для отмены регистрации
+     * Register a keyboard shortcut.
+     * @param keys Array of keys (e.g., ['Meta', 'K'])
+     * @param action Action to execute on key press
+     * @returns Function to unregister the shortcut
      */
     register(keys: string[], action: () => void): () => void;
 }
 
+/**
+ * Storage API for plugin-specific persistent storage.
+ * Used for internal plugin state (e.g., last opened file, view preferences).
+ * Storage is isolated per plugin and persists across sessions.
+ *
+ * @example
+ * ```typescript
+ * import type { StorageApi } from '@u-devtools/core';
+ *
+ * function useStorage(api: StorageApi) {
+ *   // Store values
+ *   api.set('lastView', 'list');
+ *   api.set('filters', { category: 'all', sort: 'name' });
+ *   api.set('items', ['item1', 'item2', 'item3']);
+ *
+ *   // Retrieve values with defaults
+ *   const lastView = api.get('lastView', 'default');
+ *   const filters = api.get('filters', { category: 'all' });
+ *   const items = api.get<string[]>('items', []);
+ *
+ *   // Remove values
+ *   api.remove('lastView');
+ * }
+ * ```
+ */
 export declare interface StorageApi {
+    /**
+     * Get a stored value.
+     * @param key - Storage key
+     * @param def - Default value if key doesn't exist
+     * @returns Stored value or default
+     * @template T - Type of the stored value
+     */
     get<T>(key: string, def: T): T;
+    /**
+     * Set a stored value.
+     * @param key - Storage key
+     * @param value - Value to store
+     * @template T - Type of the value
+     */
     set<T>(key: string, value: T): void;
+    /**
+     * Remove a stored value.
+     * @param key - Storage key to remove
+     */
     remove(key: string): void;
 }
 
+/**
+ * Universal state class with automatic synchronization between App and Client contexts.
+ * Implements "Handshake" protocol for getting current data on initialization.
+ *
+ * Use this for state that needs to be shared between App context (main window)
+ * and Client context (DevTools iframe). Changes are automatically synchronized.
+ *
+ * @template T - Type of the state value
+ *
+ * @example
+ * ```typescript
+ * import { AppBridge } from '@u-devtools/core';
+ *
+ * // Create bridge
+ * const bridge = new AppBridge('my-plugin');
+ *
+ * // Create synced state
+ * const isOpen = bridge.state('isOpen', false);
+ * const count = bridge.state('count', 0);
+ *
+ * // Update value (automatically syncs to Client)
+ * isOpen.value = true;
+ * count.value = 42;
+ *
+ * // Subscribe to changes
+ * const unsubscribe = isOpen.subscribe((value) => {
+ *   console.log('State changed:', value);
+ * });
+ *
+ * // Cleanup
+ * unsubscribe();
+ * ```
+ */
+export declare class SyncedState<T> {
+    private bridge;
+    private key;
+    private _value;
+    private listeners;
+    private isUpdating;
+    constructor(bridge: AppBridge<any>, key: string, initialValue: T);
+    get value(): T;
+    set value(newValue: T);
+    subscribe: (fn: (val: T) => void) => () => void;
+    getSnapshot: () => T;
+    private notify;
+}
+
+/**
+ * Abstract class for message transport.
+ * Provides common logic for RPC calls and event subscriptions.
+ */
+export declare abstract class Transport {
+    protected handlers: Map<string, {
+        resolve: (value: unknown) => void;
+        reject: (error: Error) => void;
+    }>;
+    protected eventListeners: Map<string, Set<(data: unknown) => void>>;
+    protected disposed: boolean;
+    protected timeout: number;
+    /**
+     * Send a message through the transport
+     */
+    protected abstract sendMessage(type: string, data: unknown): void;
+    /**
+     * Subscribe to messages from the transport
+     */
+    protected abstract subscribe(type: string, handler: (data: unknown) => void): () => void;
+    /**
+     * Unsubscribe from transport messages
+     */
+    protected abstract unsubscribe?(type: string, handler: (data: unknown) => void): void;
+    /**
+     * RPC method call
+     */
+    call<T = unknown>(method: string, payload?: unknown): Promise<T>;
+    /**
+     * Subscribe to events
+     */
+    on(event: string, fn: (data: unknown) => void): () => void;
+    /**
+     * Unsubscribe from events
+     */
+    off(event: string, fn: (data: unknown) => void): void;
+    /**
+     * Handle incoming messages (called by transport)
+     */
+    protected handleMessage(data: unknown): void;
+    /**
+     * Clean up all handlers and subscriptions
+     */
+    dispose(): void;
+}
+
+/**
+ * Typed Event Emitter for inter-plugin communication.
+ * Provides type-safe event emission and subscription.
+ *
+ * @template T - Type definition for events and their data
+ *
+ * @example
+ * ```typescript
+ * import { TypedEventBus, type BusEvents } from '@u-devtools/core';
+ *
+ * // Create event bus instance
+ * const bus = new TypedEventBus<BusEvents>();
+ *
+ * // Emit events
+ * bus.emit('plugin:mounted', { name: 'my-plugin' });
+ * bus.emit('navigate', { path: '/settings' });
+ * bus.emit('settings:changed', { key: 'theme', value: 'dark' });
+ *
+ * // Subscribe to events
+ * const unsubscribe1 = bus.on('plugin:mounted', ({ name }) => {
+ *   console.log(`Plugin ${name} was mounted`);
+ * });
+ *
+ * const unsubscribe2 = bus.on('navigate', ({ path }) => {
+ *   console.log(`Navigating to: ${path}`);
+ * });
+ *
+ * // Unsubscribe
+ * unsubscribe1();
+ * unsubscribe2();
+ *
+ * // Or use off method (handler must be the same function reference)
+ * const handler = ({ name }: { name: string }) => {
+ *   console.log(`Plugin ${name} was mounted`);
+ * };
+ * bus.on('plugin:mounted', handler);
+ * bus.off('plugin:mounted', handler);
+ * ```
+ */
+export declare class TypedEventBus<T extends Record<string, unknown> = BusEvents> {
+    private listeners;
+    /**
+     * Emit an event
+     */
+    emit<K extends keyof T>(event: K, data: T[K]): void;
+    /**
+     * Subscribe to an event
+     */
+    on<K extends keyof T>(event: K, handler: (data: T[K]) => void): () => void;
+    /**
+     * Unsubscribe from an event
+     */
+    off<K extends keyof T>(event: K, handler: (data: T[K]) => void): void;
+    /**
+     * Clear all subscriptions
+     */
+    clear(): void;
+    /**
+     * Get the number of subscribers for an event
+     */
+    listenerCount<K extends keyof T>(event: K): number;
+}
+
 export declare type UnmountFn = () => void;
 
+/**
+ * Validates a plugin settings schema.
+ * @param data - Data to validate
+ * @returns Validated plugin settings schema or null if validation fails
+ */
+export declare function validatePluginSettingsSchema(data: unknown): PluginSettingsSchemaType | null;
+
+/**
+ * Validates an unknown value as an RPC message.
+ * @param data - Data to validate
+ * @returns Validated RPC message or null if validation fails
+ */
+export declare function validateRpcMessage(data: unknown): RpcMessageType | null;
+
+/**
+ * Validates a setting schema definition.
+ * @param data - Data to validate
+ * @returns Validated setting schema definition or null if validation fails
+ */
+export declare function validateSettingSchemaDef(data: unknown): SettingSchemaDefType | null;
+
+/**
+ * Validates a setting value against its schema definition.
+ * @param value - Value to validate
+ * @param schemaDef - Setting schema definition
+ * @returns True if value is valid, false otherwise
+ */
+export declare function validateSettingValue(value: unknown, schemaDef: SettingSchemaDefType): boolean;
+
+/**
+ * Transport based on WebSocket
+ * Used for communication between client and server when HMR is unavailable
+ * (e.g., for remote debugging or production builds)
+ */
+export declare class WebSocketTransport extends Transport {
+    private url;
+    private ws;
+    private reconnectAttempts;
+    private maxReconnectAttempts;
+    private reconnectDelay;
+    private reconnectTimer;
+    private isManualClose;
+    private messageQueue;
+    constructor(url: string);
+    private connect;
+    private scheduleReconnect;
+    protected sendMessage(type: string, data: unknown): void;
+    private flushQueue;
+    protected subscribe(_type: string, _handler: (data: unknown) => void): () => void;
+    protected unsubscribe(_type: string, _handler: (data: unknown) => void): void;
+    dispose(): void;
+    /**
+     * Check connection status
+     */
+    isConnected(): boolean;
+}
+
 export { }