@pillar-ai/sdk 0.1.23 → 0.1.25

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/tools/index.d.ts

@@ -23,5 +23,6 @@
  *
  * @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 { setClientInfo, getClientInfo, getHandler, getToolDefinition, hasTool, getToolNames, getManifest, clearRegistry, getToolCount, getActionDefinition, hasAction, getActionNames, getActionCount, } from './registry';

package/dist/tools/types.d.ts

@@ -37,17 +37,17 @@
  * - start_tutorial: Start a tutorial/walkthrough
  * - inline_ui: Display inline UI card in chat
  */
-export type ToolType = 'navigate' | 'open_modal' | 'fill_form' | 'trigger_tool' | 'query' | 'copy_text' | 'external_link' | 'start_tutorial' | 'inline_ui';
+export type ToolType = "navigate" | "open_modal" | "fill_form" | "trigger_tool" | "query" | "copy_text" | "external_link" | "start_tutorial" | "inline_ui";
 /**
  * Supported platforms for tool deployments.
  */
-export type Platform = 'web' | 'ios' | 'android' | 'desktop';
+export type Platform = "web" | "ios" | "android" | "desktop";
 /**
  * Schema property definition for a single field.
  * Supports nested objects and arrays with items.
  */
 export interface ToolDataSchemaProperty {
-    type: 'string' | 'number' | 'boolean' | 'array' | 'object';
+    type: "string" | "number" | "boolean" | "array" | "object";
     description?: string;
     enum?: string[];
     default?: unknown;
@@ -65,7 +65,7 @@ export interface ToolDataSchemaProperty {
  * and populate the tool's data field before execution.
  */
 export interface ToolDataSchema {
-    type: 'object';
+    type: "object";
     properties: Record<string, ToolDataSchemaProperty>;
     required?: string[];
 }
@@ -440,6 +440,28 @@ export interface TypedOnTask<TTools extends SyncToolDefinitions | ToolDefinition
 export interface TypedPillarMethods<TTools extends SyncToolDefinitions | ToolDefinitions> {
     onTask: TypedOnTask<TTools>;
 }
+/**
+ * Valid tool name pattern (matches LLM provider requirements).
+ *
+ * - Must start with a letter or underscore
+ * - Can contain: letters, numbers, underscores, dots, colons, dashes
+ * - Maximum 64 characters
+ *
+ * Examples:
+ *   - Valid: "add_to_cart", "get_user.profile", "api:v2:search"
+ *   - Invalid: "Increment count" (space), "123_start" (starts with number)
+ */
+export declare const TOOL_NAME_PATTERN: RegExp;
+/**
+ * Validate a tool name against LLM provider requirements.
+ *
+ * @param name - Tool name to validate
+ * @returns Object with `valid` boolean and optional `error` message
+ */
+export declare function validateToolName(name: string): {
+    valid: boolean;
+    error?: string;
+};
 /**
  * Result returned from a tool's execute function.
  *
@@ -448,10 +470,10 @@ export interface TypedPillarMethods<TTools extends SyncToolDefinitions | ToolDef
  */
 export interface ToolExecuteResult {
     content: Array<{
-        type: 'text';
+        type: "text";
         text: string;
     } | {
-        type: 'image';
+        type: "image";
         data: string;
         mimeType: string;
     }>;
@@ -511,7 +533,7 @@ export interface ToolSchema<TInput = Record<string, unknown>> {
      * The AI extracts structured data from the conversation to populate these.
      */
     inputSchema?: {
-        type: 'object';
+        type: "object";
         properties: Record<string, unknown>;
         required?: string[];
     };
@@ -539,6 +561,19 @@ export interface ToolSchema<TInput = Record<string, unknown>> {
      * - `void` if the tool has no return value
      */
     execute: (input: TInput) => Promise<ToolExecuteResult | unknown | void> | ToolExecuteResult | 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;
 }
 /** @deprecated Use ToolType instead */
 export type ActionType = ToolType;

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;
+}