@guidekit/core 0.1.0-beta.1

package/dist/index.d.ts

@@ -0,0 +1,2186 @@
+/**
+ * Canonical map of every event in the GuideKit system.
+ *
+ * Keys use a `namespace:name` convention (except the top-level `error` event).
+ * Values are the payload types that accompany each event.
+ */
+interface EventMap {
+    'dom:scan-complete': {
+        pageModel: unknown;
+        durationMs: number;
+    };
+    'dom:mutation-detected': {
+        mutations: number;
+        debounced: boolean;
+    };
+    'dom:route-change': {
+        from: string;
+        to: string;
+    };
+    'llm:response-start': {
+        conversationId: string;
+    };
+    'llm:response-chunk': {
+        text: string;
+        done: boolean;
+    };
+    'llm:response-end': {
+        conversationId: string;
+        totalTokens: number;
+    };
+    'llm:tool-call': {
+        name: string;
+        arguments: Record<string, unknown>;
+    };
+    'llm:token-usage': {
+        prompt: number;
+        completion: number;
+        total: number;
+    };
+    'voice:state-change': {
+        from: string;
+        to: string;
+    };
+    'voice:transcript': {
+        text: string;
+        isFinal: boolean;
+        confidence: number;
+    };
+    'voice:tts-start': {
+        utterance: string;
+    };
+    'voice:tts-end': {
+        utterance: string;
+        durationMs: number;
+    };
+    'voice:degraded': {
+        reason: string;
+        fallback: 'text';
+    };
+    'auth:token-refreshed': {
+        expiresAt: number;
+    };
+    'auth:token-refresh-failed': {
+        error: Error;
+        attemptsRemaining: number;
+    };
+    'auth:token-expired': Record<string, never>;
+    'connectivity:state-change': {
+        state: 'online' | 'degraded' | 'offline';
+        previous: 'online' | 'degraded' | 'offline';
+    };
+    'awareness:dwell': {
+        sectionId: string;
+        durationMs: number;
+    };
+    'awareness:idle': {
+        durationMs: number;
+    };
+    'awareness:rage-click': {
+        selector: string;
+        clicks: number;
+    };
+    'awareness:section-visible': {
+        sectionId: string;
+        ratio: number;
+    };
+    'visual:spotlight-shown': {
+        selector: string;
+        sectionId?: string;
+    };
+    'visual:spotlight-dismissed': Record<string, never>;
+    'visual:tour-step': {
+        stepIndex: number;
+        totalSteps: number;
+        sectionId: string;
+    };
+    error: Error;
+}
+declare class EventBus {
+    /** Per-event listeners. Wildcard keys end with `:*`. */
+    private readonly listeners;
+    /** Listeners registered via `onAny`. */
+    private readonly anyListeners;
+    /** When true, every `emit` is logged to the console. */
+    private readonly debug;
+    constructor(options?: {
+        debug?: boolean;
+    });
+    /**
+     * Subscribe to a specific typed event.
+     *
+     * @returns An unsubscribe function.
+     */
+    on<K extends keyof EventMap>(event: K, handler: (data: EventMap[K]) => void): () => void;
+    /**
+     * Subscribe to a namespace wildcard (e.g. `'dom:*'`).
+     * The handler receives `(data, eventName)`.
+     *
+     * @returns An unsubscribe function.
+     */
+    on(event: `${string}:*`, handler: (data: unknown, eventName: string) => void): () => void;
+    /**
+     * Subscribe to **every** event emitted on the bus.
+     *
+     * @returns An unsubscribe function.
+     */
+    onAny(handler: (data: unknown, eventName: string) => void): () => void;
+    /**
+     * Emit a typed event.
+     *
+     * Handlers are invoked synchronously in registration order. If a handler
+     * throws, the error is logged and remaining handlers still execute.
+     */
+    emit<K extends keyof EventMap>(event: K, data: EventMap[K]): void;
+    /**
+     * Subscribe to a specific event, automatically unsubscribing after the
+     * first invocation.
+     *
+     * @returns An unsubscribe function (also cancels a not-yet-fired listener).
+     */
+    once<K extends keyof EventMap>(event: K, handler: (data: EventMap[K]) => void): () => void;
+    /** Remove **all** listeners from the bus. */
+    removeAll(): void;
+    /**
+     * Return the number of registered listeners.
+     *
+     * - If `event` is provided, returns the count for that specific event key
+     *   (including wildcard keys like `'dom:*'`).
+     * - If omitted, returns the total across all events plus `onAny` listeners.
+     */
+    listenerCount(event?: string): number;
+    /**
+     * Invoke a handler inside a try/catch so one misbehaving handler never
+     * prevents the remaining handlers from executing.
+     */
+    private invokeSafe;
+}
+/**
+ * Create a new {@link EventBus} instance.
+ *
+ * ```ts
+ * const bus = createEventBus({ debug: true });
+ * const unsub = bus.on('dom:scan-complete', (data) => {
+ *   console.log(data.pageModel, data.durationMs);
+ * });
+ * bus.emit('dom:scan-complete', { pageModel: {}, durationMs: 42 });
+ * unsub();
+ * ```
+ */
+declare function createEventBus(options?: {
+    debug?: boolean;
+}): EventBus;
+
+/** All translatable string keys used by the SDK UI. */
+interface I18nStrings {
+    widgetTitle: string;
+    openAssistant: string;
+    closeAssistant: string;
+    closePanel: string;
+    sendMessage: string;
+    inputPlaceholder: string;
+    listeningPlaceholder: string;
+    startVoice: string;
+    stopVoice: string;
+    statusOnline: string;
+    statusConnecting: string;
+    statusOffline: string;
+    statusListening: string;
+    statusSpeaking: string;
+    statusProcessing: string;
+    emptyStateMessage: string;
+    errorGeneric: string;
+    errorNetwork: string;
+    errorMicDenied: string;
+    errorRateLimit: string;
+    greetingMessage: string;
+    idleHelpMessage: string;
+    voiceDegradedNotice: string;
+    quietModeOn: string;
+    quietModeOff: string;
+}
+type SupportedLocale = 'en' | 'es' | 'fr' | 'de' | 'ja' | 'zh' | 'ar' | 'pt';
+type LocaleInput = SupportedLocale | 'auto' | I18nStrings;
+interface I18nOptions {
+    locale?: LocaleInput;
+    debug?: boolean;
+}
+declare class I18n {
+    private strings;
+    private resolvedLocale;
+    private debug;
+    constructor(options?: I18nOptions);
+    /** Get a translated string by key. */
+    t(key: keyof I18nStrings): string;
+    /** Get all strings for the current locale. */
+    getStrings(): I18nStrings;
+    /** Change the current locale at runtime. */
+    setLocale(locale: LocaleInput): void;
+    /** The current resolved locale code (e.g. 'en', 'fr', or 'custom'). */
+    get currentLocale(): string;
+    private resolve;
+}
+
+/**
+ * @module @guidekit/core/types
+ *
+ * Shared TypeScript types for the GuideKit SDK.
+ * All types used across packages are defined and exported from this module.
+ */
+/**
+ * Reference type matching the GuideKitError class shape defined in ../errors/.
+ * Used throughout the type system to avoid circular imports. The actual class
+ * implementation lives in the errors module; this is the structural contract.
+ */
+type GuideKitErrorType = Error & {
+    readonly code: string;
+    readonly provider?: string;
+    readonly recoverable: boolean;
+    readonly suggestion: string;
+    readonly docsUrl: string;
+};
+/** Metadata produced by the DOM scanner indicating work performed. */
+interface ScanMetadata {
+    totalSectionsFound: number;
+    sectionsIncluded: number;
+    totalNodesScanned: number;
+    scanBudgetExhausted: boolean;
+}
+/** A scored, labelled section of the current page. */
+interface PageSection {
+    id: string;
+    selector: string;
+    tagName: string;
+    label: string;
+    summary: string;
+    isVisible: boolean;
+    visibilityRatio: number;
+    score: number;
+    landmark?: string;
+    hasInteractiveElements: boolean;
+    depth: number;
+}
+/** A navigation link discovered on the page. */
+interface NavItem {
+    label: string;
+    href: string;
+    isCurrent: boolean;
+    selector: string;
+}
+/** An interactive element (button, link, input, etc.) on the page. */
+interface InteractiveElement {
+    selector: string;
+    tagName: string;
+    type?: string;
+    label: string;
+    role?: string;
+    isDisabled: boolean;
+    guideKitTarget?: string;
+}
+/** A single field inside a form. */
+interface FormField {
+    selector: string;
+    name: string;
+    type: string;
+    label: string;
+    isRequired: boolean;
+    hasError: boolean;
+    errorMessage?: string;
+}
+/** Summary representation of a <form> element. */
+interface FormSummary {
+    selector: string;
+    id?: string;
+    action?: string;
+    fields: FormField[];
+    hasValidationErrors: boolean;
+}
+/** An overlay (modal, drawer, dropdown, popover) currently present in the DOM. */
+interface OverlayElement {
+    selector: string;
+    type: 'modal' | 'drawer' | 'dropdown' | 'popover';
+    label: string;
+    isVisible: boolean;
+}
+/**
+ * Complete snapshot of the current page produced by the page-awareness scanner.
+ * Sent to the LLM as grounding context on every turn.
+ */
+interface PageModel {
+    url: string;
+    title: string;
+    meta: {
+        description: string;
+        h1: string | null;
+        language: string;
+    };
+    sections: PageSection[];
+    navigation: NavItem[];
+    interactiveElements: InteractiveElement[];
+    forms: FormSummary[];
+    activeOverlays: OverlayElement[];
+    viewport: {
+        width: number;
+        height: number;
+        orientation: 'portrait' | 'landscape';
+    };
+    allSectionsSummary: string[];
+    hash: string;
+    timestamp: number;
+    scanMetadata: ScanMetadata;
+}
+/** Discriminated union describing every possible state the agent can be in. */
+type AgentState = {
+    status: 'idle';
+} | {
+    status: 'listening';
+    durationMs: number;
+} | {
+    status: 'processing';
+    transcript: string;
+} | {
+    status: 'speaking';
+    utterance: string;
+} | {
+    status: 'error';
+    error: GuideKitErrorType;
+};
+/** Speech-to-text provider configuration. */
+type STTConfig = {
+    provider: 'deepgram';
+    apiKey: string;
+    model?: 'nova-2' | 'nova-3';
+} | {
+    provider: 'assemblyai';
+    apiKey: string;
+};
+/** Text-to-speech provider configuration. */
+type TTSConfig = {
+    provider: 'elevenlabs';
+    apiKey: string;
+    voiceId?: string;
+} | {
+    provider: 'cartesia';
+    apiKey: string;
+    voiceId?: string;
+};
+/** Large language model provider configuration. */
+type LLMConfig = {
+    provider: 'gemini';
+    apiKey: string;
+    model?: 'gemini-2.5-flash' | 'gemini-2.5-pro';
+} | {
+    provider: 'openai';
+    apiKey: string;
+    model?: 'gpt-4o' | 'gpt-4o-mini';
+};
+/** Top-level options that control SDK behaviour. */
+interface GuideKitOptions {
+    locale?: string | 'auto';
+    mode?: 'voice' | 'text' | 'auto';
+    greetOnFirstVisit?: boolean;
+    spotlightColor?: string;
+    consentRequired?: boolean;
+    debug?: boolean;
+    rateLimits?: {
+        maxLLMCallsPerMinute?: number;
+        maxSTTMinutesPerSession?: number;
+        maxTTSCharsPerSession?: number;
+    };
+    clickableSelectors?: {
+        allow?: string[];
+        deny?: string[];
+    };
+    safetySettings?: Record<string, string>;
+    /** Maximum character length for user messages. Default: 10000. */
+    maxMessageLength?: number;
+}
+/** Configuration for the assistant persona. */
+interface AgentConfig {
+    name?: string;
+    greeting?: string;
+    personality?: string;
+}
+/** Visual customisation of the GuideKit widget. */
+interface GuideKitTheme {
+    primaryColor?: string;
+    position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+    borderRadius?: string;
+}
+/** A single entry in the developer-supplied content map. */
+interface ContentMapEntry {
+    description: string;
+    facts?: string[];
+}
+/** Static content map keyed by section ID or URL pattern. */
+type ContentMap = Record<string, ContentMapEntry>;
+/** Callback-based content map for dynamic or async lookups. */
+type ContentMapFunction = (sectionId: string) => ContentMapEntry | null | Promise<ContentMapEntry | null>;
+/** Accepted input types for the content map prop. */
+type ContentMapInput = ContentMap | ContentMapFunction;
+/** A single turn in the conversation history. */
+interface ConversationTurn {
+    role: 'user' | 'assistant';
+    content: string;
+    timestamp: number;
+}
+/** Serialisable session state for persistence across page navigations. */
+interface SessionState {
+    conversationHistory: ConversationTurn[];
+    currentUrl: string;
+    agentStatus: AgentState['status'];
+    userPreference: 'voice' | 'text';
+    quietMode: boolean;
+    totalSizeBytes: number;
+}
+/** Network connectivity state observed by the SDK. */
+type ConnectionState = 'online' | 'degraded' | 'offline';
+/** An event emitted by the SDK via the `onEvent` callback. */
+interface GuideKitEvent {
+    type: string;
+    data: Record<string, unknown>;
+    timestamp: number;
+}
+/** Props accepted by the `<GuideKitProvider>` React component. */
+interface GuideKitProviderProps {
+    tokenEndpoint?: string;
+    stt?: STTConfig;
+    tts?: TTSConfig;
+    llm?: LLMConfig;
+    agent?: AgentConfig;
+    contentMap?: ContentMapInput;
+    options?: GuideKitOptions;
+    theme?: GuideKitTheme;
+    locale?: string | 'auto';
+    instanceId?: string;
+    rootElement?: HTMLElement;
+    onError?: (error: GuideKitErrorType) => void;
+    onEvent?: (event: GuideKitEvent) => void;
+    onReady?: () => void;
+    onBeforeLLMCall?: (context: {
+        systemPrompt: string;
+        userMessage: string;
+        conversationHistory: Array<{
+            role: string;
+            content: string;
+        }>;
+    }) => {
+        systemPrompt: string;
+        userMessage: string;
+        conversationHistory: Array<{
+            role: string;
+            content: string;
+        }>;
+    } | Promise<{
+        systemPrompt: string;
+        userMessage: string;
+        conversationHistory: Array<{
+            role: string;
+            content: string;
+        }>;
+    }>;
+    children?: unknown;
+}
+/** Definition of a tool that can be invoked by the LLM. */
+interface ToolDefinition {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    schemaVersion: number;
+}
+/** A tool invocation request returned by the LLM. */
+interface ToolCall {
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+}
+/** A chunk of streamed text from the LLM. */
+interface TextChunk {
+    text: string;
+    done: boolean;
+}
+/**
+ * Adapter interface that each LLM provider must implement.
+ * Handles format conversion between GuideKit's internal representation
+ * and the provider-specific wire format.
+ */
+interface LLMProviderAdapter {
+    formatTools(tools: ToolDefinition[]): unknown;
+    formatConversation(history: ConversationTurn[]): unknown;
+    parseResponse(stream: ReadableStream): AsyncIterable<TextChunk | ToolCall>;
+    formatToolResult(callId: string, result: unknown): unknown;
+}
+/** Decoded payload of a GuideKit session token. */
+interface TokenPayload {
+    sessionId: string;
+    expiresAt: number;
+    audience: string[];
+    permissions: string[];
+    userId?: string;
+    metadata?: Record<string, unknown>;
+    iat: number;
+}
+/** Response returned by the token endpoint. */
+interface TokenResponse {
+    token: string;
+    expiresIn: number;
+    expiresAt: number;
+}
+/** Options for `createSessionToken()` on the server side. */
+interface CreateSessionTokenOptions {
+    signingSecret: string | string[];
+    deepgramKey?: string;
+    elevenlabsKey?: string;
+    geminiKey?: string;
+    expiresIn?: string;
+    allowedOrigins?: string[];
+    permissions?: string[];
+    userId?: string;
+    sessionId?: string;
+    metadata?: Record<string, unknown>;
+}
+/** Shape of the external store consumed by React hooks. */
+interface GuideKitStore {
+    status: {
+        isReady: boolean;
+        agentState: AgentState;
+        error: GuideKitErrorType | null;
+    };
+    voice: {
+        isListening: boolean;
+        isSpeaking: boolean;
+    };
+    /** Whether the user has granted privacy consent. Always `true` when `consentRequired` is not enabled. Managed by the React widget layer. */
+    hasConsent?: boolean;
+}
+
+/**
+ * Canonical error codes emitted by the SDK.
+ * Keyed as `DOMAIN_DETAIL` so consumers can match on prefixes or exact values.
+ */
+declare const ErrorCodes: {
+    readonly AUTH_INVALID_KEY: "AUTH_INVALID_KEY";
+    readonly AUTH_EXPIRED_TOKEN: "AUTH_EXPIRED_TOKEN";
+    readonly AUTH_TOKEN_REFRESH_FAILED: "AUTH_TOKEN_REFRESH_FAILED";
+    readonly AUTH_ENDPOINT_FAILED: "AUTH_ENDPOINT_FAILED";
+    readonly CONFIG_INVALID_PROVIDER: "CONFIG_INVALID_PROVIDER";
+    readonly CONFIG_MISSING_REQUIRED: "CONFIG_MISSING_REQUIRED";
+    readonly INIT_SHADOW_DOM_FAILED: "INIT_SHADOW_DOM_FAILED";
+    readonly INIT_BROWSER_UNSUPPORTED: "INIT_BROWSER_UNSUPPORTED";
+    readonly RATE_LIMIT_PROVIDER: "RATE_LIMIT_PROVIDER";
+    readonly RATE_LIMIT_CLIENT: "RATE_LIMIT_CLIENT";
+    readonly RESOURCE_EXHAUSTED_LLM: "RESOURCE_EXHAUSTED_LLM";
+    readonly RESOURCE_EXHAUSTED_STT: "RESOURCE_EXHAUSTED_STT";
+    readonly RESOURCE_EXHAUSTED_TTS: "RESOURCE_EXHAUSTED_TTS";
+    readonly PERMISSION_MIC_DENIED: "PERMISSION_MIC_DENIED";
+    readonly PERMISSION_MIC_UNAVAILABLE: "PERMISSION_MIC_UNAVAILABLE";
+    readonly NETWORK_WEBSOCKET_FAILED: "NETWORK_WEBSOCKET_FAILED";
+    readonly NETWORK_CONNECTION_LOST: "NETWORK_CONNECTION_LOST";
+    readonly NETWORK_TIMEOUT: "NETWORK_TIMEOUT";
+    readonly TIMEOUT_STT_CONNECT: "TIMEOUT_STT_CONNECT";
+    readonly TIMEOUT_LLM_RESPONSE: "TIMEOUT_LLM_RESPONSE";
+    readonly TIMEOUT_TTS_CONNECT: "TIMEOUT_TTS_CONNECT";
+    readonly TIMEOUT_TTS_FIRST_AUDIO: "TIMEOUT_TTS_FIRST_AUDIO";
+    readonly BROWSER_NO_WEB_AUDIO: "BROWSER_NO_WEB_AUDIO";
+    readonly BROWSER_NO_WASM: "BROWSER_NO_WASM";
+    readonly VAD_PACKAGE_MISSING: "VAD_PACKAGE_MISSING";
+    readonly CONTENT_FILTER_TRIGGERED: "CONTENT_FILTER_TRIGGERED";
+    readonly PRIVACY_HOOK_CANCELLED: "PRIVACY_HOOK_CANCELLED";
+};
+/** Union of every known error code string. */
+type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+type Provider = 'deepgram' | 'elevenlabs' | 'gemini' | 'openai';
+interface GuideKitErrorOptions {
+    code: string;
+    message: string;
+    provider?: Provider;
+    recoverable: boolean;
+    suggestion: string;
+    docsUrl?: string;
+    cause?: Error;
+}
+/**
+ * Root error for every failure surfaced by the GuideKit SDK.
+ *
+ * Every instance carries structured metadata so UI layers can present
+ * actionable feedback without parsing message strings.
+ */
+declare class GuideKitError extends Error {
+    readonly code: string;
+    readonly provider?: Provider;
+    readonly recoverable: boolean;
+    readonly suggestion: string;
+    readonly docsUrl: string;
+    constructor(options: GuideKitErrorOptions);
+}
+/** Wrong or expired API key / token. */
+declare class AuthenticationError extends GuideKitError {
+    constructor(options: Omit<GuideKitErrorOptions, 'recoverable'> & {
+        recoverable?: boolean;
+    });
+}
+/** Invalid provider configuration supplied at init time. */
+declare class ConfigurationError extends GuideKitError {
+    constructor(options: Omit<GuideKitErrorOptions, 'recoverable'> & {
+        recoverable?: boolean;
+    });
+}
+/** SDK startup failure (Shadow DOM creation, browser too old, etc.). */
+declare class InitializationError extends GuideKitError {
+    constructor(options: Omit<GuideKitErrorOptions, 'recoverable'> & {
+        recoverable?: boolean;
+    });
+}
+/** Provider-side rate limit hit. Includes a retry hint. */
+declare class RateLimitError extends GuideKitError {
+    readonly retryAfterMs: number;
+    constructor(options: GuideKitErrorOptions & {
+        retryAfterMs: number;
+    });
+}
+/** Client-side cost / usage limits exhausted. */
+declare class ResourceExhaustedError extends GuideKitError {
+    constructor(options: Omit<GuideKitErrorOptions, 'recoverable'> & {
+        recoverable?: boolean;
+    });
+}
+/** Microphone permission denied or device not available. */
+declare class PermissionError extends GuideKitError {
+    constructor(options: Omit<GuideKitErrorOptions, 'recoverable'> & {
+        recoverable?: boolean;
+    });
+}
+/** WebSocket dropped, HTTP connection failed, etc. */
+declare class NetworkError extends GuideKitError {
+    constructor(options: Omit<GuideKitErrorOptions, 'recoverable'> & {
+        recoverable?: boolean;
+    });
+}
+/** An operation exceeded its deadline. */
+declare class TimeoutError extends GuideKitError {
+    readonly operationName: string;
+    readonly timeoutMs: number;
+    constructor(options: GuideKitErrorOptions & {
+        operationName: string;
+        timeoutMs: number;
+    });
+}
+/** Missing browser capability (Web Audio, WASM, VAD). */
+declare class BrowserSupportError extends GuideKitError {
+    constructor(options: Omit<GuideKitErrorOptions, 'recoverable'> & {
+        recoverable?: boolean;
+    });
+}
+/** LLM safety / content filter triggered. */
+declare class ContentFilterError extends GuideKitError {
+    constructor(options: Omit<GuideKitErrorOptions, 'recoverable'> & {
+        recoverable?: boolean;
+    });
+}
+/**
+ * Narrows an unknown caught value to `GuideKitError`.
+ *
+ * ```ts
+ * try { ... } catch (err) {
+ *   if (isGuideKitError(err)) {
+ *     console.log(err.code, err.suggestion);
+ *   }
+ * }
+ * ```
+ */
+declare function isGuideKitError(error: unknown): error is GuideKitError;
+
+/** Result of a health check on a single service. */
+interface HealthCheckStatus {
+    status: 'ok' | 'degraded' | 'unavailable' | 'not-configured';
+    latencyMs?: number;
+    error?: string;
+}
+/** Full health check result. */
+interface HealthCheckResult {
+    llm: HealthCheckStatus;
+    stt: HealthCheckStatus;
+    tts: HealthCheckStatus;
+    mic: HealthCheckStatus;
+    overall: 'ok' | 'degraded' | 'unavailable';
+}
+/** Context passed to onBeforeLLMCall for privacy filtering. */
+interface BeforeLLMCallContext {
+    systemPrompt: string;
+    userMessage: string;
+    conversationHistory: Array<{
+        role: string;
+        content: string;
+    }>;
+}
+interface GuideKitCoreOptions {
+    tokenEndpoint?: string;
+    stt?: STTConfig;
+    tts?: TTSConfig;
+    llm?: LLMConfig;
+    agent?: AgentConfig;
+    contentMap?: ContentMapInput;
+    options?: GuideKitOptions;
+    instanceId?: string;
+    rootElement?: HTMLElement;
+    onError?: (error: GuideKitError) => void;
+    onEvent?: (event: GuideKitEvent) => void;
+    onReady?: () => void;
+    /**
+     * Privacy hook: called before every LLM request. Return modified context
+     * or throw to cancel the request. Use for custom PII scrubbing.
+     */
+    onBeforeLLMCall?: (context: BeforeLLMCallContext) => BeforeLLMCallContext | Promise<BeforeLLMCallContext>;
+}
+declare class GuideKitCore {
+    readonly instanceId: string;
+    readonly bus: EventBus;
+    private resourceManager;
+    private domScanner;
+    private contextManager;
+    private llmOrchestrator;
+    private connectionManager;
+    private navigationController;
+    private voicePipeline;
+    private visualGuidance;
+    private toolExecutor;
+    private awarenessSystem;
+    private proactiveEngine;
+    private rateLimiter;
+    private _i18n;
+    private tokenManager;
+    private _isReady;
+    private _agentState;
+    private _currentPageModel;
+    private readonly _options;
+    private _debug;
+    private _sendInFlight;
+    private _instanceAbortController;
+    private _initPromise;
+    private storeListeners;
+    private _storeSnapshot;
+    private customActions;
+    constructor(options: GuideKitCoreOptions);
+    init(): Promise<void>;
+    private _doInit;
+    sendText(message_: string): Promise<string>;
+    /** Get the current page model. */
+    get pageModel(): PageModel | null;
+    /** Whether the SDK has been fully initialized. */
+    get isReady(): boolean;
+    /** Current agent state. */
+    get agentState(): AgentState;
+    /** Current auth token string, or null if not using token-based auth. */
+    get currentToken(): string | null;
+    subscribe(listener: () => void): () => void;
+    getSnapshot(): GuideKitStore;
+    registerAction(actionId: string, action: {
+        description: string;
+        parameters: Record<string, unknown>;
+        handler: (params: Record<string, unknown>) => Promise<unknown>;
+    }): void;
+    /** Start listening for voice input. Initializes voice pipeline on first call. */
+    startListening(): Promise<void>;
+    /** Stop listening for voice input. */
+    stopListening(): void;
+    /** Stop current TTS playback (barge-in). */
+    stopSpeaking(): void;
+    /** Whether voice pipeline is available. */
+    get hasVoice(): boolean;
+    /** Highlight an element by sectionId or CSS selector. */
+    highlight(params: {
+        sectionId?: string;
+        selector?: string;
+        tooltip?: string;
+        position?: 'top' | 'bottom' | 'left' | 'right' | 'auto';
+    }): boolean;
+    /** Dismiss the current spotlight highlight. */
+    dismissHighlight(): void;
+    /** Smooth scroll to a section. */
+    scrollToSection(sectionId: string, offset?: number): void;
+    /** Smooth scroll to a CSS selector. */
+    scrollToSelector(selector: string, offset?: number): void;
+    /** Start a guided tour. */
+    startTour(sectionIds: string[], mode?: 'auto' | 'manual'): void;
+    /** Advance to next tour step. */
+    nextTourStep(): void;
+    /** Go back to previous tour step. */
+    prevTourStep(): void;
+    /** Stop the guided tour. */
+    stopTour(): void;
+    /** Navigate to a same-origin URL. */
+    navigate(href: string): Promise<boolean>;
+    setPageContext(context: Record<string, unknown>): void;
+    /** Get the i18n instance for localized strings. */
+    get i18n(): I18n;
+    /** Get/set quiet mode on proactive triggers. */
+    get quietMode(): boolean;
+    set quietMode(value: boolean);
+    /** Get/set user preference (voice/text). */
+    get userPreference(): 'voice' | 'text';
+    set userPreference(value: 'voice' | 'text');
+    /** Get the rate limiter for monitoring usage. */
+    get rateLimiterState(): RateLimiterState;
+    /**
+     * Check health of all connected services.
+     * Returns per-service status and an overall assessment.
+     */
+    checkHealth(): Promise<HealthCheckResult>;
+    destroy(): Promise<void>;
+    private setAgentState;
+    private notifyStoreListeners;
+    private buildSnapshot;
+    /**
+     * Register all built-in tool handlers with the ToolExecutor.
+     * Called once during init() after VisualGuidance and all subsystems are ready.
+     */
+    private registerBuiltinTools;
+    private getToolDefinitions;
+}
+
+/**
+ * A disposable resource that the SDK tracks for deterministic cleanup.
+ * Each resource has a unique name and a cleanup function that may be async.
+ */
+interface Resource {
+    name: string;
+    cleanup: () => void | Promise<void>;
+}
+/** Lifecycle states for a ResourceManager instance. */
+type ResourceManagerState = 'initializing' | 'ready' | 'tearing_down' | 'torn_down';
+/**
+ * Manages the lifecycle of SDK resources (AbortControllers, event listeners,
+ * WebSocket connections, etc.) and ensures deterministic cleanup on unmount.
+ *
+ * Resources are cleaned up sequentially — order matters because later
+ * resources may depend on earlier ones still being alive during their own
+ * cleanup phase.
+ */
+declare class ResourceManager {
+    readonly instanceId: string;
+    private _state;
+    private readonly _resources;
+    private _destroyPromise;
+    private _destroyCancelled;
+    constructor(instanceId?: string);
+    /** Current lifecycle state. */
+    get state(): ResourceManagerState;
+    /** Number of currently registered resources. */
+    get resourceCount(): number;
+    /**
+     * Register a resource for cleanup tracking.
+     *
+     * @throws If the manager has already been torn down.
+     */
+    register(resource: Resource): void;
+    /**
+     * Unregister a specific resource by name without invoking its cleanup.
+     */
+    unregister(name: string): void;
+    /**
+     * Create a tracked AbortController. On destroy, its `abort()` method will
+     * be called automatically.
+     */
+    createAbortController(name: string): AbortController;
+    /** Transition from `initializing` to `ready`. */
+    markReady(): void;
+    /**
+     * Destroy all registered resources sequentially.
+     *
+     * Each resource gets up to {@link CLEANUP_TIMEOUT_MS}ms to complete.
+     * If cleanup exceeds the timeout a warning is logged and the manager
+     * proceeds to the next resource.
+     *
+     * After all resources are processed the state transitions to `torn_down`.
+     * Calling `destroy()` multiple times returns the same promise.
+     */
+    destroy(): Promise<void>;
+    /**
+     * Cancel a pending destroy, transitioning back to `ready`.
+     *
+     * This exists to support React 18 StrictMode which unmounts then
+     * immediately re-mounts components. If the re-mount arrives while
+     * teardown is still in progress, cancelling prevents resource loss.
+     *
+     * @returns `true` if teardown was pending and has been cancelled.
+     *          `false` if already torn down or not currently tearing down.
+     */
+    cancelDestroy(): boolean;
+    /** Sequential cleanup with per-resource timeout. */
+    private _performDestroy;
+}
+/**
+ * Ref-counted singleton guard keyed by `instanceId`.
+ *
+ * - `acquire()` increments the ref count (or creates the manager).
+ * - `release()` decrements the ref count. When it reaches 0 a
+ *   `setTimeout(0)` is scheduled to allow React StrictMode re-mount to
+ *   reclaim the instance before it is destroyed.
+ * - If a mount arrives during `TEARING_DOWN`, the teardown is cancelled
+ *   and the manager transitions back to `READY`.
+ */
+declare class SingletonGuard {
+    private static readonly _entries;
+    /**
+     * Acquire (or create) a ResourceManager for the given instanceId.
+     *
+     * @param instanceId Unique identifier for the singleton slot.
+     * @param factory    Called to create a fresh ResourceManager when none
+     *                   exists or the previous one has been torn down.
+     */
+    static acquire(instanceId: string, factory: () => ResourceManager): ResourceManager;
+    /**
+     * Release a reference to the manager. When the ref count drops to 0 a
+     * `setTimeout(0)` delay is introduced before destruction so that React
+     * StrictMode's synchronous re-mount can reclaim the instance.
+     */
+    static release(instanceId: string): void;
+    /**
+     * Retrieve a manager by instanceId without affecting the ref count.
+     * Returns `undefined` if no manager exists for the given id.
+     */
+    static get(instanceId: string): ResourceManager | undefined;
+}
+
+/**
+ * @module @guidekit/core/dom
+ *
+ * DOM intelligence engine for the GuideKit SDK.
+ * Scans the current page and builds a structured PageModel that serves as
+ * grounding context for the LLM on every turn.
+ *
+ * Key design decisions:
+ * - SSR-safe: every browser API is guarded behind `typeof document/window`.
+ * - Privacy-first: password fields and PII patterns are never captured.
+ * - Budget-constrained: hard limits on node count and tree depth prevent
+ *   runaway scans on large pages.
+ * - Mutation-resilient: MutationObserver is throttled and circuit-broken.
+ */
+
+interface DOMScannerOptions {
+    rootElement?: HTMLElement;
+    debug?: boolean;
+    maxNodes?: number;
+    maxSections?: number;
+    maxDepth?: number;
+}
+declare class DOMScanner {
+    private readonly root;
+    private readonly debug;
+    private readonly maxNodes;
+    private readonly maxSections;
+    private readonly maxDepth;
+    private cachedModel;
+    private visibilityMap;
+    private observer;
+    private mutationCount;
+    private mutationWindowStart;
+    private circuitBroken;
+    private circuitBrokenTimer;
+    private debounceTimer;
+    private lastScanTime;
+    constructor(options?: DOMScannerOptions);
+    /** Perform a full scan and return a PageModel. */
+    scan(): PageModel;
+    /**
+     * Set up a MutationObserver that rescans on DOM changes.
+     * Returns a cleanup function to disconnect the observer.
+     */
+    observe(callback: (model: PageModel) => void): () => void;
+    /** Update visibility data from an IntersectionObserver. */
+    updateVisibility(entries: IntersectionObserverEntry[]): void;
+    /** Get the current cached page model. */
+    get currentModel(): PageModel | null;
+    private startObserving;
+    private triggerRescan;
+    private cleanup;
+    private isSectionCandidate;
+    private extractSections;
+    private buildPageSection;
+    private getSectionLabel;
+    private getLandmark;
+    private scoreSection;
+    private extractNavigation;
+    private extractInteractiveElements;
+    private extractForms;
+    private extractFormFields;
+    private extractOverlays;
+    private classifyOverlay;
+    private extractMeta;
+    private getDepth;
+    private isInViewport;
+    private generateHash;
+    private emptyModel;
+    private log;
+}
+
+/**
+ * @module @guidekit/core/context
+ *
+ * Context manager for the GuideKit SDK.
+ * Assembles the LLM system prompt from the current page model, manages
+ * conversation history with automatic eviction, resolves content-map entries,
+ * and persists session state across page navigations via sessionStorage.
+ */
+
+interface ContextManagerOptions {
+    agent?: AgentConfig;
+    contentMap?: ContentMapInput;
+    maxTurns?: number;
+    maxSessionSizeBytes?: number;
+    tokenBudget?: number;
+    debug?: boolean;
+}
+declare class ContextManager {
+    private agent;
+    private contentMap;
+    private maxTurns;
+    private maxSessionSizeBytes;
+    private tokenBudget;
+    private debug;
+    private history;
+    private contentCache;
+    private _userPreference;
+    private _quietMode;
+    private _pageContext;
+    constructor(options?: ContextManagerOptions);
+    /**
+     * Build the full system prompt from the current page model and available
+     * tools. The output is capped at `tokenBudget` characters so it fits
+     * comfortably inside the LLM context window alongside conversation history.
+     */
+    buildSystemPrompt(pageModel: PageModel, tools: ToolDefinition[]): string;
+    /** Append a turn to the conversation history, enforcing size constraints. */
+    addTurn(turn: ConversationTurn): void;
+    /** Return a copy of the current conversation history. */
+    getHistory(): ConversationTurn[];
+    /** Clear all conversation history. */
+    clearHistory(): void;
+    /**
+     * Resolve a `ContentMapEntry` for the given `sectionId`.
+     *
+     * - Static maps are looked up directly.
+     * - Function-based maps are called with a 2-second timeout.
+     * - Results are cached for 30 seconds per section ID.
+     */
+    getContent(sectionId: string): Promise<ContentMapEntry | null>;
+    /** Replace the content map used for section lookups. Clears the cache. */
+    setContentMap(contentMap: ContentMapInput): void;
+    get userPreference(): 'voice' | 'text';
+    set userPreference(value: 'voice' | 'text');
+    get quietMode(): boolean;
+    set quietMode(value: boolean);
+    /** Set developer-supplied page context (merged into system prompt). */
+    setPageContext(context: Record<string, unknown>): void;
+    /** Get the current page context. */
+    getPageContext(): Record<string, unknown>;
+    /** Clear all page context. */
+    clearPageContext(): void;
+    /** Persist the current session state to `sessionStorage`. */
+    saveSession(): void;
+    /** Restore a previously persisted session from `sessionStorage`. */
+    restoreSession(): SessionState | null;
+    /** Build the current session state snapshot. */
+    getSessionState(): SessionState;
+    private buildRoleSection;
+    private buildCurrentPageSection;
+    private buildPageSectionsSection;
+    private buildNavigationSection;
+    private buildInteractiveElementsSection;
+    private buildFormsSection;
+    private buildViewportSection;
+    private buildToolsSection;
+    private buildPageContextSection;
+    private buildGuidelinesSection;
+    /**
+     * When the assembled prompt exceeds the budget, progressively trim
+     * lower-priority sections to fit.
+     */
+    private trimPromptToBudget;
+    /**
+     * Enforce `maxTurns` and `maxSessionSizeBytes` constraints on the
+     * conversation history. When the history approaches 80% of `maxTurns`,
+     * the oldest turns are summarised into a single recap turn.
+     */
+    private enforceHistoryLimits;
+    /**
+     * Compress the oldest half of turns into a single recap turn so the
+     * context window is used more efficiently.
+     */
+    private summariseOldestTurns;
+    /** Evict oldest turns until the serialised history fits within the byte budget. */
+    private enforceByteLimit;
+    private log;
+}
+
+interface TokenUsage$1 {
+    prompt: number;
+    completion: number;
+    total: number;
+}
+/**
+ * Adapter that translates between GuideKit's internal types and the
+ * OpenAI Chat Completions API wire format. Handles streaming via SSE,
+ * tool formatting, and response parsing.
+ */
+declare class OpenAIAdapter implements LLMProviderAdapter {
+    private readonly apiKey;
+    private readonly model;
+    constructor(config: Extract<LLMConfig, {
+        provider: 'openai';
+    }>);
+    /**
+     * Convert GuideKit tool definitions into OpenAI's `tools` format.
+     * Each tool is wrapped as `{ type: 'function', function: { name, description, parameters } }`.
+     */
+    formatTools(tools: ToolDefinition[]): unknown;
+    /**
+     * Convert an array of `ConversationTurn` objects into OpenAI's messages
+     * format with `role: 'user' | 'assistant'`.
+     */
+    formatConversation(history: ConversationTurn[]): Array<{
+        role: 'user' | 'assistant';
+        content: string;
+    }>;
+    /**
+     * Parse an OpenAI SSE streaming response into an async iterable of
+     * `TextChunk` and `ToolCall` objects.
+     *
+     * The OpenAI streaming endpoint sends each chunk as a JSON object
+     * prefixed by `data: `. The final line is `data: [DONE]`.
+     * Text content arrives in `choices[0].delta.content` and tool calls
+     * arrive in `choices[0].delta.tool_calls`.
+     */
+    parseResponse(stream: ReadableStream<Uint8Array>): AsyncIterable<TextChunk | ToolCall>;
+    /**
+     * Format a tool result so it can be sent back to OpenAI as a
+     * `tool` role message with the `tool_call_id`.
+     */
+    formatToolResult(callId: string, result: unknown): {
+        role: 'tool';
+        tool_call_id: string;
+        content: string;
+    };
+    /**
+     * Build and execute a streaming request to the OpenAI Chat Completions API.
+     * Returns the raw `ReadableStream` for the response body together with
+     * the raw Response object.
+     */
+    streamRequest(params: {
+        systemPrompt: string;
+        contents: Array<{
+            role: string;
+            content: string;
+        }>;
+        tools?: unknown;
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<{
+        stream: ReadableStream<Uint8Array>;
+        response: Response;
+    }>;
+    /**
+     * Extract `TextChunk` and accumulate `ToolCall` data from a single parsed
+     * OpenAI SSE JSON object.
+     *
+     * OpenAI tool calls arrive incrementally: the first chunk for a tool call
+     * carries the `id` and `function.name`, while subsequent chunks append to
+     * `function.arguments`. We accumulate these in `pendingToolCalls` and only
+     * yield complete `ToolCall` objects when the finish_reason is 'tool_calls'
+     * or when flushed.
+     */
+    private extractChunks;
+    /**
+     * Flush all accumulated pending tool calls as complete `ToolCall` objects.
+     */
+    private flushPendingToolCalls;
+    /**
+     * Extract token usage from a parsed OpenAI response chunk.
+     * Usage data typically appears in the final chunk when `stream_options`
+     * includes `include_usage`, or in the non-streaming response.
+     * Returns `null` if no usage data is present.
+     */
+    extractUsage(parsed: Record<string, unknown>): TokenUsage$1 | null;
+    /**
+     * Check whether a parsed OpenAI chunk indicates the response was
+     * blocked by a content filter.
+     *
+     * OpenAI signals content filtering through:
+     * - `choices[].finish_reason === 'content_filter'`
+     * - `choices[].content_filter_results` with `filtered: true`
+     */
+    isContentFiltered(parsed: Record<string, unknown>): boolean;
+    /**
+     * Translate an HTTP error response from OpenAI into the appropriate
+     * GuideKit error class.
+     */
+    private handleHttpError;
+}
+
+interface TokenUsage {
+    prompt: number;
+    completion: number;
+    total: number;
+}
+/**
+ * Adapter that translates between GuideKit's internal types and the
+ * Gemini REST API wire format. Handles streaming via SSE, tool formatting,
+ * and response parsing.
+ */
+declare class GeminiAdapter implements LLMProviderAdapter {
+    private readonly apiKey;
+    private readonly model;
+    constructor(config: Extract<LLMConfig, {
+        provider: 'gemini';
+    }>);
+    /**
+     * Convert GuideKit tool definitions into Gemini's `functionDeclarations`
+     * format, wrapped inside a `tools` array.
+     */
+    formatTools(tools: ToolDefinition[]): unknown;
+    /**
+     * Convert an array of `ConversationTurn` objects into Gemini's `contents`
+     * array with `role: 'user' | 'model'`.
+     */
+    formatConversation(history: ConversationTurn[]): Array<{
+        role: string;
+        parts: Array<{
+            text: string;
+        }>;
+    }>;
+    /**
+     * Parse a Gemini SSE streaming response into an async iterable of
+     * `TextChunk` and `ToolCall` objects.
+     *
+     * The Gemini `streamGenerateContent?alt=sse` endpoint sends each chunk
+     * as a JSON object prefixed by `data: `. We parse line-by-line, extract
+     * text parts and function call parts, and yield the appropriate types.
+     */
+    parseResponse(stream: ReadableStream<Uint8Array>): AsyncIterable<TextChunk | ToolCall>;
+    /**
+     * Format a tool result so it can be sent back to Gemini as a
+     * `functionResponse` part.
+     */
+    formatToolResult(callId: string, result: unknown): {
+        role: string;
+        parts: Array<{
+            functionResponse: {
+                name: string;
+                response: {
+                    result: unknown;
+                };
+            };
+        }>;
+    };
+    /**
+     * Build and execute a streaming request to the Gemini API.
+     * Returns the raw `ReadableStream` for the response body together with
+     * a promise that resolves to token usage extracted from the final chunk.
+     */
+    streamRequest(params: {
+        systemPrompt: string;
+        contents: Array<{
+            role: string;
+            parts: Array<{
+                text: string;
+            }>;
+        }>;
+        tools?: unknown;
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<{
+        stream: ReadableStream<Uint8Array>;
+        response: Response;
+    }>;
+    /**
+     * Extract `TextChunk` and `ToolCall` items from a single parsed Gemini
+     * SSE JSON object.
+     */
+    private extractChunks;
+    /**
+     * Extract token usage from a parsed Gemini response chunk.
+     * Returns `null` if no usage metadata is present.
+     */
+    extractUsage(parsed: Record<string, unknown>): TokenUsage | null;
+    /**
+     * Check whether a parsed Gemini chunk indicates the response was
+     * blocked by a safety filter.
+     */
+    isContentFiltered(parsed: Record<string, unknown>): boolean;
+    /**
+     * Translate an HTTP error response from Gemini into the appropriate
+     * GuideKit error class.
+     */
+    private handleHttpError;
+}
+/**
+ * High-level orchestrator that manages LLM interactions for the GuideKit SDK.
+ *
+ * Responsibilities:
+ * - Owns the active `LLMProviderAdapter` (currently only `GeminiAdapter`).
+ * - Streams responses from the provider, emitting callbacks for text chunks,
+ *   tool calls, and token usage.
+ * - Handles content filter retries: if the initial response is blocked, it
+ *   retries once with a stripped-down prompt (no tools).
+ * - Surfaces all errors through the SDK error hierarchy.
+ */
+declare class LLMOrchestrator {
+    private _adapter;
+    private _config;
+    private readonly debug;
+    private readonly callbacks;
+    constructor(options: {
+        config: LLMConfig;
+        debug?: boolean;
+        onChunk?: (chunk: TextChunk) => void;
+        onToolCall?: (toolCall: ToolCall) => void;
+        onTokenUsage?: (usage: TokenUsage) => void;
+        onError?: (error: Error) => void;
+    });
+    /**
+     * Send a message and stream the response from the LLM.
+     *
+     * Accumulates text and tool calls from the stream, invoking callbacks
+     * as chunks arrive, and returns the complete result once the stream ends.
+     */
+    sendMessage(params: {
+        systemPrompt: string;
+        history: ConversationTurn[];
+        userMessage: string;
+        tools?: ToolDefinition[];
+        signal?: AbortSignal;
+    }): Promise<{
+        text: string;
+        toolCalls: ToolCall[];
+        usage: TokenUsage;
+    }>;
+    /**
+     * Hot-swap the LLM configuration. Creates a new adapter for the
+     * updated provider/model.
+     */
+    updateConfig(config: LLMConfig): void;
+    /** Get the current provider adapter. */
+    get adapter(): LLMProviderAdapter;
+    /**
+     * Execute a streaming LLM request and collect the results.
+     */
+    private executeStream;
+    /**
+     * Create the appropriate adapter for the given config.
+     * Currently only Gemini is implemented; other providers will be added
+     * as the SDK evolves.
+     */
+    private createAdapter;
+    /** Convenience accessor for the current provider name. */
+    private get providerName();
+    /** Log a debug message if debug mode is enabled. */
+    private log;
+}
+
+/**
+ * A registered handler for a specific tool. The `name` must match the tool
+ * definition's `name` field exactly.
+ */
+interface ToolHandler {
+    name: string;
+    execute: (args: Record<string, unknown>) => Promise<unknown>;
+}
+/** Options for configuring the ToolExecutor. */
+interface ToolExecutorOptions {
+    /** Max number of tool call rounds before forcing text response. Default: 5 */
+    maxRounds?: number;
+    /** Enable debug logging. */
+    debug?: boolean;
+    /** Called when a tool is about to be executed. */
+    onToolCall?: (name: string, args: Record<string, unknown>) => void;
+    /** Called when a tool execution completes. */
+    onToolResult?: (name: string, result: unknown, durationMs: number) => void;
+    /** Called when a tool execution fails. */
+    onToolError?: (name: string, error: Error) => void;
+}
+/** A single executed tool call with its outcome. */
+interface ToolCallRecord {
+    name: string;
+    args: Record<string, unknown>;
+    result: unknown;
+    durationMs: number;
+    error?: string;
+}
+/** Aggregated token usage across all rounds. */
+interface AggregatedUsage {
+    prompt: number;
+    completion: number;
+    total: number;
+}
+/** The complete result of a multi-turn tool execution session. */
+interface ToolExecutionResult {
+    /** The final text response from the LLM. */
+    text: string;
+    /** All tool calls that were executed across every round. */
+    toolCallsExecuted: ToolCallRecord[];
+    /** Accumulated token usage across all LLM calls. */
+    totalUsage: AggregatedUsage;
+    /** Number of LLM round-trips performed. */
+    rounds: number;
+}
+/**
+ * Manages multi-turn LLM interactions involving tool calls.
+ *
+ * Flow:
+ * 1. Send the user message to the LLM along with available tool definitions.
+ * 2. If the LLM response includes tool calls, execute them in parallel.
+ * 3. Feed tool results back to the LLM as additional conversation context.
+ * 4. Repeat until the LLM produces a text-only response or `maxRounds`
+ *    is exceeded.
+ */
+declare class ToolExecutor {
+    private readonly maxRounds;
+    private readonly debugEnabled;
+    private readonly handlers;
+    private readonly onToolCallCb?;
+    private readonly onToolResultCb?;
+    private readonly onToolErrorCb?;
+    constructor(options?: ToolExecutorOptions);
+    /** Register a tool handler. Overwrites any existing handler with the same name. */
+    registerTool(handler: ToolHandler): void;
+    /** Unregister a tool by name. No-op if the tool is not registered. */
+    unregisterTool(name: string): void;
+    /** Check whether a tool handler is registered. */
+    hasTool(name: string): boolean;
+    /**
+     * Build `ToolDefinition[]` from all registered handlers.
+     *
+     * Since `ToolHandler` only carries `name` and `execute`, the returned
+     * definitions have empty descriptions and parameters. Callers that need
+     * richer definitions should maintain their own `ToolDefinition[]` and
+     * pass them directly to `executeWithTools`.
+     */
+    getToolDefinitions(): ToolDefinition[];
+    /**
+     * Execute a multi-turn conversation with tool calls.
+     *
+     * The method sends the initial user message to the LLM. If the LLM
+     * responds with tool calls, each call is executed in parallel, the
+     * results are appended to the conversation, and the updated context
+     * is sent back to the LLM. This loop repeats until:
+     *
+     * - The LLM returns a text-only response (no tool calls), or
+     * - `maxRounds` consecutive tool-calling rounds have been exhausted.
+     *
+     * When `maxRounds` is exceeded the executor returns whatever text the
+     * LLM has produced so far (which may be empty).
+     */
+    executeWithTools(params: {
+        llm: LLMOrchestrator;
+        systemPrompt: string;
+        history: ConversationTurn[];
+        userMessage: string;
+        tools: ToolDefinition[];
+        signal?: AbortSignal;
+    }): Promise<ToolExecutionResult>;
+    /**
+     * Execute a single tool call by looking up the registered handler and
+     * invoking it. Returns the result, any error message, and the wall-clock
+     * duration in milliseconds.
+     */
+    private executeTool;
+    /**
+     * Execute an array of tool calls concurrently. If the abort signal fires
+     * mid-execution, already-started calls run to completion but the results
+     * of all settled calls are still returned.
+     */
+    private executeToolCallsInParallel;
+    /**
+     * Convert the internal turn representation (which includes 'tool' roles
+     * and assistant turns with tool call metadata) into the flat
+     * `ConversationTurn[]` that `LLMOrchestrator.sendMessage` expects.
+     *
+     * Strategy:
+     * - Standard `ConversationTurn` objects pass through unchanged.
+     * - `AssistantToolCallTurn` objects are converted to an assistant turn
+     *   whose content describes the tool calls that were made.
+     * - `ToolResultTurn` objects are converted to user turns that report
+     *   the tool results so the LLM can incorporate them.
+     *
+     * This approach works with any LLM provider since it only uses the
+     * 'user' | 'assistant' role discriminator.
+     */
+    private flattenHistory;
+    private isToolResultTurn;
+    private isAssistantToolCallTurn;
+    private log;
+}
+
+/**
+ * @module @guidekit/core/visual
+ *
+ * Visual Guidance System for the GuideKit SDK.
+ * Provides spotlight overlays, tooltips, smooth scrolling, and guided tours
+ * to visually direct users to page elements identified by the LLM.
+ *
+ * Key design decisions:
+ * - Overlay lives on document.body (NOT Shadow DOM) so it can cover the entire page.
+ * - Uses box-shadow cutout technique for the spotlight effect.
+ * - Tracks element position via ResizeObserver + scroll listeners (NOT rAF polling).
+ * - All text is set via textContent (never innerHTML) to prevent XSS.
+ * - SSR-safe: every browser API is guarded behind typeof checks.
+ * - Compositor-only animations (transform, opacity) for smooth 60fps.
+ * - Respects prefers-reduced-motion.
+ */
+interface VisualGuidanceOptions {
+    /** Color of the spotlight overlay. Default: 'rgba(0, 0, 0, 0.5)' */
+    overlayColor?: string;
+    /** Color of the spotlight cutout border. Default: '#4a9eed' */
+    spotlightColor?: string;
+    /** Animation duration in ms. Default: 300 */
+    animationDuration?: number;
+    /** Padding around the highlighted element in px. Default: 8 */
+    spotlightPadding?: number;
+    /** Enable debug logging. Default: false */
+    debug?: boolean;
+}
+interface TooltipOptions {
+    text: string;
+    position?: 'top' | 'bottom' | 'left' | 'right' | 'auto';
+}
+interface SpotlightState {
+    isActive: boolean;
+    selector: string | null;
+    sectionId: string | null;
+    tooltip: string | null;
+}
+declare class VisualGuidance {
+    private readonly overlayColor;
+    private readonly spotlightColor;
+    private readonly animationDuration;
+    private readonly spotlightPadding;
+    private readonly debug;
+    private overlayEl;
+    private spotlightEl;
+    private tooltipEl;
+    private liveRegionEl;
+    private _state;
+    private resizeObserver;
+    private scrollListenerCleanups;
+    private currentTargetElement;
+    private tourSectionIds;
+    private tourCurrentStep;
+    private tourMode;
+    private tourAutoTimer;
+    private tourPausedByInteraction;
+    private spotlightChangeCallbacks;
+    private tourStepCallbacks;
+    private domScanner;
+    private destroyed;
+    constructor(options?: VisualGuidanceOptions);
+    /**
+     * Highlight an element by selector or sectionId.
+     * Returns true if the element was found and highlighted, false otherwise.
+     */
+    highlight(params: {
+        sectionId?: string;
+        selector?: string;
+        tooltip?: string;
+        position?: 'top' | 'bottom' | 'left' | 'right' | 'auto';
+    }): boolean;
+    /**
+     * Remove the spotlight and all associated elements.
+     */
+    dismissHighlight(): void;
+    /**
+     * Smooth scroll to a section by its sectionId.
+     */
+    scrollToSection(sectionId: string, offset?: number): void;
+    /**
+     * Smooth scroll to an element by CSS selector.
+     */
+    scrollToSelector(selector: string, offset?: number): void;
+    /**
+     * Start a guided tour through the given section IDs.
+     */
+    startTour(sectionIds: string[], mode?: 'auto' | 'manual'): void;
+    /**
+     * Move to the next tour step. No-op if no tour is active.
+     */
+    nextTourStep(): void;
+    /**
+     * Move to the previous tour step. No-op if no tour is active or at first step.
+     */
+    prevTourStep(): void;
+    /**
+     * Stop the tour and dismiss all highlights.
+     */
+    stopTour(): void;
+    /**
+     * Get the current spotlight state.
+     */
+    get state(): SpotlightState;
+    /**
+     * Get the current tour state, or null if no tour is active.
+     */
+    get tourState(): {
+        active: boolean;
+        step: number;
+        total: number;
+    } | null;
+    /**
+     * Subscribe to spotlight state changes.
+     * Returns an unsubscribe function.
+     */
+    onSpotlightChange(callback: (state: SpotlightState) => void): () => void;
+    /**
+     * Subscribe to tour step events.
+     * Returns an unsubscribe function.
+     */
+    onTourStep(callback: (step: number, total: number, sectionId: string) => void): () => void;
+    /**
+     * Clean up all DOM elements, observers, and event listeners.
+     * After calling destroy(), the instance is unusable.
+     */
+    destroy(): void;
+    /**
+     * Resolve a target element from either a sectionId or a CSS selector.
+     * If sectionId is provided, uses DOMScanner to find the section's selector.
+     */
+    private resolveTarget;
+    /**
+     * Build a CSS selector for an element, using the same priority hierarchy
+     * as the DOMScanner.
+     */
+    private buildSelectorForElement;
+    private buildStructuralPath;
+    /**
+     * Ensure the full-page overlay element exists on document.body.
+     */
+    private ensureOverlay;
+    /**
+     * Ensure the spotlight (cutout) element exists on document.body.
+     */
+    private ensureSpotlight;
+    /**
+     * Position the spotlight element over the target's bounding rect.
+     */
+    private positionSpotlight;
+    /**
+     * Show the overlay and spotlight with entrance animation.
+     */
+    private showOverlay;
+    /**
+     * Hide the overlay and spotlight.
+     */
+    private hideOverlay;
+    /**
+     * Show a tooltip near the target element.
+     */
+    private showTooltip;
+    /**
+     * Remove the tooltip element from the DOM.
+     */
+    private removeTooltip;
+    /**
+     * Remove aria-describedby from the current target element.
+     */
+    private removeAriaDescribedBy;
+    /**
+     * Compute the best auto-position for the tooltip relative to the target rect.
+     * Preference order: bottom, top, right, left.
+     */
+    private computeAutoPosition;
+    /**
+     * Position the tooltip element relative to the target rect.
+     */
+    private positionTooltip;
+    /**
+     * Apply an arrow on the tooltip pointing toward the target element.
+     * Uses a child div with CSS border triangle technique.
+     */
+    private applyTooltipArrow;
+    /**
+     * Adjust arrow horizontal position so it points toward the target center
+     * even when the tooltip is clamped to viewport edges.
+     */
+    private adjustArrowHorizontal;
+    /**
+     * Set up ResizeObserver and scroll listeners to track the target element
+     * and update spotlight/tooltip positions.
+     */
+    private setupPositionTracking;
+    /**
+     * Remove all tracking observers and event listeners.
+     */
+    private cleanupTrackingInfrastructure;
+    /**
+     * Update spotlight and tooltip positions based on the current target
+     * element's bounding rect.
+     */
+    private updatePositions;
+    /**
+     * Scroll to an element, respecting reduced motion preferences.
+     */
+    private scrollToElement;
+    /**
+     * Execute the current tour step: scroll to and highlight the section.
+     */
+    private executeTourStep;
+    /**
+     * Schedule auto-advance to the next tour step.
+     */
+    private scheduleAutoAdvance;
+    /**
+     * Clear the auto-advance timer.
+     */
+    private clearAutoTimer;
+    /**
+     * Announce a message to screen readers via an aria-live region.
+     */
+    private announce;
+    private notifySpotlightChange;
+    /**
+     * Get the transition duration, respecting prefers-reduced-motion.
+     */
+    private getTransitionDuration;
+    /**
+     * Debug logger.
+     */
+    private log;
+}
+
+/** A message held for replay once connectivity is restored. */
+interface QueuedMessage {
+    content: string;
+    timestamp: number;
+    pageUrl: string;
+}
+interface ConnectionManagerOptions {
+    /** Server endpoint for lightweight health-check pings. */
+    healthEndpoint?: string;
+    /** When `true`, diagnostic messages are logged to the console. */
+    debug?: boolean;
+}
+type StateChangeCallback = (state: ConnectionState, previous: ConnectionState) => void;
+/**
+ * Monitors network connectivity and exposes a reactive {@link ConnectionState}.
+ *
+ * Strategy:
+ * 1. Listen to `window.online` / `window.offline` events (coarse signal).
+ * 2. Periodically ping the configured `healthEndpoint` (fine-grained signal).
+ * 3. Compute a rolling average of the last {@link ROLLING_WINDOW} ping
+ *    latencies to detect degraded connections (> {@link DEGRADED_THRESHOLD_MS}).
+ * 4. When fully offline (`navigator.onLine === false`), suspend pinging and
+ *    wait for the browser's `online` event before resuming.
+ *
+ * All browser APIs are gated behind `typeof window !== 'undefined'` so the
+ * class can be safely imported (though not meaningfully used) in SSR contexts.
+ */
+declare class ConnectionManager {
+    private readonly healthEndpoint;
+    private readonly debugEnabled;
+    private _state;
+    private _running;
+    /** Rolling window of recent ping latencies (ms). */
+    private readonly pingLatencies;
+    /** Queued messages awaiting replay on reconnect. */
+    private readonly messageQueue;
+    /** Registered state-change subscribers. */
+    private readonly subscribers;
+    /** Timer handle for the periodic ping loop. */
+    private pingTimer;
+    /** Bound event handlers (stored for deterministic removal). */
+    private readonly handleOnline;
+    private readonly handleOffline;
+    constructor(options?: ConnectionManagerOptions);
+    /** Current connection state. */
+    get state(): ConnectionState;
+    /**
+     * Start monitoring connectivity.
+     *
+     * Attaches browser event listeners and begins the periodic ping loop.
+     * Calling `start()` when already running is a no-op.
+     */
+    start(): void;
+    /**
+     * Stop monitoring connectivity.
+     *
+     * Removes all event listeners, clears timers, and resets internal state.
+     */
+    stop(): void;
+    /**
+     * Subscribe to connection state changes.
+     *
+     * @returns An unsubscribe function. Calling it more than once is safe.
+     */
+    onStateChange(callback: StateChangeCallback): () => void;
+    /**
+     * Queue a message for replay once the connection is restored.
+     *
+     * The queue is capped at {@link MAX_QUEUE_SIZE} messages. When the cap is
+     * exceeded the oldest message is discarded.
+     */
+    queueMessage(message: QueuedMessage): void;
+    /**
+     * Drain the message queue and return its contents.
+     *
+     * Messages whose `pageUrl` no longer matches the current browser URL are
+     * silently discarded (the user has navigated away since queueing).
+     */
+    drainQueue(): QueuedMessage[];
+    /**
+     * Force an immediate connectivity check.
+     *
+     * @returns The updated {@link ConnectionState} after the check completes.
+     */
+    checkNow(): Promise<ConnectionState>;
+    private onBrowserOnline;
+    private onBrowserOffline;
+    /**
+     * Execute a single health-check ping and update state accordingly.
+     */
+    private ping;
+    /**
+     * Record a latency sample, keeping only the last {@link ROLLING_WINDOW}
+     * entries.
+     */
+    private recordLatency;
+    /** Compute the arithmetic mean of recorded latencies. */
+    private rollingAverage;
+    /**
+     * Schedule the next ping according to the current state's interval.
+     *
+     * When in the `offline` state, pinging is suspended entirely — the
+     * manager waits for the browser's `online` event to resume.
+     */
+    private schedulePing;
+    private clearPingTimer;
+    /**
+     * Transition to a new state, notifying subscribers if the state actually
+     * changed.
+     */
+    private transition;
+    /** Return the current page URL, or an empty string in SSR contexts. */
+    private getCurrentUrl;
+    /** Conditional debug logging. */
+    private log;
+}
+
+interface NavigationControllerOptions {
+    debug?: boolean;
+    /** Developer-provided router for guaranteed SPA navigation. */
+    router?: {
+        push: (href: string) => void | Promise<void>;
+    };
+}
+/**
+ * Manages SPA navigation detection and programmatic routing.
+ *
+ * - Prefers the Navigation API (Chrome 102+) where available.
+ * - Falls back to `popstate` + periodic URL polling (200ms).
+ * - Developer can pass a `router` prop for guaranteed SPA nav.
+ */
+declare class NavigationController {
+    private readonly debug;
+    private readonly router?;
+    private currentUrl;
+    private pollingTimer;
+    private callbacks;
+    private cleanups;
+    constructor(options?: NavigationControllerOptions);
+    /** Start listening for navigation events. */
+    start(): void;
+    /** Stop listening for navigation events. */
+    stop(): void;
+    /**
+     * Subscribe to route changes.
+     * @returns Unsubscribe function.
+     */
+    onRouteChange(callback: (from: string, to: string) => void): () => void;
+    /**
+     * Programmatically navigate to a URL.
+     * Validates same-origin before navigating.
+     */
+    navigate(href: string): Promise<boolean>;
+    /** Get the current URL. */
+    get url(): string;
+    private handleRouteChange;
+}
+
+interface AwarenessOptions {
+    bus: EventBus;
+    rootElement?: HTMLElement;
+    idleTimeoutMs?: number;
+    dwellTimeoutMs?: number;
+    rageClickThreshold?: number;
+    rageClickWindowMs?: number;
+    debug?: boolean;
+}
+interface AwarenessState {
+    scrollPercent: number;
+    scrollDirection: 'up' | 'down' | 'none';
+    focusedSectionId: string | null;
+    focusedSectionDwellMs: number;
+    isIdle: boolean;
+    lastInteractionAt: number;
+    visibleSections: Map<string, number>;
+}
+/**
+ * Observes user interactions with the page and emits structured awareness
+ * events on the shared {@link EventBus}.
+ *
+ * All browser API usage is gated behind `typeof window !== 'undefined'` so
+ * the module can be safely imported in SSR contexts.
+ */
+declare class AwarenessSystem {
+    private readonly bus;
+    private readonly rootElement;
+    private readonly idleTimeoutMs;
+    private readonly dwellTimeoutMs;
+    private readonly rageClickThreshold;
+    private readonly rageClickWindowMs;
+    private readonly debugEnabled;
+    private running;
+    /** AbortController whose signal is passed to every addEventListener call. */
+    private abortController;
+    /** IntersectionObserver for section visibility tracking. */
+    private sectionObserver;
+    /** Section id -> current visibility ratio. */
+    private readonly visibleSections;
+    private scrollPercent;
+    private scrollDirection;
+    private lastScrollY;
+    private scrollRafPending;
+    private focusedSectionId;
+    private focusedSectionSince;
+    private dwellTimer;
+    private dwellEmitted;
+    private lastInteractionAt;
+    private idleTimer;
+    private isIdle;
+    private readonly recentClicks;
+    private lastMouseMoveAt;
+    constructor(options: AwarenessOptions);
+    /** Begin observing user behavior. No-op if already running or in SSR. */
+    start(): void;
+    /** Stop all observers and listeners. */
+    stop(): void;
+    /** Alias for {@link stop}. */
+    destroy(): void;
+    /** Return a snapshot of the current awareness state. */
+    getState(): AwarenessState;
+    private readonly handleScroll;
+    private readonly handleMouseMove;
+    private readonly handleClick;
+    private readonly handleInteraction;
+    private recordInteraction;
+    private scheduleIdleTimer;
+    private clearIdleTimer;
+    /**
+     * Periodically (every 1s) check whether the user has been focused on the
+     * same section long enough to trigger a dwell event.
+     */
+    private readonly checkDwell;
+    private clearDwellTimer;
+    private initSectionObserver;
+    /**
+     * Query the DOM for observable sections and start observing them.
+     */
+    private observeSections;
+    /**
+     * Derive a stable string identifier for a DOM element used as a section.
+     *
+     * Priority: `data-guidekit-target` > `id` > tagName.
+     */
+    private getSectionId;
+    /**
+     * Build a simple CSS selector string for an element, suitable for
+     * inclusion in rage-click events.
+     */
+    private buildSelector;
+    /** Conditional debug logging. */
+    private log;
+}
+
+interface ProactiveOptions {
+    bus: EventBus;
+    debug?: boolean;
+    /** Callback invoked whenever a proactive trigger fires. */
+    onTrigger?: (trigger: ProactiveTrigger) => void;
+}
+type ProactiveTriggerType = 'greeting' | 'idle-help' | 'dwell-commentary' | 'navigation-commentary' | 'frustration' | 'form-abandonment';
+interface ProactiveTrigger {
+    type: ProactiveTriggerType;
+    sectionId?: string;
+    selector?: string;
+    /** Suggested context message for the LLM. */
+    message?: string;
+    timestamp: number;
+}
+declare class ProactiveTriggerEngine {
+    private readonly bus;
+    private readonly debug;
+    private readonly onTrigger?;
+    /** Collected unsubscribe functions from bus.on(). */
+    private unsubs;
+    /** Cooldown map: trigger key → last-fired timestamp. */
+    private cooldowns;
+    /** Progressive dwell: sectionId → number of times triggered. */
+    private dwellCounts;
+    /** Track forms the user started interacting with. */
+    private formTimers;
+    /** Track sections where frustration already fired (once per section). */
+    private frustrationFired;
+    /** Track whether idle-help has fired on this page. */
+    private idleFiredThisPage;
+    private _quietMode;
+    private started;
+    constructor(options: ProactiveOptions);
+    get quietMode(): boolean;
+    set quietMode(value: boolean);
+    /** Subscribe to bus events and check for first-visit greeting. */
+    start(): void;
+    /** Unsubscribe all bus listeners and clear internal state. */
+    stop(): void;
+    /** Alias for {@link stop}. */
+    destroy(): void;
+    /**
+     * Notify the engine about a route change.
+     * Called from the NavigationController or externally.
+     */
+    onRouteChange(from: string, to: string): void;
+    /**
+     * Notify the engine that the user started interacting with a form.
+     * If the user does not continue within {@link FORM_ABANDON_MS}, a
+     * `form-abandonment` trigger fires (once per form).
+     */
+    onFormInteractionStart(formSelector: string): void;
+    /** Reset all cooldowns and internal tracking state (useful for testing). */
+    resetCooldowns(): void;
+    private checkFirstVisitGreeting;
+    private handleIdle;
+    private handleDwell;
+    private handleRageClick;
+    private handleNavigation;
+    /**
+     * Handler for the bus `dom:route-change` event.
+     * Delegates to the shared navigation logic.
+     */
+    private handleDomRouteChange;
+    /**
+     * Fire a trigger if quiet mode is off, recording the cooldown timestamp.
+     */
+    private fireTrigger;
+    private isCooldownActive;
+}
+
+interface RateLimits {
+    maxLLMCallsPerMinute?: number;
+    maxSTTMinutesPerSession?: number;
+    maxTTSCharsPerSession?: number;
+}
+interface RateLimiterOptions {
+    bus?: EventBus;
+    limits?: RateLimits;
+    debug?: boolean;
+}
+interface RateLimiterState {
+    llmCallsInWindow: number;
+    sttMinutesUsed: number;
+    ttsCharsUsed: number;
+    llmWindowStart: number;
+}
+declare class RateLimiter {
+    private readonly bus;
+    private readonly debug;
+    private maxLLMCallsPerMinute;
+    private maxSTTMinutesPerSession;
+    private maxTTSCharsPerSession;
+    private llmCallTimestamps;
+    private sttMs;
+    private sttStartedAt;
+    private ttsChars;
+    constructor(options?: RateLimiterOptions);
+    /**
+     * Check whether an LLM call is allowed. If allowed, records the call.
+     * Throws `ResourceExhaustedError` if the limit is exceeded.
+     */
+    checkLLMCall(): void;
+    /** Call when STT streaming starts. */
+    sttStart(): void;
+    /** Call when STT streaming stops. Accumulates duration. */
+    sttStop(): void;
+    /**
+     * Check whether STT streaming is within limits.
+     * Throws `ResourceExhaustedError` if exceeded.
+     */
+    checkSTT(): void;
+    /** Current STT minutes used (including active stream). */
+    private get sttMinutesUsed();
+    /**
+     * Record TTS character usage. Throws `ResourceExhaustedError` if limit exceeded.
+     */
+    checkTTS(charCount: number): void;
+    /** Get the current rate limiter state for monitoring. */
+    getState(): RateLimiterState;
+    /** Update limits at runtime. */
+    setLimits(limits: RateLimits): void;
+    /** Reset all counters (e.g., for testing or new session). */
+    reset(): void;
+    private emitError;
+    private log;
+}
+
+interface TokenData {
+    token: string;
+    expiresAt: number;
+    expiresIn: number;
+    fetchedAt: number;
+}
+interface TokenManagerOptions {
+    tokenEndpoint: string;
+    instanceId: string;
+    bus: EventBus;
+    debug?: boolean;
+}
+declare class TokenManager {
+    private readonly endpoint;
+    private readonly instanceId;
+    private readonly bus;
+    private readonly debug;
+    private _token;
+    private _refreshTimer;
+    private _isLeader;
+    private _bc;
+    private _destroyed;
+    constructor(options: TokenManagerOptions);
+    /** Current token string, or null if not yet fetched. */
+    get token(): string | null;
+    /** Current token data, or null if not yet fetched. */
+    get tokenData(): TokenData | null;
+    /** Whether this tab is the leader for token refresh. */
+    get isLeader(): boolean;
+    /**
+     * Initialize the token manager: elect leader, fetch initial token,
+     * schedule auto-refresh.
+     */
+    start(): Promise<void>;
+    /**
+     * Force a token refresh, regardless of TTL.
+     */
+    refresh(): Promise<void>;
+    /**
+     * Clean up timers, BroadcastChannel, and release leader.
+     */
+    destroy(): void;
+    private fetchToken;
+    private scheduleRefresh;
+    private scheduleExpiredCheck;
+    private setupBroadcastChannel;
+    private readonly _tabId;
+    private electLeader;
+    private broadcastToken;
+    private get storageKey();
+    private saveToStorage;
+    private loadFromStorage;
+    private isExpired;
+    private log;
+}
+
+export { type AgentConfig, type AgentState, type AggregatedUsage, AuthenticationError, type AwarenessOptions, type AwarenessState, AwarenessSystem, type BeforeLLMCallContext, BrowserSupportError, ConfigurationError, ConnectionManager, type ConnectionManagerOptions, type ConnectionState, ContentFilterError, type ContentMap, type ContentMapEntry, type ContentMapFunction, type ContentMapInput, ContextManager, type ContextManagerOptions, type ConversationTurn, type CreateSessionTokenOptions, DOMScanner, type DOMScannerOptions, type ErrorCode, ErrorCodes, EventBus, type EventMap, type FormField, type FormSummary, GeminiAdapter, GuideKitCore, type GuideKitCoreOptions, GuideKitError, type GuideKitErrorOptions, type GuideKitErrorType, type GuideKitEvent, type GuideKitOptions, type GuideKitProviderProps, type GuideKitStore, type GuideKitTheme, type HealthCheckResult, type HealthCheckStatus, I18n, type I18nOptions, type I18nStrings, InitializationError, type InteractiveElement, type LLMConfig, LLMOrchestrator, type LLMProviderAdapter, type LocaleInput, type NavItem, NavigationController, type NavigationControllerOptions, NetworkError, OpenAIAdapter, type OverlayElement, type PageModel, type PageSection, PermissionError, type ProactiveOptions, type ProactiveTrigger, ProactiveTriggerEngine, type ProactiveTriggerType, type Provider, type QueuedMessage, RateLimitError, RateLimiter, type RateLimiterOptions, type RateLimiterState, type RateLimits, type Resource, ResourceExhaustedError, ResourceManager, type ResourceManagerState, type STTConfig, type ScanMetadata, type SessionState, SingletonGuard, type SpotlightState, type SupportedLocale, type TTSConfig, type TextChunk, TimeoutError, type TokenData, TokenManager, type TokenManagerOptions, type TokenPayload, type TokenResponse, type ToolCall, type ToolCallRecord, type ToolDefinition, type ToolExecutionResult, ToolExecutor, type ToolExecutorOptions, type ToolHandler, type TooltipOptions, VisualGuidance, type VisualGuidanceOptions, createEventBus, isGuideKitError };