@pillar-ai/sdk 0.1.32 → 0.1.34

package/dist/store/chat.d.ts

@@ -18,6 +18,7 @@ export interface ActionStatus {
  *
  * - "text": Model-generated content tokens (narration or final response)
  * - "progress": A group of progress events (thinking, search, tool calls)
+ * - "card": A tool result card to be rendered inline
  */
 export type MessageSegment = {
     type: "text";
@@ -25,6 +26,10 @@ export type MessageSegment = {
 } | {
     type: "progress";
     events: ProgressEvent[];
+} | {
+    type: "card";
+    cardType: string;
+    data: Record<string, unknown>;
 };
 export interface StoredChatMessage extends ChatMessage {
     id?: string;
@@ -152,6 +157,11 @@ export declare const addProgressEventToLastMessage: (event: ProgressEvent) => vo
  * updating `content` for backward compat (history persistence, feedback, etc.).
  */
 export declare const appendTokenToSegments: (token: string) => void;
+/**
+ * Add a card segment to the last assistant message.
+ * Used when a tool returns data with a card_type that has a registered renderer.
+ */
+export declare const addCardSegment: (cardType: string, data: Record<string, unknown>) => void;
 export declare const isExpanded: import("@preact/signals-core").Signal<boolean>;
 /**
  * @deprecated Sources are now stored per-message on `StoredChatMessage.sources`. Will be removed in v2.0.

package/dist/store/developer.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Developer Store
+ * Signal-based state for developer mode features
+ */
+export declare const selectedAction: import("@preact/signals-core").Signal<string | null>;
+export declare const actionData: import("@preact/signals-core").Signal<string>;
+export declare const executionResult: import("@preact/signals-core").Signal<{
+    type: "success" | "error";
+    message: string;
+} | null>;
+export declare const isExecuting: import("@preact/signals-core").Signal<boolean>;
+export declare const setSelectedAction: (actionName: string | null) => void;
+export declare const setActionData: (data: string) => void;
+export declare const setExecutionResult: (result: {
+    type: "success" | "error";
+    message: string;
+} | null) => void;
+export declare const setIsExecuting: (executing: boolean) => void;
+export declare const resetDeveloperStore: () => void;

package/dist/store/tooltips.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Tooltips Store
+ * Signal-based state for tooltip visibility and data
+ */
+import type { TooltipData } from '../api/client';
+export interface TooltipInstance {
+    id: string;
+    data: TooltipData;
+    anchor: HTMLElement;
+    isVisible: boolean;
+}
+export declare const tooltips: import("@preact/signals-core").Signal<Map<string, TooltipInstance>>;
+export declare const visibleTooltipId: import("@preact/signals-core").Signal<string | null>;
+export declare const visibleTooltip: import("@preact/signals-core").ReadonlySignal<TooltipInstance | null>;
+export declare const tooltipCount: import("@preact/signals-core").ReadonlySignal<number>;
+export declare const registerTooltip: (id: string, data: TooltipData, anchor: HTMLElement) => void;
+export declare const unregisterTooltip: (id: string) => void;
+export declare const showTooltip: (id: string) => void;
+export declare const hideTooltip: (id: string) => void;
+export declare const hideAllTooltips: () => void;
+export declare const resetTooltips: () => void;

package/dist/tools/index.d.ts

@@ -24,5 +24,5 @@
  * @module tools
  */
 export { validateToolName, TOOL_NAME_PATTERN } from './types';
-export type { ToolType, ToolDataSchema, ToolDataSchemaProperty, ToolDefinition, ToolDefinitions, ToolManifest, ToolManifestEntry, ClientInfo, Platform, SyncToolDefinition, SyncToolDefinitions, ToolTypeDataMap, NavigateToolData, TriggerToolData, InlineUIData, ExternalLinkData, CopyTextData, QueryToolData, ToolDataType, ToolNames, TypedTaskHandler, TypedOnTask, TypedPillarMethods, ToolExecuteResult, ToolSchema, ActionType, ActionDataSchema, ActionDataSchemaProperty, ActionDefinition, ActionDefinitions, ActionManifest, ActionManifestEntry, SyncActionDefinition, SyncActionDefinitions, NavigateActionData, TriggerActionData, QueryActionData, ActionTypeDataMap, ActionDataType, ActionNames, ActionResult, ActionSchema, } from './types';
+export type { ToolType, ToolDataSchema, ToolDataSchemaProperty, ToolDefinition, ToolDefinitions, ToolManifest, ToolManifestEntry, ClientInfo, Platform, SyncToolDefinition, SyncToolDefinitions, ToolTypeDataMap, NavigateToolData, TriggerToolData, InlineUIData, ExternalLinkData, CopyTextData, QueryToolData, ToolDataType, ToolNames, TypedTaskHandler, TypedOnTask, TypedPillarMethods, ToolExecuteResult, ToolSchemaBase, InlineUIToolSchema, ExecutableToolSchema, ToolSchema, ActionType, ActionDataSchema, ActionDataSchemaProperty, ActionDefinition, ActionDefinitions, ActionManifest, ActionManifestEntry, SyncActionDefinition, SyncActionDefinitions, NavigateActionData, TriggerActionData, QueryActionData, ActionTypeDataMap, ActionDataType, ActionNames, ActionResult, ActionSchema, } from './types';
 export { setClientInfo, getClientInfo, getHandler, getToolDefinition, hasTool, getToolNames, getManifest, clearRegistry, getToolCount, getActionDefinition, hasAction, getActionNames, getActionCount, } from './registry';

package/dist/tools/types.d.ts

@@ -24,6 +24,7 @@
  * // Register handlers at runtime: pillar.onTask('open_settings', () => router.push('/settings'));
  * ```
  */
+import type { CardRenderer } from "../core/events";
 /**
  * Supported tool types.
  *
@@ -480,34 +481,12 @@ export interface ToolExecuteResult {
     isError?: boolean;
 }
 /**
- * Unified tool definition that co-locates metadata and handler.
- *
- * Use with `pillar.defineTool()` or the `usePillarTool()` React hook.
- * The CLI scanner (`npx pillar-sync --scan ./src`) discovers these
- * definitions automatically — no barrel file needed.
- *
- * @template TInput - Type of the input object passed to `execute`
+ * Shared fields for all tool schemas (both executable and inline_ui).
  *
- * @example
- * ```ts
- * pillar.defineTool({
- *   name: 'get_signing_secret',
- *   description: 'Retrieve the webhook signing secret',
- *   outputSchema: {
- *     type: 'object',
- *     properties: {
- *       signing_secret: { type: 'string', sensitive: true },
- *       algorithm: { type: 'string' },
- *     },
- *   },
- *   execute: async () => {
- *     const secret = await api.getSigningSecret();
- *     return { signing_secret: secret.value, algorithm: 'HMAC-SHA256' };
- *   },
- * });
- * ```
+ * @template TInput - Type of the input object passed to `execute` or
+ *   provided by the AI agent to the `render` component.
  */
-export interface ToolSchema<TInput = Record<string, unknown>> {
+export interface ToolSchemaBase<TInput = Record<string, unknown>> {
     /** Unique tool name (e.g., 'add_to_cart') */
     name: string;
     /** Human-readable description for AI matching */
@@ -523,10 +502,6 @@ export interface ToolSchema<TInput = Record<string, unknown>> {
      * Action model so the agent sees it without runtime code.
      */
     guidance?: string;
-    /**
-     * Type of tool - determines how the SDK handles it and organizes it in the UI.
-     */
-    type?: ToolType;
     /**
      * JSON Schema describing the input parameters.
      * The AI extracts structured data from the conversation to populate these.
@@ -572,6 +547,85 @@ export interface ToolSchema<TInput = Record<string, unknown>> {
      * @example { plan: 'enterprise', betaAccess: true }
      */
     requiredContext?: Record<string, unknown>;
+    /**
+     * Whether to also register this tool with WebMCP (navigator.modelContext).
+     *
+     * When true, the tool will be exposed to browser-native AI agents and
+     * assistive technologies via the W3C WebMCP API. The tool is registered
+     * on mount and unregistered on unmount (or when the tool is removed).
+     *
+     * Only works in browser contexts where `navigator.modelContext` is available
+     * (either natively or via polyfill).
+     *
+     * @default false
+     */
+    webMCP?: boolean;
+}
+/**
+ * Tool schema for `inline_ui` tools that render a component in the chat.
+ *
+ * The AI agent provides data directly to the `render` function —
+ * there is no `execute` handler.
+ *
+ * @template TInput - Type of the data the AI agent provides to the render component
+ *
+ * @example Vanilla JS
+ * ```ts
+ * pillar.defineTool({
+ *   name: 'show_results',
+ *   description: 'Display search results inline',
+ *   type: 'inline_ui',
+ *   render: (container, data, { onConfirm, onCancel }) => {
+ *     container.innerHTML = `<div>${data.items.length} results</div>`;
+ *     return () => { container.innerHTML = ''; };
+ *   },
+ * });
+ * ```
+ */
+export interface InlineUIToolSchema<TInput = Record<string, unknown>> extends ToolSchemaBase<TInput> {
+    type: "inline_ui";
+    /**
+     * Card renderer for displaying tool results inline in the chat.
+     *
+     * The AI agent provides structured data matching `inputSchema` directly
+     * to this renderer. The SDK automatically registers this as a card
+     * renderer using the tool name as the card type.
+     *
+     * For framework-specific SDKs (React, Vue, Angular), pass a component
+     * instead — the framework SDK will convert it to a CardRenderer.
+     */
+    render: CardRenderer;
+    /** Not applicable for inline_ui tools. Use `render` instead. */
+    execute?: never;
+}
+/**
+ * Tool schema for executable tools (all types except `inline_ui`).
+ *
+ * The `execute` handler runs when the AI invokes this tool.
+ *
+ * @template TInput - Type of the input object passed to `execute`
+ *
+ * @example
+ * ```ts
+ * pillar.defineTool({
+ *   name: 'get_signing_secret',
+ *   description: 'Retrieve the webhook signing secret',
+ *   outputSchema: {
+ *     type: 'object',
+ *     properties: {
+ *       signing_secret: { type: 'string', sensitive: true },
+ *       algorithm: { type: 'string' },
+ *     },
+ *   },
+ *   execute: async () => {
+ *     const secret = await api.getSigningSecret();
+ *     return { signing_secret: secret.value, algorithm: 'HMAC-SHA256' };
+ *   },
+ * });
+ * ```
+ */
+export interface ExecutableToolSchema<TInput = Record<string, unknown>> extends ToolSchemaBase<TInput> {
+    type?: Exclude<ToolType, "inline_ui">;
     /**
      * Handler function executed when the AI invokes this tool.
      *
@@ -587,20 +641,23 @@ export interface ToolSchema<TInput = Record<string, unknown>> {
      * return flat data.
      */
     execute: (input: TInput) => Promise<ToolExecuteResult | Record<string, unknown> | void> | ToolExecuteResult | Record<string, unknown> | void;
-    /**
-     * Whether to also register this tool with WebMCP (navigator.modelContext).
-     *
-     * When true, the tool will be exposed to browser-native AI agents and
-     * assistive technologies via the W3C WebMCP API. The tool is registered
-     * on mount and unregistered on unmount (or when the tool is removed).
-     *
-     * Only works in browser contexts where `navigator.modelContext` is available
-     * (either natively or via polyfill).
-     *
-     * @default false
-     */
-    webMCP?: boolean;
+    /** Not applicable for executable tools. Only `inline_ui` tools use `render`. */
+    render?: never;
 }
+/**
+ * Unified tool definition that co-locates metadata and handler.
+ *
+ * Use with `pillar.defineTool()` or the `usePillarTool()` React hook.
+ * The CLI scanner (`npx pillar-sync --scan ./src`) discovers these
+ * definitions automatically — no barrel file needed.
+ *
+ * - For `type: 'inline_ui'` tools: provide `render` (no `execute`).
+ * - For all other tool types: provide `execute` (no `render`).
+ *
+ * @template TInput - Type of the input object passed to `execute`
+ *   or provided to the `render` component by the AI agent.
+ */
+export type ToolSchema<TInput = Record<string, unknown>> = InlineUIToolSchema<TInput> | ExecutableToolSchema<TInput>;
 /** @deprecated Use ToolType instead */
 export type ActionType = ToolType;
 /** @deprecated Use ToolDataSchemaProperty instead */

package/dist/tooltips/Tooltip.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Individual Tooltip Component
+ * Handles rendering and positioning of a single tooltip
+ */
+import type { TooltipData } from '../api/client';
+import type { TooltipTrigger, TooltipPosition } from '../core/config';
+export interface TooltipOptions {
+    trigger: TooltipTrigger;
+    position: TooltipPosition;
+    onLearnMore?: (articleSlug: string) => void;
+    onShow?: () => void;
+    onHide?: () => void;
+}
+export declare class Tooltip {
+    private id;
+    private data;
+    private anchor;
+    private options;
+    private element;
+    private arrow;
+    private iconElement;
+    private isVisible;
+    private hideTimeout;
+    constructor(data: TooltipData, anchor: HTMLElement, options: TooltipOptions);
+    /**
+     * Initialize the tooltip
+     */
+    init(): void;
+    /**
+     * Show the tooltip
+     */
+    show(): void;
+    /**
+     * Hide the tooltip
+     */
+    hide(): void;
+    /**
+     * Toggle tooltip visibility
+     */
+    toggle(): void;
+    /**
+     * Update tooltip position
+     */
+    updatePosition(): void;
+    /**
+     * Destroy the tooltip
+     */
+    destroy(): void;
+    private createElement;
+    private createIcon;
+    private bindEvents;
+    private unbindEvents;
+    private handleMouseEnter;
+    private handleTooltipMouseEnter;
+    private handleMouseLeave;
+    private handleClick;
+    private handleDocumentClick;
+    private handleFocus;
+    private handleBlur;
+    private handleKeyDown;
+    private handleScroll;
+    private handleResize;
+}

package/dist/tooltips/TooltipManager.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Tooltip Manager
+ * Scans DOM for tooltip elements and manages their lifecycle
+ */
+import type { EventEmitter } from '../core/events';
+import type { ResolvedConfig } from '../core/config';
+import type { APIClient } from '../api/client';
+export declare class TooltipManager {
+    private config;
+    private api;
+    private events;
+    private tooltips;
+    private tooltipData;
+    private observer;
+    private stylesInjected;
+    constructor(config: ResolvedConfig, api: APIClient, events: EventEmitter);
+    /**
+     * Initialize the tooltip manager
+     */
+    init(): Promise<void>;
+    /**
+     * Scan DOM for tooltip elements and initialize them
+     */
+    scan(): Promise<void>;
+    /**
+     * Show a specific tooltip
+     */
+    show(tooltipId: string): void;
+    /**
+     * Hide a specific tooltip
+     */
+    hide(tooltipId: string): void;
+    /**
+     * Destroy the tooltip manager
+     */
+    destroy(): void;
+    private createTooltip;
+    private setupObserver;
+    private handleRemovedElement;
+    private getElementKey;
+    private getTooltipDataForElement;
+}

package/dist/tooltips/styles.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Tooltip CSS Styles
+ * Injected into the document head
+ */
+export declare const TOOLTIP_STYLES = "\n/* Pillar Tooltip Styles */\n.pillar-tooltip {\n  position: absolute;\n  z-index: 99999;\n  max-width: 320px;\n  padding: 12px 16px;\n  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;\n  font-size: 14px;\n  line-height: 1.5;\n  color: #1a1a1a;\n  background: #ffffff;\n  border-radius: 8px;\n  box-shadow: 0 4px 20px rgba(0, 0, 0, 0.15), 0 0 0 1px rgba(0, 0, 0, 0.05);\n  pointer-events: auto;\n  opacity: 0;\n  transform: scale(0.95);\n  transition: opacity 0.15s ease, transform 0.15s ease;\n}\n\n.pillar-tooltip.pillar-tooltip--visible {\n  opacity: 1;\n  transform: scale(1);\n}\n\n.pillar-tooltip__content {\n  margin: 0;\n}\n\n.pillar-tooltip__content p {\n  margin: 0 0 8px;\n}\n\n.pillar-tooltip__content p:last-child {\n  margin-bottom: 0;\n}\n\n.pillar-tooltip__content a {\n  color: #2563eb;\n  text-decoration: none;\n}\n\n.pillar-tooltip__content a:hover {\n  text-decoration: underline;\n}\n\n.pillar-tooltip__learn-more {\n  display: inline-flex;\n  align-items: center;\n  gap: 4px;\n  margin-top: 12px;\n  padding: 6px 12px;\n  font-size: 13px;\n  font-weight: 500;\n  color: #2563eb;\n  background: #eff6ff;\n  border: none;\n  border-radius: 6px;\n  cursor: pointer;\n  transition: background 0.15s ease;\n}\n\n.pillar-tooltip__learn-more:hover {\n  background: #dbeafe;\n}\n\n.pillar-tooltip__learn-more svg {\n  width: 14px;\n  height: 14px;\n}\n\n/* Arrow */\n.pillar-tooltip__arrow {\n  position: absolute;\n  width: 12px;\n  height: 12px;\n  background: #ffffff;\n  transform: rotate(45deg);\n  box-shadow: -1px -1px 0 0 rgba(0, 0, 0, 0.05);\n}\n\n.pillar-tooltip--top .pillar-tooltip__arrow {\n  bottom: -6px;\n  box-shadow: 1px 1px 0 0 rgba(0, 0, 0, 0.05);\n}\n\n.pillar-tooltip--bottom .pillar-tooltip__arrow {\n  top: -6px;\n}\n\n.pillar-tooltip--left .pillar-tooltip__arrow {\n  right: -6px;\n  box-shadow: 1px -1px 0 0 rgba(0, 0, 0, 0.05);\n}\n\n.pillar-tooltip--right .pillar-tooltip__arrow {\n  left: -6px;\n  box-shadow: -1px 1px 0 0 rgba(0, 0, 0, 0.05);\n}\n\n/* Tooltip Icon (for icon trigger) */\n.pillar-tooltip-icon {\n  display: inline-flex;\n  align-items: center;\n  justify-content: center;\n  width: 16px;\n  height: 16px;\n  margin-left: 4px;\n  vertical-align: middle;\n  color: #6b7280;\n  cursor: help;\n  transition: color 0.15s ease;\n}\n\n.pillar-tooltip-icon:hover {\n  color: #2563eb;\n}\n\n.pillar-tooltip-icon svg {\n  width: 100%;\n  height: 100%;\n}\n\n/* Close button */\n.pillar-tooltip__close {\n  position: absolute;\n  top: 8px;\n  right: 8px;\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  width: 20px;\n  height: 20px;\n  padding: 0;\n  color: #9ca3af;\n  background: none;\n  border: none;\n  border-radius: 4px;\n  cursor: pointer;\n  transition: color 0.15s ease, background 0.15s ease;\n}\n\n.pillar-tooltip__close:hover {\n  color: #1a1a1a;\n  background: #f3f4f6;\n}\n\n.pillar-tooltip__close svg {\n  width: 12px;\n  height: 12px;\n}\n";

package/dist/ui/config.d.ts

@@ -0,0 +1,96 @@
+/**
+ * UI Scanner Configuration
+ *
+ * Configuration options for the UI scanning system.
+ */
+/**
+ * Configuration for the UI Scanner.
+ */
+export interface UIScannerConfig {
+    /**
+     * Enable automatic UI scanning.
+     * When true, the page is scanned on init and after interactions.
+     * @default true
+     */
+    enabled: boolean;
+    /**
+     * CSS selectors for containers to scan.
+     * Only elements within these containers will be included.
+     * Use ['body'] to scan the entire page.
+     * @default ['body']
+     */
+    includeSelectors: string[];
+    /**
+     * CSS selectors to exclude from scanning.
+     * Elements matching these selectors (or within them) will be skipped.
+     * @default []
+     */
+    excludeSelectors: string[];
+    /**
+     * Automatically exclude sensitive elements.
+     * When true, password fields, payment forms, etc. are excluded.
+     * @default true
+     */
+    excludeSensitive: boolean;
+    /**
+     * Additional selectors for sensitive elements to exclude.
+     * These are added to the default sensitive selectors.
+     * @default []
+     */
+    sensitiveSelectors: string[];
+    /**
+     * Maximum number of elements to include in the scan.
+     * Elements are prioritized by visibility and interactability.
+     * @default 100
+     */
+    maxElements: number;
+    /**
+     * Automatically rescan after each UI interaction.
+     * @default true
+     */
+    rescanAfterInteraction: boolean;
+    /**
+     * Debounce delay for rescanning in milliseconds.
+     * Prevents excessive scans during rapid interactions.
+     * @default 300
+     */
+    rescanDebounceMs: number;
+    /**
+     * Include elements that are currently not visible (scrolled out of view).
+     * @default false
+     */
+    includeOffscreen: boolean;
+    /**
+     * Maximum text length for element labels.
+     * Longer text will be truncated.
+     * @default 100
+     */
+    maxLabelLength: number;
+    /**
+     * Maximum text length for context extraction.
+     * @default 200
+     */
+    maxContextLength: number;
+}
+/**
+ * Default sensitive element selectors.
+ * These are excluded when excludeSensitive is true.
+ */
+export declare const DEFAULT_SENSITIVE_SELECTORS: string[];
+/**
+ * Default selectors for interactable elements.
+ * Used by the scanner to find elements to include.
+ */
+export declare const DEFAULT_INTERACTABLE_SELECTORS: string[];
+/**
+ * Default configuration for the UI Scanner.
+ */
+export declare const DEFAULT_UI_SCANNER_CONFIG: UIScannerConfig;
+/**
+ * Merge user config with defaults.
+ */
+export declare function resolveUIScannerConfig(config?: Partial<UIScannerConfig>): UIScannerConfig;
+/**
+ * Get all sensitive selectors (default + custom).
+ */
+export declare function getSensitiveSelectors(config: UIScannerConfig): string[];

package/dist/ui/executor.d.ts

@@ -0,0 +1,75 @@
+/**
+ * UI Interaction Executor
+ *
+ * Executes AI-requested interactions on DOM elements.
+ * Handles clicking, typing, selecting, scrolling, and other interactions.
+ */
+import type { UIScanner } from './scanner';
+import type { UIInteraction, UIInteractionResult } from './types';
+/**
+ * Executes UI interactions on DOM elements.
+ */
+export declare class UIInteractionExecutor {
+    private scanner;
+    constructor(scanner: UIScanner);
+    /**
+     * Execute a UI interaction.
+     */
+    execute(interaction: UIInteraction): Promise<UIInteractionResult>;
+    /**
+     * Find an element by its Pillar ID.
+     */
+    private findElement;
+    /**
+     * Wait for an element to become visible.
+     */
+    private waitForVisible;
+    /**
+     * Check if an element is visible.
+     */
+    private isVisible;
+    /**
+     * Scroll an element into view.
+     */
+    private scrollIntoView;
+    /**
+     * Click on an element.
+     */
+    private click;
+    /**
+     * Type text into an input element.
+     */
+    private type;
+    /**
+     * Select an option from a select element.
+     */
+    private select;
+    /**
+     * Scroll to an element.
+     */
+    private scroll;
+    /**
+     * Hover over an element.
+     */
+    private hover;
+    /**
+     * Focus an element.
+     */
+    private focus;
+    /**
+     * Clear an input element's value.
+     */
+    private clear;
+    /**
+     * Create an error result.
+     */
+    private errorResult;
+    /**
+     * Sleep for a given number of milliseconds.
+     */
+    private sleep;
+    /**
+     * Flush microtasks to allow React/Vue state updates.
+     */
+    private flushMicrotasks;
+}

package/dist/ui/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * UI Interaction Module
+ *
+ * Exports for the UI scanning and interaction system.
+ */
+export type { UIElement, UIElementRect, UIElementSummary, UIElementType, UIInteraction, UIInteractionOptions, UIInteractionResult, UIInteractionType, UIPageState, UIScrollPosition, } from './types';
+export { toElementSummary, toPageStateSummary } from './types';
+export type { UIScannerConfig } from './config';
+export { DEFAULT_INTERACTABLE_SELECTORS, DEFAULT_SENSITIVE_SELECTORS, DEFAULT_UI_SCANNER_CONFIG, getSensitiveSelectors, resolveUIScannerConfig, } from './config';
+export { UIScanner } from './scanner';
+export { UIInteractionExecutor } from './executor';

package/dist/ui/scanner.d.ts

@@ -0,0 +1,105 @@
+/**
+ * UI Scanner
+ *
+ * Scans the DOM for interactable elements and builds a structured
+ * representation of the page's UI state for AI understanding.
+ */
+import { type UIScannerConfig } from './config';
+import type { UIPageState } from './types';
+/**
+ * Scans the page for interactable UI elements.
+ */
+export declare class UIScanner {
+    private config;
+    private elementIdCounter;
+    private elementMap;
+    constructor(config: UIScannerConfig);
+    /**
+     * Update scanner configuration.
+     */
+    updateConfig(config: Partial<UIScannerConfig>): void;
+    /**
+     * Scan the page and return the UI state.
+     */
+    scan(): UIPageState;
+    /**
+     * Get an element by its Pillar ID.
+     */
+    getElementById(id: string): HTMLElement | null;
+    /**
+     * Find all interactable elements on the page.
+     */
+    private findElements;
+    /**
+     * Get containers to scan based on config.
+     */
+    private getContainers;
+    /**
+     * Check if element is in an excluded area.
+     */
+    private isExcluded;
+    /**
+     * Check if element is sensitive (should be excluded for security).
+     */
+    private isSensitive;
+    /**
+     * Check if element is visible.
+     */
+    private isVisible;
+    /**
+     * Convert an HTML element to a UIElement.
+     */
+    private elementToUIElement;
+    /**
+     * Generate a unique ID for an element.
+     */
+    private generateId;
+    /**
+     * Determine the semantic type of an element.
+     */
+    private getElementType;
+    /**
+     * Get the available interactions for an element.
+     */
+    private getInteractions;
+    /**
+     * Extract a human-readable label for an element.
+     */
+    private extractLabel;
+    /**
+     * Extract context from surrounding elements.
+     */
+    private extractContext;
+    /**
+     * Check if element is disabled.
+     */
+    private isDisabled;
+    /**
+     * Get element bounding rectangle.
+     */
+    private getRect;
+    /**
+     * Get relevant attributes from element.
+     */
+    private getRelevantAttributes;
+    /**
+     * Generate XPath for element.
+     */
+    private getXPath;
+    /**
+     * Get the ID of the currently focused element.
+     */
+    private getFocusedElementId;
+    /**
+     * Get current scroll position.
+     */
+    private getScrollPosition;
+    /**
+     * Truncate text to max length.
+     */
+    private truncate;
+    /**
+     * Convert camelCase/snake_case name to human readable.
+     */
+    private humanizeName;
+}