/**
 * Widget Registry
 *
 * Extensible registry for mountable widget components.
 * Apps can register custom widgets that can be rendered via mountWidget actions.
 */
/**
 * Cleanup function returned when unmounting a widget.
 */
export type WidgetCleanup = () => void;
/**
 * Mountable widget component interface.
 *
 * Widgets must implement this interface to be registered and mounted
 * via the Surfaces system or mountWidget actions.
 */
export interface MountableWidget {
    /**
     * Mount the widget into a container element.
     *
     * @param container - The DOM element to mount into
     * @param config - Configuration/props for the widget
     * @returns A cleanup function to unmount the widget, or void
     */
    mount(container: HTMLElement, config?: Record<string, unknown>): WidgetCleanup | void;
    /**
     * Optional: Update the widget with new config.
     * If not provided, the widget will be unmounted and remounted on updates.
     *
     * @param container - The DOM element containing the widget
     * @param config - New configuration/props
     */
    update?(container: HTMLElement, config?: Record<string, unknown>): void;
}
/**
 * Widget registration entry.
 */
export interface WidgetRegistration {
    /** Widget ID (e.g., "gamification:leaderboard") */
    id: string;
    /** The widget component */
    widget: MountableWidget;
    /** Source app ID or "built-in" */
    source: 'built-in' | string;
    /** Optional metadata */
    metadata?: {
        name?: string;
        description?: string;
        icon?: string;
        subtitle?: string;
    };
}
/**
 * Mounted widget handle.
 */
export interface MountedWidgetHandle {
    /** The widget ID */
    widgetId: string;
    /** The container element */
    container: HTMLElement;
    /** Unmount the widget */
    unmount: () => void;
    /** Update the widget config */
    update: (config?: Record<string, unknown>) => void;
}
/**
 * Extensible registry for widget components.
 *
 * Allows apps to register custom widgets that can be rendered via
 * mountWidget actions or directly through the Surfaces system.
 */
export type WidgetRegistryListener = (event: {
    type: 'registered' | 'unregistered';
    widgetId: string;
}) => void;
export declare class WidgetRegistry {
    private widgets;
    private mountedWidgets;
    private mountIdCounter;
    private runtimeRef?;
    private listeners;
    /**
     * Bind a runtime reference so it can be injected into widget mount() calls.
     * Uses `unknown` to avoid circular imports (WidgetRegistry ← runtime.ts).
     */
    bindRuntime(runtime: unknown): void;
    /**
     * Register a widget.
     *
     * @param id - The widget ID (e.g., "gamification:leaderboard")
     * @param widget - The widget component
     * @param source - The source app ID (for tracking)
     * @param metadata - Optional metadata about the widget
     */
    register(id: string, widget: MountableWidget, source?: string, metadata?: WidgetRegistration['metadata']): void;
    /**
     * Unregister a widget.
     *
     * @param id - The widget ID to unregister
     * @returns true if the widget was unregistered, false if not found or built-in
     */
    unregister(id: string): boolean;
    /**
     * Unregister all widgets from a specific source.
     *
     * @param source - The source app ID
     */
    unregisterBySource(source: string): void;
    /**
     * Get a widget by ID.
     */
    get(id: string): MountableWidget | undefined;
    /**
     * Get the full registration for a widget.
     */
    getRegistration(id: string): WidgetRegistration | undefined;
    /**
     * Check if a widget exists.
     */
    has(id: string): boolean;
    /**
     * Mount a widget into a container.
     *
     * @param id - The widget ID
     * @param container - The DOM element to mount into
     * @param config - Configuration/props for the widget
     * @returns A handle for managing the mounted widget
     */
    mount(id: string, container: HTMLElement, config?: Record<string, unknown>): MountedWidgetHandle;
    /**
     * List all registered widget IDs.
     */
    list(): string[];
    /**
     * List all registrations.
     */
    listRegistrations(): WidgetRegistration[];
    /**
     * Get all widgets from a specific source.
     */
    getBySource(source: string): WidgetRegistration[];
    /**
     * Subscribe to widget registration changes.
     */
    subscribe(callback: WidgetRegistryListener): () => void;
    private notify;
    /**
     * Clean up all mounted widgets.
     */
    destroy(): void;
}
/**
 * Default singleton instance of WidgetRegistry.
 */
export declare const widgetRegistry: WidgetRegistry;
