@hsafa/ui-sdk 0.2.5 → 0.3.1

package/dist/index.d.cts

@@ -1,11 +1,11 @@
-import * as react from 'react';
-import react__default, { ComponentType } from 'react';
+import * as React$1 from 'react';
+import React__default, { ComponentType } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
 /**
  * Props for the Button component
  */
-interface ButtonProps extends react__default.ButtonHTMLAttributes<HTMLButtonElement> {
+interface ButtonProps extends React__default.ButtonHTMLAttributes<HTMLButtonElement> {
     /** Visual style variant of the button */
     variant?: "primary" | "secondary" | "outline" | "ghost";
     /** Size of the button */
@@ -13,7 +13,7 @@ interface ButtonProps extends react__default.ButtonHTMLAttributes<HTMLButtonElem
     /** Whether the button is in a loading state */
     loading?: boolean;
     /** Content to be displayed inside the button */
-    children: react__default.ReactNode;
+    children: React__default.ReactNode;
 }
 /**
  * A versatile button component with multiple variants, sizes, and states.
@@ -33,173 +33,7 @@ interface ButtonProps extends react__default.ButtonHTMLAttributes<HTMLButtonElem
  * <Button onClick={() => console.log('Clicked!')}>Click me</Button>
  * ```
  */
-declare const Button: react__default.FC<ButtonProps>;
-
-/**
- * Vercel AI SDK compatible message types
- * Based on https://sdk.vercel.ai/docs/ai-sdk-core/messages
- */
-type TextPart = {
-    type: 'text';
-    text: string;
-};
-type ImagePart = {
-    type: 'image';
-    image: string | URL;
-    mediaType?: string;
-};
-type FilePart = {
-    type: 'file';
-    data: string | URL;
-    mediaType: string;
-    name?: string;
-};
-type UserContentPart = TextPart | ImagePart | FilePart;
-type AssistantTextPart = {
-    type: 'text';
-    text: string;
-};
-type ReasoningPart = {
-    type: 'reasoning';
-    text: string;
-};
-type AssistantFilePart = {
-    type: 'file';
-    data: string | URL;
-    mediaType: string;
-    filename?: string;
-};
-type ToolCallPart = {
-    type: 'tool-call';
-    toolCallId: string;
-    toolName: string;
-    input: any;
-};
-type AssistantContentPart = AssistantTextPart | ReasoningPart | AssistantFilePart | ToolCallPart;
-interface Attachment {
-    id: string;
-    name: string;
-    url: string;
-    mimeType: string;
-    size: number;
-}
-
-/**
- * Type definitions for the HsafaChat component
- */
-
-type MainAgentAction$1 = {
-    type: 'reasoning';
-    reasoning: string;
-    status: 'streaming' | 'finished';
-    startDate?: number;
-    endDate?: number;
-    durationMs?: number;
-} | {
-    type: 'tool-call';
-    toolCallId?: string;
-    toolName?: string;
-    input?: any;
-    inputText?: string;
-    output?: any;
-    status: 'input_streaming' | 'running' | 'finished' | 'error';
-    error?: string;
-    startDate?: number;
-    endDate?: number;
-    durationMs?: number;
-} | {
-    type: 'step';
-    stepNumber?: number;
-    finishReason?: string;
-    usage?: any;
-    startDate?: number;
-    endDate?: number;
-    durationMs?: number;
-} | {
-    type: 'text';
-    text: string;
-    status: 'streaming' | 'finished';
-    startDate?: number;
-    endDate?: number;
-    durationMs?: number;
-} | {
-    type: 'source';
-    source: any;
-    durationMs?: number;
-} | {
-    type: 'file';
-    file: any;
-    durationMs?: number;
-} | {
-    type: 'response';
-    items: any[];
-    [key: string]: any;
-    startDate?: number;
-    endDate?: number;
-    durationMs?: number;
-};
-type ChatMessage = {
-    id: string;
-    role: 'user';
-    content: string | UserContentPart[];
-    createdAt?: number;
-    text?: string;
-    attachments?: Attachment[];
-} | {
-    id: string;
-    role: 'assistant';
-    content?: string | AssistantContentPart[];
-    items: any[];
-    reasoning?: string;
-    reasoningOpen?: boolean;
-    reasoningTokens?: number;
-    createdAt?: number;
-    requestParams?: any;
-    mcpToolCalls?: Array<{
-        toolName: string;
-        args: any;
-        timestamp: number;
-        status?: 'pending' | 'running' | 'completed' | 'failed';
-    }>;
-    mcpToolResults?: Record<string, any>;
-    mainAgentActions?: MainAgentAction$1[];
-    firstAgentMessage?: string;
-    firstAgentContinue?: boolean;
-    autoGenerated?: boolean;
-    hidden?: boolean;
-    turnIndex?: number;
-    controlDecision?: 'continue' | 'done';
-    followUpPrompt?: string;
-};
-interface HsafaChatProps {
-    agentId: string;
-    theme?: 'dark' | 'light';
-    primaryColor?: string;
-    backgroundColor?: string;
-    borderColor?: string;
-    textColor?: string;
-    accentColor?: string;
-    width?: number | string;
-    maxWidth?: number | string;
-    height?: string;
-    expandable?: boolean;
-    alwaysOpen?: boolean;
-    defaultOpen?: boolean;
-    floatingButtonPosition?: {
-        bottom?: number | string;
-        right?: number | string;
-        top?: number | string;
-        left?: number | string;
-    };
-    placeholder?: string;
-    title?: string;
-    className?: string;
-    chatContainerClassName?: string;
-    dir?: 'rtl' | 'ltr';
-    language?: 'en' | 'ar';
-    defaultReasoningOpen?: boolean;
-    hideReasoningContent?: boolean;
-}
+declare const Button: React__default.FC<ButtonProps>;
 
 declare const themeColors: {
     dark: {
@@ -227,57 +61,6 @@ declare const themeColors: {
 };
 type ThemeColors = typeof themeColors.dark;
 
-type TranslationKeys = {
-    'header.maximize': string;
-    'header.minimize': string;
-    'header.new': string;
-    'header.history': string;
-    'header.close': string;
-    'input.placeholder': string;
-    'input.attachFiles': string;
-    'input.insertLink': string;
-    'input.send': string;
-    'input.stop': string;
-    'input.uploadingFiles': string;
-    'input.previewImage': string;
-    'input.removeFile': string;
-    'editor.cancel': string;
-    'editor.saveAndRegenerate': string;
-    'editor.clickToEdit': string;
-    'messages.empty': string;
-    'messages.error': string;
-    'history.search': string;
-    'history.noChatsFound': string;
-    'history.untitledChat': string;
-    'history.deleteChat': string;
-    'general.agent': string;
-};
-
-interface MessageListProps {
-    messages: ChatMessage[];
-    streaming: boolean;
-    editingMessageId: string | null;
-    editingMessageText: string;
-    editingAttachments?: Attachment[];
-    error: string | null;
-    actionStatuses: Map<string, 'executing' | 'executed'>;
-    components: Map<string, react__default.ComponentType<any>>;
-    theme: 'light' | 'dark';
-    resolvedColors: ThemeColors;
-    onEditingTextChange: (text: string) => void;
-    onRemoveAttachment?: (id: string) => void;
-    onAddAttachments?: (files: FileList) => void;
-    uploading?: boolean;
-    onStartEdit: (messageId: string, text: string) => void;
-    onCancelEdit: () => void;
-    onSaveEdit: (messageId: string, text: string) => void;
-    onToggleReasoning: (messageId: string) => void;
-    scrollAnchorRef: react__default.RefObject<HTMLDivElement>;
-    hideReasoningContent?: boolean;
-    t: (key: keyof TranslationKeys) => string;
-}
-declare function MessageList({ messages, streaming, editingMessageId, editingMessageText, editingAttachments, error, actionStatuses, components, theme, resolvedColors, onEditingTextChange, onRemoveAttachment, onAddAttachments, uploading, onStartEdit, onCancelEdit, onSaveEdit, onToggleReasoning, scrollAnchorRef, hideReasoningContent, t }: MessageListProps): react_jsx_runtime.JSX.Element;
-
 interface FloatingChatButtonProps {
     show: boolean;
     onClick: () => void;
@@ -291,26 +74,67 @@ interface FloatingChatButtonProps {
 }
 declare function FloatingChatButton({ show, onClick, resolvedColors, floatingButtonPosition }: FloatingChatButtonProps): react_jsx_runtime.JSX.Element | null;
 
-interface UseToggleReturn {
-    /** Current toggle state */
-    on: boolean;
-    /** Toggle the state */
-    toggle: () => void;
-    /** Set the state directly */
-    setOn: (value: boolean | ((prev: boolean) => boolean)) => void;
-    /** Set state to true */
-    setTrue: () => void;
-    /** Set state to false */
-    setFalse: () => void;
-}
+declare function useAutoScroll<T extends HTMLElement>(shouldScroll?: boolean): React$1.MutableRefObject<T | null>;
+
 /**
- * A hook for managing boolean toggle state
- * @param initial - Initial state value (default: false)
- * @returns Object with toggle state and control functions
+ * Type definitions for the Hsafa SDK - minimal exports used across the SDK
  */
-declare function useToggle(initial?: boolean): UseToggleReturn;
+type Attachment = {
+    id: string;
+    name?: string;
+    url: string;
+    mimeType?: string;
+    size?: number;
+};
+type HsafaTool = ((input: any) => any | Promise<any>) | {
+    tool: (input: any) => any | Promise<any>;
+    executeEachToken?: boolean;
+};
+interface HsafaChatProps {
+    agentId: string;
+    theme?: 'dark' | 'light';
+    primaryColor?: string;
+    primaryColorDark?: string;
+    primaryColorLight?: string;
+    backgroundColor?: string;
+    borderColor?: string;
+    textColor?: string;
+    accentColor?: string;
+    width?: number | string;
+    maxWidth?: number | string;
+    height?: string;
+    expandable?: boolean;
+    alwaysOpen?: boolean;
+    defaultOpen?: boolean;
+    floatingButtonPosition?: {
+        bottom?: number | string;
+        right?: number | string;
+        top?: number | string;
+        left?: number | string;
+    };
+    placeholder?: string;
+    title?: string;
+    className?: string;
+    chatContainerClassName?: string;
+    dir?: 'rtl' | 'ltr';
+    language?: 'en' | 'ar';
+    defaultReasoningOpen?: boolean;
+    hideReasoningContent?: boolean;
+    UIComponents?: Record<string, React.ComponentType<any>>;
+    HsafaTools?: Record<string, HsafaTool>;
+}
 
-declare function useAutoScroll<T extends HTMLElement>(): react.MutableRefObject<T | null>;
+declare function useFileUpload(baseUrl: string): {
+    attachments: Attachment[];
+    uploading: boolean;
+    fileInputRef: React$1.MutableRefObject<HTMLInputElement | null>;
+    formatBytes: (bytes: number) => string;
+    handleRemoveAttachment: (id: string) => void;
+    handleFileSelection: (fileList: FileList | File[] | null, setError: (error: string | null) => void) => Promise<void>;
+    buildUserContent: (text: string, attachments: Attachment[]) => any[];
+    clearAttachments: () => void;
+    MAX_UPLOAD_SIZE: number;
+};
 
 /**
  * Handler function for custom actions that can be triggered by the AI agent
@@ -333,6 +157,10 @@ type HsafaActionHandler = (params: any, meta: {
 interface HsafaConfig {
     /** Base URL for agent API calls, e.g. "" (same origin) or "https://example.com" */
     baseUrl?: string;
+    /** Default text direction for SDK components */
+    dir?: 'ltr' | 'rtl';
+    /** Default theme for SDK components */
+    theme?: 'dark' | 'light';
 }
 /**
  * Context value provided by HsafaProvider
@@ -341,15 +169,15 @@ interface HsafaContextValue extends HsafaConfig {
     /** Registered custom actions */
     actions: Map<string, HsafaActionHandler>;
     /** Registered custom components */
-    components: Map<string, react__default.ComponentType<any>>;
+    components: Map<string, React__default.ComponentType<any>>;
     /** Register a custom action handler */
     registerAction: (name: string, handler: HsafaActionHandler) => () => void;
     /** Unregister a custom action handler */
     unregisterAction: (name: string, handler?: HsafaActionHandler) => void;
     /** Register a custom component */
-    registerComponent: (name: string, component: react__default.ComponentType<any>) => () => void;
+    registerComponent: (name: string, component: React__default.ComponentType<any>) => () => void;
     /** Unregister a custom component */
-    unregisterComponent: (name: string, component?: react__default.ComponentType<any>) => void;
+    unregisterComponent: (name: string, component?: React__default.ComponentType<any>) => void;
     /** Global streaming state - true if any chat is streaming */
     isAnyStreaming: boolean;
     /** Set streaming state for a specific chat instance */
@@ -364,7 +192,7 @@ interface HsafaContextValue extends HsafaConfig {
  */
 interface HsafaProviderProps extends HsafaConfig {
     /** Child components that will have access to the Hsafa context */
-    children: react__default.ReactNode;
+    children: React__default.ReactNode;
 }
 /**
  * Provider component that sets up the Hsafa context for the SDK.
@@ -377,7 +205,7 @@ interface HsafaProviderProps extends HsafaConfig {
  * </HsafaProvider>
  * ```
  */
-declare function HsafaProvider({ baseUrl, children }: HsafaProviderProps): react_jsx_runtime.JSX.Element;
+declare function HsafaProvider({ baseUrl, dir, theme, children }: HsafaProviderProps): react_jsx_runtime.JSX.Element;
 /**
  * Hook to access the Hsafa context.
  * Must be used within a HsafaProvider.
@@ -404,187 +232,14 @@ declare function HsafaProvider({ baseUrl, children }: HsafaProviderProps): react
  */
 declare function useHsafa(): HsafaContextValue;
 
-/**
- * Register an action handler by name within the nearest HsafaProvider.
- * The handler will be automatically unregistered on unmount.
- *
- * @param name - Unique name for the action
- * @param handler - Function to execute when action is triggered
- *
- * @example
- * ```tsx
- * useHsafaAction('submitForm', async (params, meta) => {
- *   console.log('Form submitted:', params);
- *   return { success: true };
- * });
- * ```
- */
-declare function useHsafaAction(name: string, handler: HsafaActionHandler): void;
-
-/**
- * Register a UI component by name within the nearest HsafaProvider.
- * The component will be automatically unregistered on unmount.
- *
- * @param name - Unique name for the component (matches agent's component field)
- * @param component - React component to render when agent requests this component
- *
- * @example
- * ```tsx
- * function ProductCard({ name, price }: { name: string; price: number }) {
- *   return <div>{name}: ${price}</div>;
- * }
- *
- * useHsafaComponent('ProductCard', ProductCard);
- * ```
- */
-declare function useHsafaComponent<T = any>(name: string, component: ComponentType<T>): void;
-
-interface ChatMeta {
-    id: string;
-    title: string;
-    createdAt: number;
-    updatedAt: number;
-}
-interface ChatData {
-    id: string;
-    messages: ChatMessage[];
-    agentId?: string;
-}
-declare function useChatStorage(agentId: string): {
-    currentChatId: string | null;
-    setCurrentChatId: react.Dispatch<react.SetStateAction<string | null>>;
-    hasChatRecordRef: react.MutableRefObject<boolean>;
-    pendingFirstTitleRef: react.MutableRefObject<string | null>;
-    loadChatsIndex: () => ChatMeta[];
-    loadChat: (id: string) => ChatData | null;
-    saveChat: (data: ChatData) => void;
-    deleteChat: (id: string, onChatDeleted?: (wasCurrentChat: boolean) => void) => void;
-    loadChatPreferences: () => ChatMessage[];
-    persistChatData: (messages: ChatMessage[]) => void;
-    createNewChat: (firstMessage?: string) => string;
-    upsertChatMeta: (meta: ChatMeta) => void;
-    showChatKey: string;
-};
-
-declare function useStreaming(): {
-    streaming: boolean;
-    setStreaming: react.Dispatch<react.SetStateAction<boolean>>;
-    error: string | null;
-    setError: react.Dispatch<react.SetStateAction<string | null>>;
-    actionStatuses: Map<string, "executing" | "executed">;
-    setActionStatuses: react.Dispatch<react.SetStateAction<Map<string, "executing" | "executed">>>;
-    abortControllerRef: react.MutableRefObject<AbortController | null>;
-    actionExecMapRef: react.MutableRefObject<Record<string, boolean>>;
-    assistantMsgIdRef: react.MutableRefObject<string | undefined>;
-    calledFinalActionsRef: react.MutableRefObject<Set<string>>;
-    actionParamsHistoryRef: react.MutableRefObject<Map<string, any[]>>;
-    actionExecutionStatusRef: react.MutableRefObject<Map<string, "executing" | "executed">>;
-    processActions: (items: any[] | undefined, trigger: "partial" | "final", actions: Map<string, any>, currentChatId: string | null) => void;
-    handleStop: () => void;
-    resetActionTracking: () => void;
-    cleanupTimeouts: () => void;
-    hasActionParamsStabilized: (actionKey: string, currentParams: any) => boolean;
-};
-
-declare function useFileUpload(baseUrl: string): {
-    attachments: Attachment[];
-    uploading: boolean;
-    fileInputRef: react.MutableRefObject<HTMLInputElement | null>;
-    formatBytes: (bytes: number) => string;
-    handleRemoveAttachment: (id: string) => void;
-    handleFileSelection: (fileList: FileList | File[] | null, setError: (error: string | null) => void) => Promise<void>;
-    buildUserContent: (text: string, attachments: Attachment[]) => any[];
-    clearAttachments: () => void;
-    MAX_UPLOAD_SIZE: number;
-};
-
-/**
- * Types matching the structure from getAgentStreamingResponse
- */
-type FirstAgentData = {
-    message: string;
-    continue: boolean;
-    startDate?: number;
-    endDate?: number;
-    durationMs?: number;
-};
-type MainAgentAction = {
-    type: 'reasoning';
-    reasoning: string;
-    status: 'streaming' | 'finished';
-    startDate?: number;
-    endDate?: number;
-    durationMs?: number;
-} | {
-    type: 'tool-call';
-    toolCallId?: string;
-    toolName?: string;
-    input?: any;
-    inputText?: string;
-    output?: any;
-    status: 'input_streaming' | 'running' | 'finished' | 'error';
-    error?: string;
-    startDate?: number;
-    endDate?: number;
-    durationMs?: number;
-} | {
-    type: 'step';
-    stepNumber?: number;
-    finishReason?: string;
-    usage?: any;
-    startDate?: number;
-    endDate?: number;
-    durationMs?: number;
-} | {
-    type: 'text';
-    text: string;
-    status: 'streaming' | 'finished';
-    startDate?: number;
-    endDate?: number;
-    durationMs?: number;
-} | {
-    type: 'source';
-    source: any;
-    durationMs?: number;
-} | {
-    type: 'file';
-    file: any;
-    durationMs?: number;
-} | {
-    type: 'response';
-    items: any[];
-    [key: string]: any;
-    startDate?: number;
-    endDate?: number;
-    durationMs?: number;
-};
-type AgentStreamData = {
-    first_agent: FirstAgentData;
-    main_agent: MainAgentAction[];
-};
-/**
- * Hook to handle agent streaming responses
- * Returns streaming state and a function to start streaming
- */
-declare function useAgentStreaming(): {
-    streaming: boolean;
-    error: string | null;
-    streamData: AgentStreamData | null;
-    startStreaming: ({ agentId, body, baseUrl, onUpdate, signal, }: {
-        agentId: string;
-        body: any;
-        baseUrl?: string;
-        onUpdate?: (data: AgentStreamData) => void;
-        signal?: AbortSignal;
-    }) => Promise<AgentStreamData | null>;
-    stopStreaming: () => void;
-    reset: () => void;
-};
-
-declare function HsafaChat(props: HsafaChatProps): react__default.ReactPortal | null;
+declare function HsafaChat({ agentId, theme, primaryColor, primaryColorDark, primaryColorLight, backgroundColor, borderColor, textColor, accentColor, baseUrl, initialMessages, onMessagesChange, defaultOpen, floatingButtonPosition, UIComponents, HsafaTools, }: HsafaChatProps & {
+    baseUrl?: string;
+    initialMessages?: any[];
+    onMessagesChange?: (messages: any[]) => void;
+}): react_jsx_runtime.JSX.Element;
 
 interface ContentContainerProps {
-    children: react__default.ReactNode;
+    children: React__default.ReactNode;
     theme?: "dark" | "light";
     primaryColor?: string;
     backgroundColor?: string;
@@ -642,4 +297,264 @@ interface ContentContainerProps {
  */
 declare function ContentContainer({ children, theme, primaryColor, backgroundColor, borderColor, textColor, mutedTextColor, enableBorderAnimation, borderRadius, enableContentBorder, className, enableMargin, chatWidth, dir, }: ContentContainerProps): react_jsx_runtime.JSX.Element;
 
-export { type AgentStreamData, Button, type ButtonProps, type ChatData, type ChatMeta, ContentContainer, type ContentContainerProps, type FirstAgentData, FloatingChatButton, HsafaChat, HsafaProvider, type MainAgentAction, MessageList, type UseToggleReturn, useAgentStreaming, useAutoScroll, useChatStorage, useFileUpload, useHsafa, useHsafaAction, useHsafaComponent, useStreaming, useToggle };
+/**
+ * Component Registry for custom UI components
+ * Allows users to register their own React components to be rendered in chat responses
+ */
+
+interface UIComponentProps {
+    props: any;
+    resolvedColors?: any;
+}
+declare class ComponentRegistry {
+    private components;
+    /**
+     * Register a custom UI component
+     * @param name - The component name (should match the 'component' field from the agent response)
+     * @param component - The React component to render
+     */
+    register(name: string, component: ComponentType<UIComponentProps>): void;
+    /**
+     * Unregister a component
+     * @param name - The component name to remove
+     */
+    unregister(name: string): void;
+    /**
+     * Get a registered component
+     * @param name - The component name
+     * @returns The component or undefined if not found
+     */
+    get(name: string): ComponentType<UIComponentProps> | undefined;
+    /**
+     * Check if a component is registered
+     * @param name - The component name
+     */
+    has(name: string): boolean;
+    /**
+     * Clear all registered components
+     */
+    clear(): void;
+    /**
+     * Get all registered component names
+     */
+    getRegisteredNames(): string[];
+}
+declare const registry: ComponentRegistry;
+
+/**
+ * getDomComponents - Scan and analyze all interactive DOM elements inside ContentContainer
+ *
+ * Returns a structured list of all inputs, buttons, links, and interactive elements
+ * that the agent can interact with using the web controller tools.
+ */
+interface DomComponent {
+    id: string | null;
+    tag: string;
+    type?: string;
+    name?: string;
+    label?: string;
+    placeholder?: string;
+    value?: string | boolean | string[];
+    options?: Array<{
+        value: string;
+        label: string;
+        selected: boolean;
+        disabled: boolean;
+    }>;
+    checked?: boolean;
+    disabled?: boolean;
+    required?: boolean;
+    className?: string;
+    text?: string;
+    href?: string;
+    role?: string;
+    ariaLabel?: string;
+    selector?: string;
+    isVisible: boolean;
+    isInteractive: boolean;
+}
+interface GetDomComponentsOptions {
+    includeHidden?: boolean;
+    selector?: string;
+    what?: 'inputs' | 'content';
+    limit?: number;
+}
+interface GetDomComponentsResult {
+    ok: boolean;
+    components: DomComponent[];
+    count: number;
+    total: number;
+    truncated?: boolean;
+    containerFound: boolean;
+    error?: string;
+}
+declare function getDomComponents(options?: GetDomComponentsOptions): Promise<GetDomComponentsResult>;
+
+/**
+ * CursorController
+ *
+ * Mount this component once on a page (e.g. in the demo at `/demo`). It registers a
+ * global function `window.__cursorGuide(stepsOrTarget, options?)` that moves a fake
+ * cursor to a target and optionally performs actions (click, drag).
+ *
+ * In `app/demo/page.tsx`, a convenience wrapper `guideCursorTo(targetOrSteps, options?)`
+ * is also exported and exposed globally as `window.guideCursorTo`.
+ *
+ * Quick examples (run in DevTools on /demo):
+ * ```js
+ * // Move to a screen position
+ * await window.guideCursorTo({ position: { x: 140, y: 160 } }, { durationMs: 700 });
+ *
+ * // Click an element by selector or id
+ * await window.guideCursorTo('#submitBtn', { action: 'click', anchor: 'center' });
+ *
+ * // Drag from one element to another
+ * await window.guideCursorTo({ selector: '#cardBacklog0' }, { action: 'drag', dragTo: '#doingDrop' });
+ *
+ * // Multi-step sequence
+ * await window.guideCursorTo([
+ *   { target: '#tabStats', action: 'click', options: { durationMs: 600 } },
+ *   { target: { position: { x: 100, y: 120 } } },
+ *   { target: '#progressStartBtn', action: 'click' },
+ * ]);
+ * ```
+ *
+ * Options highlights (see `GuideOptions`):
+ * - action: 'none' | 'click' | 'drag'
+ * - durationMs, easing: control motion speed/curve
+ * - path: 'straight' | 'curve', curveStrength, curveDirection
+ * - anchor: where inside the element to aim (e.g. 'center', 'top-left' or {x:0..1,y:0..1})
+ * - cursorHotspot: px offset to the click location
+ * - dragTo: target for drag action
+ */
+type GuideAction = "none" | "click" | "drag";
+type GuideTarget = string | Element | {
+    selector: string;
+    nth?: number;
+    within?: Element | string;
+} | {
+    position: {
+        x: number;
+        y: number;
+    };
+};
+type Anchor = "center" | "top-left" | "bottom-right" | {
+    x: number;
+    y: number;
+};
+type GuideOptions = {
+    action?: GuideAction;
+    durationMs?: number;
+    easing?: "ease" | "ease-in" | "ease-out" | "ease-in-out" | "linear";
+    offset?: {
+        x?: number;
+        y?: number;
+    };
+    highlight?: boolean;
+    path?: "straight" | "curve";
+    curveStrength?: number;
+    curveDirection?: "auto" | "left" | "right";
+    anchor?: Anchor;
+    cursorHotspot?: {
+        x?: number;
+        y?: number;
+    };
+    dragTo?: GuideTarget;
+};
+type GuideStep = {
+    target: GuideTarget;
+    action?: GuideAction;
+    options?: GuideOptions;
+};
+type GuideStepResult = {
+    ok: boolean;
+    action: GuideAction;
+    targetKind: "element" | "position";
+    durationMs: number;
+    clickedElementId?: string | null;
+    error?: string;
+};
+type GuideRunResult = {
+    ok: boolean;
+    steps: GuideStepResult[];
+};
+declare function CursorController(): null;
+
+/**
+ * guideCursor - Wrapper for window.__cursorGuide
+ *
+ * Move the visual cursor to elements and perform click/drag actions.
+ * Requires CursorController component to be mounted on the page.
+ */
+
+interface GuideCursorOptions extends GuideOptions {
+}
+/**
+ * Guide the cursor to a target element or position
+ *
+ * @example
+ * ```ts
+ * // Move to an element and click it
+ * await guideCursor('#submitBtn', { action: 'click' });
+ *
+ * // Move to a position
+ * await guideCursor({ position: { x: 100, y: 200 } });
+ *
+ * // Drag from one element to another
+ * await guideCursor('#item1', { action: 'drag', dragTo: '#dropzone' });
+ * ```
+ */
+declare function guideCursor(target: GuideTarget, options?: GuideCursorOptions): Promise<GuideRunResult>;
+
+/**
+ * FillInput utilities
+ *
+ * Exports two helpers for programmatically filling inputs while dispatching the
+ * same DOM events a user would normally trigger (input/change/click):
+ *
+ * - FillInput(inputId, value, options?)
+ *   Fill a single field by its element id with the provided value.
+ *
+ * - FillActiveInput(value, options?)
+ *   Fill the currently focused field without needing its id.
+ *
+ * Basic example:
+ * ```ts
+ * import { FillInput, FillActiveInput } from "./FillInput";
+ *
+ * // Fill individual fields by id
+ * await FillInput("fi_name", "Jane Doe");
+ * await FillInput("fi_email", "jane@example.com");
+ * await FillInput("fi_role_admin", true);       // radio -> check this option
+ * await FillInput("fi_country2", "sa");        // select value
+ * await FillInput("fi_tags", ["a", "c"]);     // multi-select values
+ * await FillInput("fi_newsletter", true);       // checkbox
+ * await FillInput("fi_dob", "1995-05-15");     // date input
+ * await FillInput("about", "Hello there");     // contenteditable by id
+ *
+ * // Fill the currently focused field
+ * (document.getElementById("fi_name") as HTMLElement)?.focus();
+ * await FillActiveInput("Alice");
+ * ```
+ *
+ * Notes:
+ * - Scrolling is disabled; these helpers will not scroll the page.
+ * - typingDelayMs is ignored; filling is instantaneous.
+ * - For file inputs, pass a File or File[]; browsers may restrict programmatic assignment.
+ */
+type FillInputOptions = {
+    typingDelayMs?: number;
+    scrollIntoView?: boolean;
+};
+type FillResult = {
+    ok: boolean;
+    filled: Array<{
+        key: string;
+        status: "ok" | "skipped" | "error";
+        message?: string;
+    }>;
+    errors?: string[];
+};
+declare function FillActiveInput(value: any, options?: FillInputOptions): Promise<FillResult>;
+
+export { type Anchor, Button, type ButtonProps, ContentContainer, type ContentContainerProps, CursorController, type DomComponent, FillActiveInput, type FillInputOptions, type FillResult, FloatingChatButton, type GetDomComponentsOptions, type GetDomComponentsResult, type GuideAction, type GuideCursorOptions, type GuideOptions, type GuideRunResult, type GuideStep, type GuideStepResult, type GuideTarget, HsafaChat, type HsafaChatProps, HsafaProvider, type UIComponentProps, registry as componentRegistry, guideCursor as controlCursor, getDomComponents, guideCursor, useAutoScroll, useFileUpload, useHsafa };