@pillar-ai/sdk 0.1.14 → 0.1.16

package/dist/store/chat.d.ts

@@ -2,39 +2,86 @@
  * Chat Store
  * Signal-based state for chat messages and interaction
  */
-import type { ArticleSummary, ChatMessage } from '../api/client';
-import type { ChatImage } from '../api/mcp-client';
-import type { TaskButtonData } from '../components/Panel/TaskButton';
-import type { UserContextItem } from '../types/user-context';
-export type { ChatImage } from '../api/mcp-client';
+import type { ArticleSummary, ChatMessage, ConversationSummary, HistoryMessage, DisplayStep } from "../api/client";
+import type { ChatImage } from "../api/mcp-client";
+import type { TaskButtonData } from "../components/Panel/TaskButton";
+import type { UserContextItem } from "../types/user-context";
+export type { ChatImage } from "../api/mcp-client";
 export interface ActionStatus {
-    status: 'pending' | 'success' | 'failed';
+    status: "pending" | "success" | "failed";
     completedAt?: number;
     errorMessage?: string;
 }
+/**
+ * A segment in an assistant message's timeline.
+ * Segments maintain chronological order so text and tool blocks interleave correctly.
+ *
+ * - "text": Model-generated content tokens (narration or final response)
+ * - "progress": A group of progress events (thinking, search, tool calls)
+ */
+export type MessageSegment = {
+    type: "text";
+    content: string;
+} | {
+    type: "progress";
+    events: ProgressEvent[];
+};
 export interface StoredChatMessage extends ChatMessage {
     id?: string;
-    feedback?: 'up' | 'down' | null;
+    feedback?: "up" | "down" | null;
     actions?: TaskButtonData[];
     sources?: ArticleSummary[];
     actionStatus?: Record<string, ActionStatus>;
     userContext?: UserContextItem[];
     images?: ChatImage[];
     progressEvents?: ProgressEvent[];
+    segments?: MessageSegment[];
 }
 export declare const messages: import("@preact/signals-core").Signal<StoredChatMessage[]>;
 export declare const conversationId: import("@preact/signals-core").Signal<string | null>;
 export declare const registeredActions: import("@preact/signals-core").Signal<Record<string, unknown>[]>;
 export declare const historyInvalidationCounter: import("@preact/signals-core").Signal<number>;
+export declare const optimisticConversations: import("@preact/signals-core").Signal<ConversationSummary[]>;
+/**
+ * Read the persisted conversation ID from localStorage (e.g. for restore on refresh).
+ */
+export declare function getStoredConversationId(): string | null;
 export declare const isLoading: import("@preact/signals-core").Signal<boolean>;
+export declare const activeRequestId: import("@preact/signals-core").Signal<number | null>;
+export declare const setActiveRequestId: (id: number | null) => void;
+export declare const isLoadingHistory: import("@preact/signals-core").Signal<boolean>;
 export interface InterruptedSession {
     conversationId: string;
     userMessage: string;
     partialResponse: string;
-    summary: string;
+    displayTrace: DisplayStep[];
     elapsedMs: number;
 }
 export declare const interruptedSession: import("@preact/signals-core").Signal<InterruptedSession | null>;
+export interface TokenUsageState {
+    /** Input tokens for the latest iteration */
+    promptTokens: number;
+    /** Output tokens for the latest iteration */
+    completionTokens: number;
+    /** Cumulative prompt tokens across all iterations */
+    totalPromptTokens: number;
+    /** Cumulative completion tokens across all iterations */
+    totalCompletionTokens: number;
+    /** Current total tokens in context */
+    totalUsed: number;
+    /** Maximum context window for the model */
+    contextWindow: number;
+    /** Current context occupancy percentage (0-100) */
+    occupancyPct: number;
+    /** Name of the model in use */
+    modelName: string;
+    /** Current iteration number (0-indexed) */
+    iteration: number;
+}
+/** Current token usage for the active streaming response */
+export declare const tokenUsage: import("@preact/signals-core").Signal<TokenUsageState | null>;
+export declare const updateTokenUsage: (usage: TokenUsageState) => void;
+export declare const clearTokenUsage: () => void;
 export interface ProgressStatus {
     kind: string | null;
     message?: string;
@@ -59,7 +106,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>;
@@ -85,6 +132,12 @@ export declare const progressEvents: import("@preact/signals-core").Signal<Progr
  * This prevents multiple rows from appearing for the same event.
  */
 export declare const addProgressEventToLastMessage: (event: ProgressEvent) => void;
+/**
+ * Append a content token to the last assistant message's segments array.
+ * Creates a new text segment or appends to an existing one, while also
+ * updating `content` for backward compat (history persistence, feedback, etc.).
+ */
+export declare const appendTokenToSegments: (token: string) => 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.
@@ -104,7 +157,8 @@ export declare const submitPendingTrigger: import("@preact/signals-core").Signal
 export declare const focusInputTrigger: import("@preact/signals-core").Signal<number>;
 export declare const userContext: import("@preact/signals-core").Signal<UserContextItem[]>;
 export declare const pendingUserContext: import("@preact/signals-core").Signal<UserContextItem[]>;
-export type ImageUploadStatus = 'uploading' | 'ready' | 'error';
+export declare const pendingImagesForNavigation: import("@preact/signals-core").Signal<ChatImage[]>;
+export type ImageUploadStatus = "uploading" | "ready" | "error";
 export interface PendingImage {
     id: string;
     file: File;
@@ -112,12 +166,13 @@ export interface PendingImage {
     status: ImageUploadStatus;
     url?: string;
     error?: string;
+    path?: string;
 }
 export declare const pendingImages: import("@preact/signals-core").Signal<PendingImage[]>;
 export declare const isUploadingImages: import("@preact/signals-core").ReadonlySignal<boolean>;
 export declare const getReadyImages: () => ChatImage[];
 export declare const addPendingImage: (image: PendingImage) => void;
-export declare const updateImageStatus: (id: string, status: ImageUploadStatus, url?: string, error?: string) => void;
+export declare const updateImageStatus: (id: string, status: ImageUploadStatus, url?: string, error?: string, path?: string) => void;
 export declare const removePendingImage: (id: string) => void;
 export declare const clearPendingImages: () => void;
 export declare const hasMessages: import("@preact/signals-core").ReadonlySignal<boolean>;
@@ -154,10 +209,24 @@ export declare const clearActions: () => void;
 export declare const setLoading: (loading: boolean) => void;
 export declare const setProgressStatus: (status: ProgressStatus) => void;
 export declare const clearProgressStatus: () => void;
+/**
+ * Mark all active progress events on the last assistant message as "done".
+ * Called when the user cancels/stops streaming so thinking timers stop.
+ */
+export declare const finalizeActiveProgressEvents: () => void;
 export declare const addProgressEvent: (event: ProgressEvent) => void;
 export declare const clearProgressEvents: () => void;
 export declare const setInterruptedSession: (session: InterruptedSession | null) => void;
 export declare const clearInterruptedSession: () => void;
+/**
+ * Remove the last assistant message if it has no content AND no progress events.
+ * Used after Stop / AbortError to clean up the empty placeholder
+ * that was added before streaming started.
+ *
+ * If the model was thinking (progress events exist), the message is kept
+ * so the user can still see the thinking text that was streamed.
+ */
+export declare const removeLastEmptyAssistantMessage: () => void;
 export declare const expandChat: () => void;
 export declare const collapseChat: () => void;
 export declare const setPrefillText: (text: string) => void;
@@ -171,13 +240,31 @@ export declare const removeUserContext: (id: string) => void;
 export declare const clearUserContext: () => void;
 export declare const setPendingUserContext: (items: UserContextItem[]) => void;
 export declare const clearPendingUserContext: () => void;
+export declare const setPendingImagesForNavigation: (images: ChatImage[]) => void;
+export declare const clearPendingImagesForNavigation: () => void;
 export declare const resetChat: () => void;
+/**
+ * Start loading a conversation from history.
+ * Shows loading state immediately for better UX.
+ */
+export declare const startLoadingHistory: () => void;
 /**
  * Load a conversation from history.
  * Populates the chat with messages from a previous conversation.
  */
-export declare const loadConversation: (id: string, historyMessages: Array<{
-    role: "user" | "assistant";
-    content: string;
-    id?: string;
-}>) => void;
+export declare const loadConversation: (id: string, historyMessages: HistoryMessage[]) => void;
+/**
+ * Stop loading history (on error or cancellation).
+ */
+export declare const stopLoadingHistory: () => void;
+/**
+ * Optimistically add a new conversation to the history list.
+ * The conversation appears immediately in the dropdown without
+ * waiting for the server to confirm via listConversations.
+ */
+export declare const addOptimisticConversation: (id: string, title: string) => void;
+/**
+ * Select and load a conversation by ID (fetch from API, navigate to chat, load messages).
+ * Use from history dropdown or anywhere else in the SDK that needs to open a past conversation.
+ */
+export declare const selectConversationById: (conversationId: string) => Promise<void>;

package/dist/store/index.d.ts

@@ -8,3 +8,4 @@ export * as chatStore from './chat';
 export * as contextStore from './context';
 export * as workflowStore from './workflow';
 export * as suggestionsStore from './suggestions';
+export * as pagePilotStore from './pagePilot';

package/dist/store/pagePilot.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Page Pilot Store
+ * Signal-based state for tracking when the AI agent is piloting the page
+ * (executing interact_with_page actions like click, type, select, etc.)
+ */
+/** Current piloting operation type */
+export type PilotOperation = 'click' | 'type' | 'select' | 'focus' | 'toggle' | null;
+/** Whether page interaction is currently in progress */
+export declare const isPiloting: import("@preact/signals-core").Signal<boolean>;
+/** Current operation type being performed */
+export declare const pilotOperation: import("@preact/signals-core").Signal<PilotOperation>;
+/** Flag to indicate cancellation was requested */
+export declare const isCancelled: import("@preact/signals-core").Signal<boolean>;
+/** Tool call ID of the current action (for sending cancellation result) */
+export declare const currentToolCallId: import("@preact/signals-core").Signal<string | null>;
+/**
+ * Start piloting mode - called when an interact_with_page action begins
+ */
+export declare function startPiloting(operation: PilotOperation, toolCallId?: string): void;
+/**
+ * Stop piloting mode - called when an interact_with_page action completes
+ */
+export declare function stopPiloting(): void;
+/**
+ * Cancel the current piloting action - called when user clicks Stop
+ */
+export declare function cancelPiloting(): void;
+/**
+ * Reset cancellation flag after it's been handled
+ */
+export declare function resetCancellation(): void;
+/**
+ * Check if cancellation was requested
+ */
+export declare function wasCancelled(): boolean;
+/** Whether a destructive action is awaiting user confirmation */
+export declare const needsConfirmation: import("@preact/signals-core").Signal<boolean>;
+/** Human-readable description of the action pending confirmation */
+export declare const confirmationLabel: import("@preact/signals-core").Signal<string | null>;
+/** Resolver function for the confirmation promise */
+export declare const confirmationResolver: import("@preact/signals-core").Signal<((confirmed: boolean) => void) | null>;
+/**
+ * Request user confirmation for a destructive action.
+ * Shows a confirmation UI and returns a Promise that resolves when the user responds.
+ *
+ * @param label - Description of the action (e.g., 'Agent wants to click "Delete Account"')
+ * @returns Promise<boolean> - true if user confirmed, false if denied
+ */
+export declare function requestConfirmation(label: string): Promise<boolean>;
+/**
+ * Resolve the pending confirmation request.
+ * Called by the UI when the user clicks Allow or Deny.
+ *
+ * @param confirmed - Whether the user confirmed the action
+ */
+export declare function resolveConfirmation(confirmed: boolean): void;

package/dist/store/panel.d.ts

@@ -3,6 +3,15 @@
  * Signal-based state for panel open/close and configuration
  */
 import type { PanelPosition, PanelMode } from '../core/config';
+/**
+ * Load panel width from localStorage.
+ * Returns null if not set or on error.
+ */
+export declare function loadPanelWidth(): number | null;
+/**
+ * Save panel width to localStorage.
+ */
+export declare function savePanelWidth(w: number): void;
 export declare const isOpen: import("@preact/signals-core").Signal<boolean>;
 export declare const activeTab: import("@preact/signals-core").Signal<string>;
 export declare const position: import("@preact/signals-core").Signal<PanelPosition>;

package/dist/store/suggestions.d.ts

@@ -2,12 +2,12 @@
  * Suggestions Store
  * Signal-based state for page-aware suggested questions
  *
- * The backend generates a pool of 15-20 diverse suggestions.
+ * The backend generates a small set of suggested questions.
  * This store sorts them client-side based on page relevance
  * for instant page-aware suggestions without additional LLM calls.
  */
 import type { SuggestedQuestion } from '../api/client';
-/** Base suggestion pool from backend (15-20 suggestions) */
+/** Base suggestion pool from backend */
 export declare const suggestionPool: import("@preact/signals-core").Signal<SuggestedQuestion[]>;
 /** Currently displayed suggestions (sorted by page relevance) */
 export declare const suggestions: import("@preact/signals-core").Signal<SuggestedQuestion[]>;

package/dist/styles/panel-styles.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Panel Styles Aggregator
+ * Imports all CSS files that are injected into the Panel (Shadow DOM or head)
+ * and exports them as a single concatenated string.
+ */
+export declare const ALL_PANEL_STYLES: string;

package/dist/styles/theme.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Theme CSS Generation
+ * Runtime functions for generating CSS variable overrides from theme config.
+ */
+import type { ResolvedThemeConfig, ThemeColors } from "../core/config";
+/**
+ * Generate CSS variable overrides from theme colors
+ */
+export declare function generateThemeVariables(colors: ThemeColors, prefix?: string): string;
+/**
+ * Generate custom theme CSS from config
+ */
+export declare function generateThemeCSS(theme: ResolvedThemeConfig): string;

package/dist/types/dom-scanner.d.ts

@@ -20,6 +20,10 @@ export interface ScanOptions {
     minTextLength?: number;
     /** Maximum text length before truncation (default: 500) */
     maxTextLength?: number;
+    /** Maximum total output length in characters (default: 50000) */
+    maxTotalLength?: number;
+    /** Maximum label length for interactable elements (default: 100) */
+    maxLabelLength?: number;
     /** Include element positions/coordinates (default: false) */
     includePositions?: boolean;
 }
@@ -38,6 +42,25 @@ export interface CompactScanResult {
     /** Title of the page */
     title: string;
 }
+/** Result of a delta scan showing only changes since the last scan */
+export interface DeltaScanResult {
+    /** Formatted delta string for LLM context, or null if no changes */
+    content: string | null;
+    /** Ref IDs of elements no longer on the page */
+    removedRefs: string[];
+    /** Number of new interactable elements found */
+    newInteractableCount: number;
+    /** Total interactable elements currently on the page */
+    totalInteractableCount: number;
+    /** Whether any changes were detected */
+    hasChanges: boolean;
+    /** Timestamp when scan was performed */
+    timestamp: number;
+    /** URL of the page that was scanned */
+    url: string;
+    /** Title of the page */
+    title: string;
+}
 /** HTML tags that are inherently interactable */
 export declare const INTERACTABLE_TAGS: Set<string>;
 /** ARIA roles that indicate interactability */

package/dist/utils/dom-scanner.d.ts

@@ -2,12 +2,28 @@
  * DOM Scanner Utilities
  * Scans the DOM and outputs compact text representation for LLM context
  */
-import { type CompactScanResult, type InteractionType, type ScanOptions } from "../types/dom-scanner";
+import { type CompactScanResult, type DeltaScanResult, type InteractionType, type ScanOptions } from "../types/dom-scanner";
 /**
  * Clear all pillar refs from the DOM.
- * Called before scanning to remove stale refs.
+ * Called before full scans to remove stale refs and reset counter.
  */
 export declare function clearPillarRefs(): void;
+/**
+ * Check if an element or any of its ancestors is marked for redaction.
+ * Elements with `data-pillar-redact` or password inputs are redacted.
+ * Their text content is replaced with [REDACTED] in scan output.
+ */
+export declare function isRedacted(el: Element): boolean;
+/**
+ * Check if an element represents a destructive action.
+ * Used to gate interactions behind user confirmation.
+ *
+ * Returns true if:
+ * - The element has `data-pillar-destructive` attribute (explicit opt-in)
+ * - The element's label or text content contains destructive keywords
+ * - The element is a reset/submit button on a form with "delete" in its action URL
+ */
+export declare function isDestructiveElement(el: Element): boolean;
 /**
  * Check if an element is interactable
  */
@@ -16,12 +32,22 @@ export declare function isInteractable(el: Element): boolean;
  * Determine the interaction type for an element
  */
 export declare function getInteractionType(el: Element): InteractionType;
+/**
+ * Validate that a ref string matches the expected pillar ref format.
+ * Prevents CSS selector injection from malformed/malicious ref values.
+ *
+ * @param ref - Ref string to validate
+ * @returns true if the ref matches the expected format
+ */
+export declare function isValidPillarRef(ref: string): boolean;
 /**
  * Build full selector from short ref ID.
  * Converts "pr-abc" to '[data-pillar-ref="pr-abc"]'
+ * Throws if the ref format is invalid to prevent CSS selector injection.
  *
  * @param shortRef - Short ref ID (e.g., "pr-abc")
  * @returns Full CSS selector for querySelector
+ * @throws Error if the ref format is invalid
  */
 export declare function buildSelectorFromRef(shortRef: string): string;
 /**
@@ -42,3 +68,16 @@ export declare function buildSelectorFromRef(shortRef: string): string;
  * ```
  */
 export declare function scanPageDirect(options?: ScanOptions): CompactScanResult;
+/**
+ * Delta DOM scanner that only returns changes since the last scan.
+ * Reuses existing refs on elements, assigns new refs only to new elements.
+ * Compares output lines against the previous scan to find new content.
+ *
+ * Must be called after an initial `scanPageDirect()` which establishes
+ * the baseline. If called without a prior scan, behaves like a full scan
+ * but without the header/footer framing.
+ *
+ * @param options - Scan options
+ * @returns Delta scan result with only new lines and removed ref IDs
+ */
+export declare function scanPageDelta(options?: ScanOptions): DeltaScanResult;

package/dist/utils/markdown-components.d.ts

@@ -50,4 +50,3 @@ export interface ProgressIndicatorProps {
     isActive?: boolean;
 }
 export declare function ProgressIndicator({ message, isActive, }: ProgressIndicatorProps): VNode;
-export declare const MARKDOWN_COMPONENT_STYLES = "\n/* Collapsible Section */\n._pillar-collapsible {\n  margin: 2px 0;\n}\n\n._pillar-collapsible-header {\n  display: flex;\n  align-items: center;\n  gap: 6px;\n  padding: 4px 0;\n  background: transparent;\n  border: none;\n  border-radius: 4px;\n  cursor: pointer;\n  font-size: 13px;\n  font-weight: 500;\n  color: var(--pillar-text-secondary, #6b7280);\n  font-family: inherit;\n  width: 100%;\n  text-align: left;\n  transition: background-color 0.15s ease;\n}\n\n._pillar-collapsible-header:hover {\n  background: var(--pillar-bg-hover, rgba(0, 0, 0, 0.05));\n}\n\n._pillar-collapsible-icon {\n  font-size: 10px;\n  color: var(--pillar-text-muted, #9ca3af);\n}\n\n._pillar-collapsible-title {\n  flex: 1;\n}\n\n._pillar-collapsible-content-wrapper {\n  display: grid;\n  grid-template-rows: 0fr;\n  transition: grid-template-rows 0.2s ease;\n}\n\n._pillar-collapsible-content-wrapper--expanded {\n  grid-template-rows: 1fr;\n}\n\n._pillar-collapsible-content {\n  overflow: hidden;\n  padding-left: 18px;\n  font-size: 13px;\n  color: var(--pillar-text-secondary, #6b7280);\n  line-height: 1.4;\n}\n\n._pillar-collapsible-content-wrapper--expanded ._pillar-collapsible-content {\n  padding-top: 2px;\n  padding-bottom: 4px;\n}\n\n/* Source List */\n._pillar-source-list {\n  display: flex;\n  flex-direction: column;\n  gap: 4px;\n  margin: 4px 0;\n}\n\n._pillar-source-item {\n  display: block;\n  padding: 4px 8px;\n  font-size: 12px;\n  color: var(--pillar-primary, #2563eb);\n  text-decoration: none;\n  border-radius: 4px;\n  transition: background-color 0.15s ease;\n}\n\n._pillar-source-item:hover {\n  background: var(--pillar-bg-hover, rgba(0, 0, 0, 0.05));\n  text-decoration: underline;\n}\n\n/* Task List */\n._pillar-task-list {\n  list-style: none;\n  padding: 0;\n  margin: 8px 0;\n}\n\n._pillar-task-item {\n  display: flex;\n  align-items: center;\n  gap: 8px;\n  padding: 4px 0;\n  font-size: 13px;\n}\n\n._pillar-task-item--completed ._pillar-task-text {\n  text-decoration: line-through;\n  color: var(--pillar-text-placeholder, #9ca3af);\n}\n\n._pillar-task-checkbox {\n  width: 16px;\n  height: 16px;\n  cursor: pointer;\n}\n\n/* Code Block */\n._pillar-code-block {\n  margin: 8px 0;\n  border-radius: 8px;\n  overflow: hidden;\n  background: var(--pillar-bg-code, #1e1e1e);\n}\n\n._pillar-code-header {\n  display: flex;\n  justify-content: space-between;\n  align-items: center;\n  padding: 8px 12px;\n  background: var(--pillar-bg-code-header, #2d2d2d);\n  border-bottom: 1px solid var(--pillar-border-code, #404040);\n}\n\n._pillar-code-language {\n  font-size: 11px;\n  font-weight: 500;\n  color: var(--pillar-text-code-header, #a0a0a0);\n  text-transform: uppercase;\n}\n\n._pillar-code-copy {\n  padding: 4px 8px;\n  font-size: 11px;\n  font-family: inherit;\n  background: transparent;\n  border: 1px solid var(--pillar-border-code, #404040);\n  border-radius: 4px;\n  color: var(--pillar-text-code-header, #a0a0a0);\n  cursor: pointer;\n  transition: all 0.15s ease;\n}\n\n._pillar-code-copy:hover {\n  background: var(--pillar-bg-code-hover, #404040);\n  color: #fff;\n}\n\n._pillar-code-pre {\n  margin: 0;\n  padding: 12px;\n  overflow-x: auto;\n  font-family: 'SF Mono', Monaco, 'Cascadia Code', 'Roboto Mono', Consolas, monospace;\n  font-size: 13px;\n  line-height: 1.5;\n}\n\n._pillar-code-content {\n  color: var(--pillar-text-code, #e0e0e0);\n}\n\n/* Action Buttons */\n._pillar-action-buttons {\n  display: flex;\n  flex-wrap: wrap;\n  gap: 8px;\n  margin: 8px 0;\n}\n\n._pillar-action-button {\n  padding: 8px 16px;\n  font-size: 13px;\n  font-weight: 500;\n  font-family: inherit;\n  background: var(--pillar-primary, #2563eb);\n  color: #fff;\n  border: none;\n  border-radius: 6px;\n  cursor: pointer;\n  transition: all 0.15s ease;\n}\n\n._pillar-action-button:hover {\n  background: var(--pillar-primary-hover, #1d4ed8);\n}\n\n/* Progress Indicator */\n._pillar-progress-indicator {\n  display: flex;\n  align-items: center;\n  gap: 6px;\n  padding: 4px 0;\n  font-size: 13px;\n  color: var(--pillar-text-secondary, #6b7280);\n}\n\n._pillar-progress-indicator--active ._pillar-loading-spinner {\n  display: inline-block;\n}\n\n/* Streaming Thinking Content */\n._pillar-progress-row--streaming {\n  margin: 2px 0;\n}\n\n._pillar-thinking-header {\n  display: flex;\n  align-items: center;\n  gap: 6px;\n  padding: 4px 0;\n  font-size: 13px;\n  font-weight: 500;\n  color: var(--pillar-text-secondary, #6b7280);\n}\n\n._pillar-thinking-icon {\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  width: 16px;\n  height: 16px;\n}\n\n._pillar-spinner {\n  width: 12px;\n  height: 12px;\n  border: 2px solid var(--pillar-border, #e5e7eb);\n  border-top-color: var(--pillar-primary, #2563eb);\n  border-radius: 50%;\n  animation: pillar-spin 0.8s linear infinite;\n}\n\n@keyframes pillar-spin {\n  to { transform: rotate(360deg); }\n}\n\n._pillar-thinking-label {\n  flex: 1;\n}\n\n._pillar-thinking-content {\n  padding: 6px 10px;\n  font-size: 13px;\n  line-height: 1.4;\n  color: var(--pillar-text-secondary, #6b7280);\n  background: var(--pillar-bg-tertiary, #f9fafb);\n  border-radius: 4px;\n  margin-top: 2px;\n  max-height: 150px;\n  overflow-y: auto;\n}\n";

package/dist/utils/preact-markdown.d.ts

@@ -14,4 +14,3 @@ export interface PreactMarkdownProps {
  * Supports custom component markers in code blocks and HTML-like syntax.
  */
 export declare function PreactMarkdown({ content, class: className }: PreactMarkdownProps): VNode;
-export declare const PREACT_MARKDOWN_STYLES = "\n/* Base markdown container */\n._pillar-markdown {\n  font-size: 14px;\n  line-height: 1.6;\n  color: var(--pillar-text, #1a1a1a);\n}\n\n/* Headings */\n._pillar-md-heading {\n  margin: 16px 0 8px 0;\n  font-weight: 600;\n  line-height: 1.3;\n}\n\n._pillar-md-h1 { font-size: 1.5em; }\n._pillar-md-h2 { font-size: 1.3em; }\n._pillar-md-h3 { font-size: 1.15em; }\n._pillar-md-h4 { font-size: 1em; }\n._pillar-md-h5 { font-size: 0.95em; }\n._pillar-md-h6 { font-size: 0.9em; }\n\n/* Paragraphs */\n._pillar-md-paragraph {\n  margin: 8px 0;\n}\n\n/* Links */\n._pillar-md-link {\n  color: var(--pillar-primary, #2563eb);\n  text-decoration: none;\n}\n\n._pillar-md-link:hover {\n  text-decoration: underline;\n}\n\n/* Inline code */\n._pillar-md-code-inline {\n  padding: 2px 6px;\n  font-family: 'SF Mono', Monaco, 'Cascadia Code', 'Roboto Mono', Consolas, monospace;\n  font-size: 0.9em;\n  background: var(--pillar-bg-code-inline, #f3f4f6);\n  border-radius: 4px;\n}\n\n/* Lists */\n._pillar-md-list {\n  margin: 8px 0;\n  padding-left: 24px;\n}\n\n._pillar-md-list-item {\n  margin: 4px 0;\n}\n\n/* Task list items */\n._pillar-md-task-item {\n  display: flex;\n  align-items: flex-start;\n  gap: 8px;\n  list-style: none;\n  margin-left: -24px;\n}\n\n._pillar-md-task-checkbox {\n  margin-top: 4px;\n}\n\n._pillar-md-task-text--checked {\n  text-decoration: line-through;\n  color: var(--pillar-text-placeholder, #9ca3af);\n}\n\n/* Blockquote */\n._pillar-md-blockquote {\n  margin: 8px 0;\n  padding: 8px 16px;\n  border-left: 3px solid var(--pillar-border, #e5e7eb);\n  color: var(--pillar-text-muted, #6b7280);\n  background: var(--pillar-bg-secondary, #f9fafb);\n}\n\n/* Horizontal rule */\n._pillar-md-hr {\n  margin: 16px 0;\n  border: none;\n  border-top: 1px solid var(--pillar-border, #e5e7eb);\n}\n\n/* Tables */\n._pillar-md-table-wrapper {\n  overflow-x: auto;\n  margin: 8px 0;\n}\n\n._pillar-md-table {\n  width: 100%;\n  border-collapse: collapse;\n  font-size: 13px;\n}\n\n._pillar-md-th,\n._pillar-md-td {\n  padding: 8px 12px;\n  border: 1px solid var(--pillar-border, #e5e7eb);\n  text-align: left;\n}\n\n._pillar-md-th {\n  background: var(--pillar-bg-secondary, #f9fafb);\n  font-weight: 600;\n}\n\n/* Images */\n._pillar-md-image {\n  max-width: 100%;\n  height: auto;\n  border-radius: 8px;\n  margin: 8px 0;\n}\n";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pillar-ai/sdk",
-  "version": "0.1.14",
-  "description": "Pillar Embedded Help SDK - Add contextual help and AI chat to your application",
+  "version": "0.1.16",
+  "description": "Product copilot SDK for SaaS and web apps — AI assistant that executes tasks, not just answers questions",
   "type": "module",
   "main": "./dist/pillar.esm.js",
   "module": "./dist/pillar.esm.js",
@@ -32,12 +32,15 @@
     "prepublishOnly": "npm run build"
   },
   "keywords": [
-    "help",
-    "documentation",
-    "support",
-    "chat",
+    "copilot",
+    "assistant",
     "ai",
-    "embedded"
+    "sdk",
+    "saas",
+    "embedded",
+    "agent",
+    "support",
+    "chat"
   ],
   "author": "Pillar Team",
   "license": "MIT",

package/src/actions/types.ts

@@ -182,6 +182,19 @@ export interface ActionDefinition<TData = Record<string, unknown>> {
    */
   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.
    *
@@ -216,6 +229,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>;
+  }>;
 }
 
 /**
@@ -248,6 +265,12 @@ 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;
 }
 
 /**
@@ -314,6 +337,16 @@ 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>;
+  }>;
 }
 
 /**