@pillar-ai/sdk 0.1.27 → 0.1.29

package/dist/tooltips/TooltipManager.d.ts

@@ -1,42 +0,0 @@
-/**
- * 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

@@ -1,5 +0,0 @@
-/**
- * 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

@@ -1,96 +0,0 @@
-/**
- * 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

@@ -1,75 +0,0 @@
-/**
- * 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

@@ -1,11 +0,0 @@
-/**
- * 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

@@ -1,105 +0,0 @@
-/**
- * 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;
-}

package/dist/ui/types.d.ts

@@ -1,293 +0,0 @@
-/**
- * UI Interaction Types
- *
- * Type definitions for the UI scanning and interaction system.
- * This enables AI agents to understand and interact with page elements.
- */
-/**
- * Supported UI interaction types.
- *
- * - click: Click/tap on an element
- * - type: Enter text into an input field
- * - select: Select an option from a dropdown/select
- * - scroll: Scroll element into view
- * - hover: Hover over an element
- * - focus: Focus an element
- * - clear: Clear an input field's value
- */
-export type UIInteractionType = 'click' | 'type' | 'select' | 'scroll' | 'hover' | 'focus' | 'clear';
-/**
- * Element types detected by the scanner.
- */
-export type UIElementType = 'button' | 'link' | 'input' | 'textarea' | 'select' | 'checkbox' | 'radio' | 'switch' | 'slider' | 'menu' | 'menuitem' | 'tab' | 'dialog' | 'custom' | 'unknown';
-/**
- * Bounding rectangle for an element.
- */
-export interface UIElementRect {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-}
-/**
- * Represents a scanned UI element.
- *
- * Contains all information needed for the AI to understand
- * and interact with a page element.
- */
-export interface UIElement {
-    /**
-     * Unique identifier for this element.
-     * Generated during scanning (e.g., "pillar-el-0").
-     * Used to target the element for interactions.
-     */
-    id: string;
-    /**
-     * HTML tag name (lowercase).
-     * @example "button", "input", "div"
-     */
-    tag: string;
-    /**
-     * Semantic element type.
-     * Derived from tag, role, or type attribute.
-     */
-    type: UIElementType;
-    /**
-     * Human-readable label for the AI.
-     * Extracted from aria-label, text content, title, etc.
-     */
-    label: string;
-    /**
-     * Whether the element can be interacted with.
-     * False if disabled or not interactive.
-     */
-    interactable: boolean;
-    /**
-     * List of interactions this element supports.
-     * Determined by element type and attributes.
-     */
-    interactions: UIInteractionType[];
-    /**
-     * Current value for inputs, textareas, selects.
-     */
-    value?: string;
-    /**
-     * Available options for select elements.
-     */
-    options?: string[];
-    /**
-     * Placeholder text for inputs/textareas.
-     */
-    placeholder?: string;
-    /**
-     * Whether checkbox/radio/switch is checked.
-     */
-    checked?: boolean;
-    /**
-     * Whether the element is disabled.
-     */
-    disabled?: boolean;
-    /**
-     * Element's bounding rectangle.
-     * Useful for understanding layout context.
-     */
-    rect: UIElementRect;
-    /**
-     * Relevant attributes from the element.
-     * Includes data-pillar-* attributes and key attributes.
-     */
-    attributes: Record<string, string>;
-    /**
-     * XPath for precise element targeting.
-     * Used as a fallback if ID-based lookup fails.
-     */
-    xpath: string;
-    /**
-     * Nearby text or labels for additional context.
-     * Helps AI understand the element's purpose.
-     */
-    context?: string;
-    /**
-     * Reference to the actual DOM element.
-     * Only available client-side, not serialized.
-     * @internal
-     */
-    _element?: HTMLElement;
-}
-/**
- * Scroll position on the page.
- */
-export interface UIScrollPosition {
-    x: number;
-    y: number;
-}
-/**
- * Page-level UI state.
- *
- * Represents a snapshot of the page's interactable elements
- * at a specific point in time.
- */
-export interface UIPageState {
-    /**
-     * Current page URL.
-     */
-    url: string;
-    /**
-     * Page title.
-     */
-    title: string;
-    /**
-     * Timestamp when the scan was performed.
-     */
-    timestamp: number;
-    /**
-     * List of interactable elements on the page.
-     */
-    elements: UIElement[];
-    /**
-     * ID of the currently focused element, if any.
-     */
-    focusedElementId?: string;
-    /**
-     * Current scroll position.
-     */
-    scrollPosition: UIScrollPosition;
-}
-/**
- * Represents a UI interaction request from the AI.
- */
-export interface UIInteraction {
-    /**
-     * ID of the element to interact with.
-     * Must match an element from UIPageState.elements.
-     */
-    elementId: string;
-    /**
-     * Type of interaction to perform.
-     */
-    action: UIInteractionType;
-    /**
-     * Value for type/select interactions.
-     */
-    value?: string;
-    /**
-     * Additional options for the interaction.
-     */
-    options?: UIInteractionOptions;
-}
-/**
- * Options for UI interactions.
- */
-export interface UIInteractionOptions {
-    /**
-     * Whether to clear existing value before typing.
-     * Only applies to 'type' action.
-     * @default true
-     */
-    clearBeforeType?: boolean;
-    /**
-     * Delay in ms between keystrokes for type action.
-     * Use 0 for instant typing.
-     * @default 0
-     */
-    typeDelay?: number;
-    /**
-     * Whether to scroll element into view before interaction.
-     * @default true
-     */
-    scrollIntoView?: boolean;
-    /**
-     * Whether to wait for element to be visible.
-     * @default true
-     */
-    waitForVisible?: boolean;
-    /**
-     * Timeout in ms for waiting operations.
-     * @default 5000
-     */
-    timeout?: number;
-}
-/**
- * Result of a UI interaction.
- */
-export interface UIInteractionResult {
-    /**
-     * Whether the interaction succeeded.
-     */
-    success: boolean;
-    /**
-     * Error message if the interaction failed.
-     */
-    error?: string;
-    /**
-     * The element ID that was interacted with.
-     */
-    elementId: string;
-    /**
-     * The action that was performed.
-     */
-    action: UIInteractionType;
-    /**
-     * New value after the interaction (for inputs).
-     */
-    newValue?: string;
-    /**
-     * Whether the element is still present after interaction.
-     * May be false if clicking caused navigation or element removal.
-     */
-    elementStillPresent?: boolean;
-    /**
-     * Any data extracted from the interaction.
-     * For example, selected option text.
-     */
-    data?: Record<string, unknown>;
-}
-/**
- * Simplified element representation for AI context.
- *
- * Contains only essential information to reduce token usage
- * while still providing enough context for the AI.
- */
-export interface UIElementSummary {
-    /**
-     * Element ID for targeting.
-     */
-    id: string;
-    /**
-     * Human-readable label.
-     */
-    label: string;
-    /**
-     * Element type (button, input, etc.).
-     */
-    type: string;
-    /**
-     * Available interactions.
-     */
-    interactions: string[];
-    /**
-     * Current value (if applicable).
-     */
-    value?: string;
-    /**
-     * Available options (for selects).
-     */
-    options?: string[];
-    /**
-     * Additional context about the element.
-     */
-    context?: string;
-}
-/**
- * Convert a full UIElement to a summary for AI context.
- */
-export declare function toElementSummary(element: UIElement): UIElementSummary;
-/**
- * Convert UIPageState to a minimal representation for AI context.
- */
-export declare function toPageStateSummary(state: UIPageState): {
-    url: string;
-    title: string;
-    elements: UIElementSummary[];
-    focusedElementId?: string;
-};