@pillar-ai/sdk 0.1.14 → 0.1.16

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Pillar, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,6 @@
 # @pillar-ai/sdk
 
-Cursor for your product — Embed an AI co-pilot that executes tasks, not just answers questions.
+[Pillar](https://trypillar.com) is an open-source product copilot SDK for SaaS and web apps — embed an AI assistant that executes tasks, not just answers questions. [GitHub](https://github.com/pillarhq/pillar) · [Docs](https://trypillar.com/docs)
 
 [![npm version](https://img.shields.io/npm/v/@pillar-ai/sdk)](https://www.npmjs.com/package/@pillar-ai/sdk)
 [![npm downloads](https://img.shields.io/npm/dm/@pillar-ai/sdk)](https://www.npmjs.com/package/@pillar-ai/sdk)
@@ -9,13 +9,21 @@ Cursor for your product — Embed an AI co-pilot that executes tasks, not just a
 
 ## What is Pillar?
 
-Pillar is an embedded AI co-pilot that helps users complete tasks, not just answer questions. Users say what they want, and Pillar uses your UI to make it happen — navigating pages, pre-filling forms, and calling your APIs.
+Pillar is a product copilot for SaaS and web applications. Users say what they want, and Pillar uses your UI to make it happen — navigating pages, pre-filling forms, and calling your APIs.
 
-**How it works:**
+A CRM user could ask:
 
-1. User asks: *"Export this to CSV"* or *"Turn off email notifications"*
-2. Pillar understands intent and chains actions
-3. Your code executes with the user's session
+> "Close the Walmart deal as won in Salesforce and notify implementation"
+
+An analytics user could ask:
+
+> "Add a weekly signups chart to my Amplitude dashboard"
+
+Or an HR user:
+
+> "How do I change my direct deposit in Rippling?"
+
+Pillar understands the intent, builds a multi-step plan, and executes it client-side with the user's session.
 
 ## Features
 
@@ -50,11 +58,9 @@ yarn add @pillar-ai/sdk
 
 ### 1. Get Your Product Key
 
-First, register your product in the [Pillar app](https://app.trypillar.com):
-
-1. Sign up or log in at [app.trypillar.com](https://app.trypillar.com)
-2. Create a new product
-3. Copy your **Product Key** from the settings page
+> **⚠️ Beta Onboarding:** Cloud access is currently manual while we learn from early teams. Join the waitlist at [trypillar.com](https://trypillar.com), and we will reach out to onboard you.
+>
+> By default, you'll get an engineer from Pillar to help with setup. If you prefer onboarding without engineering support, include that in your waitlist request and we will support that too.
 
 ### 2. Initialize the SDK
 
@@ -63,7 +69,7 @@ import { Pillar } from "@pillar-ai/sdk";
 
 // Initialize and get the instance
 const pillar = await Pillar.init({
-  productKey: "your-product-key", // From Pillar app
+  productKey: "your-product-key", // Provided during onboarding
 });
 
 // Now you can use instance methods

package/dist/actions/types.d.ts

@@ -157,6 +157,18 @@ export interface ActionDefinition<TData = Record<string, unknown>> {
      * @default false
      */
     returns?: boolean;
+    /**
+     * Concrete examples of valid parameter objects for the AI to reference.
+     *
+     * Each example should have a `description` explaining the scenario
+     * and a `parameters` object matching the `dataSchema`.
+     * Useful for complex schemas where the AI benefits from seeing
+     * what a correct call looks like.
+     */
+    parameterExamples?: Array<{
+        description: string;
+        parameters: Record<string, unknown>;
+    }>;
     /**
      * Handler function executed when the action is triggered.
      *
@@ -189,6 +201,10 @@ export interface ActionManifestEntry {
     data_schema?: ActionDataSchema;
     default_data?: Record<string, unknown>;
     required_context?: Record<string, unknown>;
+    parameter_examples?: Array<{
+        description: string;
+        parameters: Record<string, unknown>;
+    }>;
 }
 /**
  * Action manifest - synced to server during CI/CD.
@@ -216,6 +232,11 @@ export interface ActionManifest {
      * Action definitions (without handlers).
      */
     actions: ActionManifestEntry[];
+    /**
+     * Custom agent guidance synced alongside actions.
+     * Injected into the AI agent's prompt as product_guidance.
+     */
+    agentGuidance?: string;
 }
 /**
  * Client info set during SDK initialization.
@@ -270,6 +291,15 @@ export interface SyncActionDefinition<TData = Record<string, unknown>> {
      * If true, the handler's return value is sent back to the agent.
      */
     returns?: boolean;
+    /**
+     * Concrete examples of valid parameter objects for the AI to reference.
+     * Each example should have a `description` and a `parameters` object
+     * matching the `dataSchema`.
+     */
+    parameterExamples?: Array<{
+        description: string;
+        parameters: Record<string, unknown>;
+    }>;
 }
 /**
  * Map of action name to sync definition (no handlers).

package/dist/api/client.d.ts

@@ -2,13 +2,13 @@
  * API Client for Pillar SDK
  * Handles all communication with the Pillar backend
  */
-import type { TaskButtonData } from '../components/Panel/TaskButton';
-import type { ResolvedConfig } from '../core/config';
-import type { Context, Suggestion, UserProfile } from '../core/context';
-import type { Workflow } from '../core/workflow';
-import type { UserContextItem } from '../types/user-context';
-import type { ActionRequest, ChatImage, ImageUploadResponse } from './mcp-client';
-import { MCPClient } from './mcp-client';
+import type { TaskButtonData } from "../components/Panel/TaskButton";
+import type { ResolvedConfig } from "../core/config";
+import type { Context, Suggestion, UserProfile } from "../core/context";
+import type { Workflow } from "../core/workflow";
+import type { UserContextItem } from "../types/user-context";
+import type { ActionRequest, ChatImage, ImageUploadResponse } from "./mcp-client";
+import { MCPClient } from "./mcp-client";
 export interface ArticleSummary {
     id: string;
     title: string;
@@ -17,7 +17,7 @@ export interface ArticleSummary {
     category_name?: string;
 }
 export interface ChatMessage {
-    role: 'user' | 'assistant';
+    role: "user" | "assistant";
     content: string;
 }
 export interface SuggestedQuestion {
@@ -53,7 +53,7 @@ export interface ProgressEvent {
     kind: string;
     id?: string;
     label?: string;
-    status?: 'active' | 'done' | 'error';
+    status?: "active" | "done" | "error";
     text?: string;
     children?: ProgressChild[];
     metadata?: Record<string, unknown>;
@@ -67,7 +67,7 @@ export interface ProgressEvent {
 export interface ServerEmbedConfig {
     panel?: {
         enabled?: boolean;
-        position?: 'left' | 'right';
+        position?: "left" | "right";
         width?: number;
     };
     floatingButton?: {
@@ -91,16 +91,45 @@ export interface ConversationSummary {
     lastMessageAt: string | null;
     messageCount: number;
 }
+/**
+ * Display step in the agent's timeline.
+ * This is a human-readable timeline that includes thinking, tool decisions, and tool results.
+ * Used for UI display of the agent's reasoning process.
+ */
+export interface DisplayStep {
+    step_type: "thinking" | "tool_decision" | "parallel_tool_decision" | "tool_result" | "token_summary" | "step_start" | "generating" | "narration";
+    iteration?: number;
+    timestamp_ms?: number;
+    content?: string;
+    tool?: string;
+    tools?: Array<{
+        tool: string;
+        arguments: Record<string, unknown>;
+    }>;
+    arguments?: Record<string, unknown>;
+    success?: boolean;
+    reasoning?: string;
+    label?: string;
+    [key: string]: unknown;
+}
+/**
+ * Message in conversation history.
+ * Contains display-oriented fields for UI rendering.
+ * LLM-native fields (llm_message) are kept server-side for conversation replay.
+ */
+export interface HistoryMessage {
+    id: string;
+    role: "user" | "assistant";
+    content: string;
+    timestamp: string | null;
+    display_trace?: DisplayStep[];
+    images?: ChatImage[];
+}
 /**
  * Full conversation with messages.
  */
 export interface ConversationDetail extends ConversationSummary {
-    messages: Array<{
-        id: string;
-        role: 'user' | 'assistant';
-        content: string;
-        timestamp: string | null;
-    }>;
+    messages: HistoryMessage[];
 }
 export declare class APIClient {
     private config;
@@ -158,13 +187,22 @@ export declare class APIClient {
      * @returns Promise with signed URL and expiration
      */
     uploadImage(file: File): Promise<ImageUploadResponse>;
-    chat(message: string, history?: ChatMessage[], onChunk?: (chunk: string) => void, articleSlug?: string, existingConversationId?: string | null, onActions?: (actions: TaskButtonData[]) => void, userContext?: UserContextItem[], images?: ChatImage[], onProgress?: (progress: ProgressEvent) => void, onConversationStarted?: (conversationId: string, messageId?: string) => void, onActionRequest?: (request: ActionRequest) => Promise<void>): Promise<ChatResponse>;
-    /**
-     * Legacy chat method using the old /ai/chat/ endpoint.
-     * @deprecated Use chat() which uses the MCP protocol.
-     */
-    chatLegacy(message: string, history?: ChatMessage[], onChunk?: (chunk: string) => void, articleSlug?: string, existingConversationId?: string | null): Promise<ChatResponse>;
-    private handleStreamingChat;
+    chat(opts: {
+        message: string;
+        history?: ChatMessage[];
+        onChunk?: (chunk: string) => void;
+        articleSlug?: string;
+        existingConversationId?: string | null;
+        onActions?: (actions: TaskButtonData[]) => void;
+        userContext?: UserContextItem[];
+        images?: ChatImage[];
+        onProgress?: (progress: ProgressEvent) => void;
+        onConversationStarted?: (conversationId: string, assistantMessageId?: string) => void;
+        onActionRequest?: (request: ActionRequest) => Promise<void>;
+        signal?: AbortSignal;
+        onRequestId?: (requestId: number) => void;
+        resume?: boolean;
+    }): Promise<ChatResponse>;
     /**
      * Submit feedback on an AI assistant message.
      * Fire-and-forget - errors are logged but don't throw.
@@ -173,7 +211,7 @@ export declare class APIClient {
      * @param feedback - 'up' for helpful, 'down' for not helpful
      * @param comment - Optional comment explaining the feedback
      */
-    submitFeedback(messageId: string, feedback: 'up' | 'down', comment?: string): Promise<void>;
+    submitFeedback(messageId: string, feedback: "up" | "down", comment?: string): Promise<void>;
     /**
      * Confirm task execution result.
      * Called by the SDK after a customer's task handler completes.
@@ -183,7 +221,7 @@ export declare class APIClient {
      * @param status - 'success' or 'failure'
      * @param details - Optional execution details
      */
-    confirmTaskExecution(taskId: string, status: 'success' | 'failure', details?: {
+    confirmTaskExecution(taskId: string, status: "success" | "failure", details?: {
         error?: string;
         duration_ms?: number;
         session_id?: string;
@@ -195,13 +233,6 @@ export declare class APIClient {
      * Returns relevant articles, videos, and actions.
      */
     getSuggestions(ctx: Context, userProfile: UserProfile): Promise<Suggestion[]>;
-    /**
-     * Chat with enhanced context.
-     * Includes product context and user profile for better responses.
-     *
-     * Note: Context is passed to the MCP ask tool as additional arguments.
-     */
-    chatWithContext(message: string, history: ChatMessage[] | undefined, ctx: Context, userProfile: UserProfile, onChunk?: (chunk: string) => void, existingConversationId?: string | null, onActions?: (actions: TaskButtonData[]) => void): Promise<ChatResponse>;
     /**
      * Identify the current user after login.
      * Links the anonymous visitor to the authenticated user ID, enabling

package/dist/api/mcp-client.d.ts

@@ -8,7 +8,7 @@ import type { TaskButtonData } from '../components/Panel/TaskButton';
 import type { ResolvedConfig } from '../core/config';
 import type { UserContextItem } from '../types/user-context';
 import { type LogEntry } from '../utils/debug';
-import type { ArticleSummary } from './client';
+import type { ArticleSummary, DisplayStep } from './client';
 /** MCP Tool result content */
 interface ToolResultContent {
     type: 'text' | 'image' | 'resource';
@@ -57,6 +57,27 @@ export interface ActionRequest {
     /** Unique ID for this specific tool invocation (for result correlation) */
     tool_call_id?: string;
 }
+/** Token usage data from the agentic loop (sent after each LLM iteration) */
+export interface TokenUsage {
+    /** Input tokens for this iteration */
+    prompt_tokens: number;
+    /** Output tokens for this iteration */
+    completion_tokens: number;
+    /** Cumulative prompt tokens across all iterations */
+    total_prompt_tokens: number;
+    /** Cumulative completion tokens across all iterations */
+    total_completion_tokens: number;
+    /** Current total tokens in context */
+    total_used: number;
+    /** Maximum context window for the model */
+    context_window: number;
+    /** Current context occupancy percentage (0-100) */
+    occupancy_pct: number;
+    /** Name of the model in use */
+    model_name: string;
+    /** Current iteration number (0-indexed) */
+    iteration: number;
+}
 /** Streaming callbacks for tool calls */
 export interface StreamCallbacks {
     /** Called for each text token */
@@ -69,8 +90,8 @@ export interface StreamCallbacks {
     onRegisteredActions?: (actions: Record<string, unknown>[]) => void;
     /** Called on error */
     onError?: (error: string) => void;
-    /** Called when conversation_started event is received (early conversation_id) */
-    onConversationStarted?: (conversationId: string, messageId?: string) => void;
+    /** Called when conversation_started event is received (confirms conversation tracking) */
+    onConversationStarted?: (conversationId: string, assistantMessageId?: string) => void;
     /** Called when stream is complete */
     onComplete?: (conversationId?: string, queryLogId?: string) => void;
     /** Called for progress updates (search, query, generating, thinking, etc.) */
@@ -89,8 +110,12 @@ export interface StreamCallbacks {
         progress_id?: string;
         message?: string;
     }) => void;
+    /** Called immediately with the request ID (for cancellation support) */
+    onRequestId?: (requestId: number) => void;
     /** Called when agent requests action execution (unified handler) */
     onActionRequest?: (request: ActionRequest) => Promise<void>;
+    /** Called when token usage is updated (after each LLM iteration) */
+    onTokenUsage?: (usage: TokenUsage) => void;
 }
 /** Image for chat requests (from upload-image endpoint) */
 export interface ChatImage {
@@ -98,10 +123,13 @@ export interface ChatImage {
     url: string;
     /** Detail level for image analysis. 'low' is faster and cheaper. */
     detail?: 'low' | 'high';
+    /** GCS storage path for URL refresh on history load */
+    path?: string;
 }
 /** Response from image upload endpoint */
 export interface ImageUploadResponse {
     url: string;
+    path: string;
     expires_at: string;
 }
 export declare class MCPClient {
@@ -174,7 +202,20 @@ export declare class MCPClient {
         /** Registered actions from previous turns (for dynamic action tools) */
         registeredActions?: Record<string, unknown>[];
         signal?: AbortSignal;
+        /** Conversation ID - generated client-side, always provided */
+        conversationId?: string;
+        /** Resume an interrupted session (sends empty query, loads state server-side) */
+        resume?: boolean;
     }): Promise<ToolResult>;
+    /**
+     * Cancel an active streaming request.
+     *
+     * Sends a notifications/cancel JSON-RPC request to the backend, which
+     * signals the StreamRegistry to stop the LLM stream and cease billing.
+     *
+     * @param requestId - The JSON-RPC request ID of the stream to cancel
+     */
+    cancelStream(requestId: number | string): Promise<void>;
     /**
      * Send action result back to the agent.
      *
@@ -214,21 +255,6 @@ export declare class MCPClient {
      * @returns Session status with resumption details, or null if not resumable
      */
     getConversationStatus(conversationId: string): Promise<ConversationStatus | null>;
-    /**
-     * Resume an interrupted conversation.
-     *
-     * Returns a streaming response that continues the conversation
-     * from where it was interrupted.
-     *
-     * @param conversationId - The conversation to resume
-     * @param userContext - Optional current page context
-     * @param callbacks - Streaming callbacks
-     */
-    resumeConversation(conversationId: string, userContext: Record<string, unknown> | undefined, callbacks: StreamCallbacks): Promise<void>;
-    /**
-     * Handle events from the resume stream.
-     */
-    private handleResumeStreamEvent;
 }
 /**
  * Conversation status for session resumption.
@@ -239,11 +265,8 @@ export interface ConversationStatus {
     elapsed_ms?: number;
     user_message?: string;
     partial_response?: string;
-    summary?: string;
-    accomplished?: Array<{
-        action: string;
-        result_summary: string;
-    }>;
+    display_trace?: DisplayStep[];
+    registered_actions?: Record<string, unknown>[];
 }
 /**
  * Convert ActionData from MCP response to TaskButtonData for UI rendering.

package/dist/cli/sync.js

@@ -181,6 +181,8 @@ function buildManifest(actions, platform, version, gitSha, agentGuidance) {
       entry.default_data = definition.defaultData;
     if (definition.requiredContext)
       entry.required_context = definition.requiredContext;
+    if (definition.parameterExamples?.length)
+      entry.parameter_examples = definition.parameterExamples;
     entries.push(entry);
   }
   const manifest = {

package/dist/components/Button/EdgeTrigger.d.ts

@@ -26,6 +26,12 @@ export declare class EdgeTrigger {
     private unsubscribeActiveTab;
     private themeObserver;
     private currentTheme;
+    private _isResizing;
+    private _resizeStartX;
+    private _resizeStartWidth;
+    private _resizeRafId;
+    private _boundHandleResizeMove;
+    private _boundHandleResizeEnd;
     constructor(config: ResolvedConfig, events: EventEmitter, onClick: () => void, rootContainer?: HTMLElement | null);
     /**
      * Handle tab click - sets active tab and opens panel
@@ -75,5 +81,17 @@ export declare class EdgeTrigger {
      * Destroy the trigger
      */
     destroy(): void;
+    /**
+     * Handle resize start from mouse or touch event on the drag handle
+     */
+    private handleResizeStart;
+    /**
+     * Handle resize move - throttled via requestAnimationFrame
+     */
+    private handleResizeMove;
+    /**
+     * Handle resize end - save final width and clean up
+     */
+    private handleResizeEnd;
     private render;
 }

package/dist/components/Cards/ConfirmActionCard.d.ts

@@ -17,7 +17,3 @@ export declare function createDefaultConfirmCard(action: TaskButtonData, callbac
  * Uses custom renderer if registered, otherwise uses default.
  */
 export declare function createConfirmActionCard(action: TaskButtonData, onConfirm: (data?: Record<string, unknown>) => void, onCancel: () => void): HTMLDivElement;
-/**
- * CSS styles for ConfirmActionCard.
- */
-export declare const CONFIRM_CARD_STYLES = "\n/* Confirm Action Card */\n.pillar-confirm-card-wrapper {\n  margin-top: 12px;\n}\n\n.pillar-confirm-card {\n  background: var(--pillar-bg-secondary, #f9fafb);\n  border: 1px solid var(--pillar-border, #e5e7eb);\n  border-radius: 12px;\n  overflow: hidden;\n}\n\n.pillar-confirm-card__content {\n  padding: 16px;\n}\n\n.pillar-confirm-card__header {\n  margin-bottom: 12px;\n}\n\n.pillar-confirm-card__title {\n  font-size: 14px;\n  font-weight: 600;\n  color: var(--pillar-text-primary, #111827);\n}\n\n.pillar-confirm-card__data {\n  background: var(--pillar-bg-primary, #ffffff);\n  border: 1px solid var(--pillar-border, #e5e7eb);\n  border-radius: 8px;\n  padding: 12px;\n  margin-bottom: 12px;\n}\n\n.pillar-confirm-card__data-row {\n  display: flex;\n  gap: 8px;\n  font-size: 13px;\n  margin-bottom: 4px;\n}\n\n.pillar-confirm-card__data-row:last-child {\n  margin-bottom: 0;\n}\n\n.pillar-confirm-card__data-key {\n  color: var(--pillar-text-secondary, #6b7280);\n  flex-shrink: 0;\n}\n\n.pillar-confirm-card__data-value {\n  color: var(--pillar-text-primary, #111827);\n  word-break: break-word;\n}\n\n.pillar-confirm-card__actions {\n  display: flex;\n  gap: 8px;\n  justify-content: flex-end;\n}\n\n.pillar-confirm-card__btn {\n  display: inline-flex;\n  align-items: center;\n  gap: 6px;\n  padding: 8px 14px;\n  font-size: 13px;\n  font-weight: 500;\n  font-family: inherit;\n  border-radius: 8px;\n  cursor: pointer;\n  transition: all 0.15s ease;\n  border: 1px solid transparent;\n}\n\n.pillar-confirm-card__btn:disabled {\n  opacity: 0.6;\n  cursor: not-allowed;\n}\n\n.pillar-confirm-card__btn svg {\n  width: 16px;\n  height: 16px;\n}\n\n.pillar-confirm-card__btn--primary {\n  background: var(--pillar-primary, #2563eb);\n  color: #ffffff;\n  border-color: var(--pillar-primary, #2563eb);\n}\n\n.pillar-confirm-card__btn--primary:hover:not(:disabled) {\n  background: var(--pillar-primary-hover, #1d4ed8);\n  border-color: var(--pillar-primary-hover, #1d4ed8);\n}\n\n.pillar-confirm-card__btn--secondary {\n  background: var(--pillar-bg-primary, #ffffff);\n  color: var(--pillar-text-secondary, #6b7280);\n  border-color: var(--pillar-border, #e5e7eb);\n}\n\n.pillar-confirm-card__btn--secondary:hover:not(:disabled) {\n  background: var(--pillar-bg-secondary, #f9fafb);\n}\n\n.pillar-confirm-card__success {\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  gap: 8px;\n  padding: 16px;\n  color: #059669;\n  font-weight: 500;\n}\n\n.pillar-confirm-card__success-icon svg {\n  width: 20px;\n  height: 20px;\n}\n\n.pillar-confirm-card__error {\n  background: #fef2f2;\n  border: 1px solid #fecaca;\n  border-radius: 8px;\n  padding: 12px;\n  margin-bottom: 12px;\n  color: #dc2626;\n  font-size: 13px;\n}\n\n.pillar-confirm-card__spinner {\n  display: inline-flex;\n  animation: pillar-spin 1s linear infinite;\n}\n\n@keyframes pillar-spin {\n  from { transform: rotate(0deg); }\n  to { transform: rotate(360deg); }\n}\n";

package/dist/components/Cards/index.d.ts

@@ -3,4 +3,4 @@
  *
  * Components for rendering interactive cards in chat responses.
  */
-export { createConfirmActionCard, createDefaultConfirmCard, CONFIRM_CARD_STYLES, } from './ConfirmActionCard';
+export { createConfirmActionCard, createDefaultConfirmCard, } from './ConfirmActionCard';

package/dist/components/DevTools/index.d.ts

@@ -2,4 +2,4 @@
  * DevTools Components
  * Development tools for debugging and previewing Pillar SDK features
  */
-export { DEVTOOLS_STYLES } from './styles';
+export { default as devtoolsCSS } from './devtools.css';

package/dist/components/PagePilot/PagePilotBanner.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Page Pilot Banner Component
+ * Shows "Page being piloted by Agent" with stop button during interact_with_page actions.
+ * When a destructive action is detected, shows a confirmation variant with Allow/Deny buttons.
+ */
+import { h } from 'preact';
+export declare function PagePilotBanner(): h.JSX.Element | null;

package/dist/components/PagePilot/PagePilotManager.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Page Pilot Manager
+ * Manages the "Page being piloted by Agent" banner, rendering it outside Shadow DOM
+ * so it appears above all other content on the page.
+ */
+export declare class PagePilotManager {
+    private container;
+    private stylesInjected;
+    private unsubscribe;
+    private themeObserver;
+    private primaryColor;
+    /**
+     * Detect the current theme from the document
+     * Checks for .dark class (next-themes) or data-theme attribute
+     */
+    private detectThemeFromDOM;
+    /**
+     * Apply theme mode to container element
+     */
+    private applyTheme;
+    /**
+     * Set up observer to watch for theme changes on documentElement
+     */
+    private setupThemeObserver;
+    /**
+     * Initialize the page pilot manager
+     * @param primaryColor - Optional primary color from theme config to override the default
+     */
+    init(primaryColor?: string): void;
+    /**
+     * Update the primary color used by the banner
+     */
+    setPrimaryColor(color: string): void;
+    /**
+     * Destroy the page pilot manager
+     */
+    destroy(): void;
+    /**
+     * Render the banner component
+     */
+    private render;
+}

package/dist/components/PagePilot/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Page Pilot Components
+ * Banner and manager for displaying "Page being piloted by Agent" indicator
+ */
+export { PagePilotBanner } from './PagePilotBanner';
+export { PagePilotManager } from './PagePilotManager';

package/dist/components/PagePilot/styles.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Page Pilot Banner CSS Styles
+ * Injected into the document head (outside Shadow DOM)
+ * Uses the same CSS variables as the Pillar panel for consistent theming
+ */
+export declare const PAGE_PILOT_STYLES = "\n/* Pillar Page Pilot Banner Styles */\n\n/* Define CSS variables at the container level (same as panel) */\n#pillar-page-pilot-container {\n  /* Core colors - Light mode (default) */\n  --pillar-primary: #2563eb;\n  --pillar-primary-hover: #1d4ed8;\n  --pillar-bg: #ffffff;\n  --pillar-bg-secondary: #f9fafb;\n  --pillar-text: #1a1a1a;\n  --pillar-text-secondary: #374151;\n  --pillar-border: #e5e7eb;\n  --pillar-shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.1);\n  --pillar-font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;\n  --pillar-radius-lg: 8px;\n  --pillar-radius-md: 6px;\n  --pillar-transition-fast: 0.15s ease;\n}\n\n/* Dark mode - Auto-detect from system preference */\n@media (prefers-color-scheme: dark) {\n  #pillar-page-pilot-container:not([data-theme=\"light\"]) {\n    --pillar-primary: #3b82f6;\n    --pillar-primary-hover: #60a5fa;\n    --pillar-bg: #1a1a1a;\n    --pillar-bg-secondary: #262626;\n    --pillar-text: #f5f5f5;\n    --pillar-text-secondary: #e5e5e5;\n    --pillar-border: #404040;\n    --pillar-shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.4);\n  }\n}\n\n/* Dark mode - Manual override via html class or data attribute */\nhtml.dark #pillar-page-pilot-container,\n[data-theme=\"dark\"] #pillar-page-pilot-container,\n#pillar-page-pilot-container[data-theme=\"dark\"] {\n  --pillar-primary: #3b82f6;\n  --pillar-primary-hover: #60a5fa;\n  --pillar-bg: #1a1a1a;\n  --pillar-bg-secondary: #262626;\n  --pillar-text: #f5f5f5;\n  --pillar-text-secondary: #e5e5e5;\n  --pillar-border: #404040;\n  --pillar-shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.4);\n}\n\n@keyframes pillar-pulse {\n  0%, 100% {\n    opacity: 1;\n    transform: scale(1);\n  }\n  50% {\n    opacity: 0.6;\n    transform: scale(1.1);\n  }\n}\n\n@keyframes pillar-banner-fade-in {\n  from {\n    opacity: 0;\n    transform: translateY(-100%);\n  }\n  to {\n    opacity: 1;\n    transform: translateY(0);\n  }\n}\n\n._pillar-page-pilot-banner {\n  position: fixed;\n  top: 0;\n  left: 0;\n  right: 0;\n  z-index: 99999;\n  font-family: var(--pillar-font-family);\n  display: flex;\n  justify-content: center;\n  pointer-events: none;\n  animation: pillar-banner-fade-in 0.2s ease-out;\n}\n\n/* Viewport outline \u2014 3px border on left, right, bottom; top handled by tab shape */\n._pillar-page-pilot-banner::before {\n  content: '';\n  position: fixed;\n  inset: 0;\n  border: 3px solid var(--pillar-primary);\n  border-top: none;\n  pointer-events: none;\n  z-index: 99998;\n}\n\n/* Top border segments on either side of the tab */\n._pillar-page-pilot-banner::after {\n  content: '';\n  position: fixed;\n  top: 0;\n  left: 0;\n  right: 0;\n  height: 3px;\n  background: var(--pillar-primary);\n  pointer-events: none;\n  z-index: 99997;\n}\n\n._pillar-page-pilot-banner__content {\n  position: relative;\n  z-index: 99999;\n  display: flex;\n  align-items: center;\n  gap: 12px;\n  padding: 6px 20px;\n  background: var(--pillar-primary);\n  color: #ffffff;\n  border-bottom-left-radius: var(--pillar-radius-lg);\n  border-bottom-right-radius: var(--pillar-radius-lg);\n  pointer-events: auto;\n}\n\n._pillar-page-pilot-banner__indicator {\n  width: 8px;\n  height: 8px;\n  background: #ffffff;\n  border-radius: 50%;\n  animation: pillar-pulse 1.5s ease-in-out infinite;\n  flex-shrink: 0;\n}\n\n._pillar-page-pilot-banner__text {\n  font-size: 13px;\n  font-weight: 500;\n  color: #ffffff;\n  white-space: nowrap;\n}\n\n._pillar-page-pilot-banner__stop {\n  display: flex;\n  align-items: center;\n  gap: 4px;\n  padding: 5px 10px;\n  margin-left: 4px;\n  font-family: inherit;\n  font-size: 12px;\n  font-weight: 500;\n  color: #ffffff;\n  background: rgba(255, 255, 255, 0.15);\n  border: 1px solid rgba(255, 255, 255, 0.3);\n  border-radius: var(--pillar-radius-md);\n  cursor: pointer;\n  transition: all var(--pillar-transition-fast);\n}\n\n._pillar-page-pilot-banner__stop:hover {\n  background: rgba(255, 255, 255, 0.25);\n  border-color: rgba(255, 255, 255, 0.5);\n}\n\n._pillar-page-pilot-banner__stop:active {\n  transform: scale(0.97);\n}\n\n._pillar-page-pilot-banner__stop-icon {\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  width: 14px;\n  height: 14px;\n}\n\n._pillar-page-pilot-banner__stop-icon svg {\n  width: 100%;\n  height: 100%;\n}\n\n/* Confirmation variant \u2014 amber/warning theme */\n._pillar-page-pilot-banner--confirm ._pillar-page-pilot-banner__content {\n  background: #d97706;\n}\n\n._pillar-page-pilot-banner--confirm::before {\n  border-color: #d97706;\n}\n\n._pillar-page-pilot-banner--confirm::after {\n  background: #d97706;\n}\n\n._pillar-page-pilot-banner__warning-icon {\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  width: 14px;\n  height: 14px;\n  flex-shrink: 0;\n}\n\n._pillar-page-pilot-banner__warning-icon svg {\n  width: 100%;\n  height: 100%;\n}\n\n._pillar-page-pilot-banner__deny {\n  display: flex;\n  align-items: center;\n  padding: 5px 12px;\n  margin-left: 4px;\n  font-family: inherit;\n  font-size: 12px;\n  font-weight: 500;\n  color: #ffffff;\n  background: rgba(255, 255, 255, 0.15);\n  border: 1px solid rgba(255, 255, 255, 0.3);\n  border-radius: var(--pillar-radius-md);\n  cursor: pointer;\n  transition: all var(--pillar-transition-fast);\n}\n\n._pillar-page-pilot-banner__deny:hover {\n  background: rgba(255, 255, 255, 0.25);\n  border-color: rgba(255, 255, 255, 0.5);\n}\n\n._pillar-page-pilot-banner__deny:active {\n  transform: scale(0.97);\n}\n\n._pillar-page-pilot-banner__allow {\n  display: flex;\n  align-items: center;\n  padding: 5px 12px;\n  font-family: inherit;\n  font-size: 12px;\n  font-weight: 600;\n  color: #d97706;\n  background: #ffffff;\n  border: 1px solid rgba(255, 255, 255, 0.8);\n  border-radius: var(--pillar-radius-md);\n  cursor: pointer;\n  transition: all var(--pillar-transition-fast);\n}\n\n._pillar-page-pilot-banner__allow:hover {\n  background: #fef3c7;\n}\n\n._pillar-page-pilot-banner__allow:active {\n  transform: scale(0.97);\n}\n";

package/dist/components/Panel/Header.d.ts

@@ -1,14 +1,13 @@
 /**
  * Panel Header Component
- * Navigation header with back, home, history, and close buttons
+ * Navigation header with back, home, history, and close buttons.
+ * In mobile mode, the header doubles as a drag handle: swipe down to dismiss.
  */
-import { h } from 'preact';
-import { type ViewType } from '../../store/router';
+import { type ViewType } from "../../store/router";
 interface HeaderProps {
     currentView: ViewType;
-    customTitle?: string;
     /** Hide back and home navigation buttons */
     hideNavigation?: boolean;
 }
-export declare function Header({ currentView, customTitle, hideNavigation }: HeaderProps): h.JSX.Element;
+export declare function Header({ currentView, hideNavigation }: HeaderProps): import("preact").JSX.Element;
 export {};

package/dist/components/Panel/Panel.d.ts

@@ -2,9 +2,9 @@
  * Panel Container Component
  * Shadow DOM container for the help panel with Preact rendering
  */
-import type { APIClient } from '../../api/client';
-import type { ResolvedConfig } from '../../core/config';
-import type { EventEmitter } from '../../core/events';
+import type { APIClient } from "../../api/client";
+import type { ResolvedConfig } from "../../core/config";
+import type { EventEmitter } from "../../core/events";
 export declare class Panel {
     private config;
     private api;
@@ -54,6 +54,12 @@ export declare class Panel {
      */
     destroy(): void;
     private subscribeToState;
+    /**
+     * Toggle backdrop visibility using inline styles.
+     * The backdrop is created with inline styles, so we must toggle via
+     * inline styles too (class-based overrides lose to inline specificity).
+     */
+    private setBackdropVisible;
     private applyPushModeStyles;
     private removePushModeStyles;
     /**
@@ -101,5 +107,5 @@ export declare class Panel {
     /**
      * Update the theme at runtime
      */
-    setTheme(themeConfig: Partial<ResolvedConfig['theme']>): void;
+    setTheme(themeConfig: Partial<ResolvedConfig["theme"]>): void;
 }

package/dist/components/Panel/PanelContent.d.ts

@@ -2,5 +2,4 @@
  * Panel Content Component
  * Main panel layout with header, content, and chat input
  */
-import { h } from 'preact';
-export declare function PanelContent(): h.JSX.Element;
+export declare function PanelContent(): import("preact").JSX.Element;

package/dist/components/Panel/TaskButton.d.ts

@@ -42,8 +42,4 @@ export declare function createTaskButton(props: TaskButtonProps): HTMLButtonElem
  * Create a container with multiple task buttons.
  */
 export declare function createTaskButtonGroup(tasks: TaskButtonData[]): HTMLDivElement;
-/**
- * CSS styles for TaskButton (to be added to PANEL_STYLES).
- */
-export declare const TASK_BUTTON_STYLES = "\n/* Task Button Component */\n.pillar-task-btn {\n  display: inline-flex;\n  align-items: center;\n  gap: 6px;\n  padding: 8px 14px;\n  font-size: 13px;\n  font-weight: 500;\n  font-family: inherit;\n  border-radius: 8px;\n  cursor: pointer;\n  transition: all 0.15s ease;\n  border: 1px solid transparent;\n  text-decoration: none;\n}\n\n.pillar-task-btn__icon {\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  flex-shrink: 0;\n}\n\n.pillar-task-btn__icon svg {\n  width: 16px;\n  height: 16px;\n}\n\n.pillar-task-btn__label {\n  white-space: nowrap;\n}\n\n/* Primary variant (default) */\n.pillar-task-btn--primary {\n  background: #2563eb;\n  color: #ffffff;\n  border-color: #2563eb;\n}\n\n.pillar-task-btn--primary:hover {\n  background: #1d4ed8;\n  border-color: #1d4ed8;\n}\n\n/* Default variant */\n.pillar-task-btn--default {\n  background: #f3f4f6;\n  color: #1a1a1a;\n  border-color: #e5e7eb;\n}\n\n.pillar-task-btn--default:hover {\n  background: #e5e7eb;\n}\n\n/* Secondary variant */\n.pillar-task-btn--secondary {\n  background: #eff6ff;\n  color: #2563eb;\n  border-color: #dbeafe;\n}\n\n.pillar-task-btn--secondary:hover {\n  background: #dbeafe;\n}\n\n/* Outline variant */\n.pillar-task-btn--outline {\n  background: transparent;\n  color: #2563eb;\n  border-color: #2563eb;\n}\n\n.pillar-task-btn--outline:hover {\n  background: #eff6ff;\n}\n\n/* Ghost variant */\n.pillar-task-btn--ghost {\n  background: transparent;\n  color: #6b7280;\n  border-color: transparent;\n}\n\n.pillar-task-btn--ghost:hover {\n  background: #f3f4f6;\n  color: #1a1a1a;\n}\n\n/* Active state for inline_ui buttons with expanded card */\n.pillar-task-btn--active {\n  background: #1d4ed8;\n  border-color: #1d4ed8;\n}\n\n/* Task button group */\n.pillar-task-btn-group {\n  display: flex;\n  flex-wrap: wrap;\n  gap: 8px;\n  margin-top: 12px;\n}\n\n/* Inline card container for inline_ui actions */\n.pillar-task-btn-inline-card {\n  margin-top: 12px;\n  animation: pillar-slide-down 0.15s ease-out;\n}\n\n@keyframes pillar-slide-down {\n  from {\n    opacity: 0;\n    transform: translateY(-8px);\n  }\n  to {\n    opacity: 1;\n    transform: translateY(0);\n  }\n}\n\n/* Task suggestion card in chat */\n.pillar-task-suggestion {\n  display: flex;\n  flex-direction: column;\n  gap: 8px;\n  padding: 12px;\n  background: #f9fafb;\n  border: 1px solid #e5e7eb;\n  border-radius: 12px;\n  margin-top: 12px;\n}\n\n.pillar-task-suggestion__header {\n  display: flex;\n  align-items: center;\n  gap: 6px;\n  font-size: 11px;\n  font-weight: 600;\n  text-transform: uppercase;\n  letter-spacing: 0.5px;\n  color: #6b7280;\n}\n\n.pillar-task-suggestion__header svg {\n  width: 14px;\n  height: 14px;\n}\n\n.pillar-task-suggestion__description {\n  font-size: 13px;\n  color: #374151;\n}\n";
 export {};