@pillar-ai/react 0.1.8 → 0.1.11

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,98 +1,181 @@
 # @pillar-ai/react
 
-React bindings for the Pillar Embedded Help SDK.
+React SDK for the [Pillar](https://trypillar.com) open-source AI copilot — embed a product assistant in your React or Next.js app 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/react)](https://www.npmjs.com/package/@pillar-ai/react)
+[![npm downloads](https://img.shields.io/npm/dm/@pillar-ai/react)](https://www.npmjs.com/package/@pillar-ai/react)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue)](https://www.typescriptlang.org/)
+
+## What is Pillar?
+
+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.
+
+For example, a user could ask:
+
+> "Close the Walmart deal as won in Salesforce and notify implementation"
+
+> "Add a weekly signups chart to my Amplitude dashboard"
+
+> "Create a P1 bug in Linear for the checkout crash and add it to this sprint"
+
+Pillar understands the intent, builds a multi-step plan, and executes it client-side with the user's session.
+
+## Features
+
+- **Task Execution** — Navigate pages, pre-fill forms, call APIs on behalf of users
+- **React Hooks** — `usePillar` and `useHelpPanel` for idiomatic React integration
+- **Next.js Support** — Works with App Router and Pages Router
+- **Multi-Step Plans** — Chain actions into workflows for complex tasks
+- **Type-Safe Actions** — Full TypeScript support for action definitions
+- **Custom Action Cards** — Render React components for confirmations and data input
+
+## Documentation
+
+**[View Full Documentation](https://trypillar.com/docs)** | [React Guide](https://trypillar.com/docs/react/installation) | [API Reference](https://trypillar.com/docs/reference/react)
 
 ## Installation
 
 ```bash
 npm install @pillar-ai/react
+# or
+pnpm add @pillar-ai/react
+# or
+yarn add @pillar-ai/react
 ```
 
 ## Quick Start
 
-Wrap your app with `PillarProvider`:
+### 1. Get Your Product Key
+
+> **⚠️ 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. Add the Provider
+
+Wrap your app with `PillarProvider` and define actions:
 
 ```tsx
 import { PillarProvider } from '@pillar-ai/react';
 
+const actions = {
+  export_to_csv: {
+    type: 'trigger' as const,
+    label: 'Export to CSV',
+    description: 'Export current data to CSV file',
+  },
+  go_to_settings: {
+    type: 'navigate' as const,
+    label: 'Open Settings',
+    description: 'Navigate to settings page',
+    path: '/settings',
+  },
+};
+
 function App() {
   return (
-    <PillarProvider helpCenter="your-help-center">
+    <PillarProvider
+      productKey="your-product-key"
+      actions={actions}
+      onTask={(actionName, data) => {
+        if (actionName === 'export_to_csv') {
+          downloadCSV();
+        }
+      }}
+    >
       <MyApp />
     </PillarProvider>
   );
 }
 ```
 
-## Components
-
-### PillarProvider
+### Next.js App Router
 
-The root provider that initializes the SDK and provides context to child components.
+For Next.js App Router, create a client wrapper component:
 
 ```tsx
-<PillarProvider
-  helpCenter="your-help-center"
-  config={{
-    panel: { position: 'right', mode: 'push' },
-    edgeTrigger: { enabled: true },
-    theme: { mode: 'auto' },
-  }}
->
-  {children}
-</PillarProvider>
-```
+// providers/PillarClientProvider.tsx
+'use client';
 
-### Custom Trigger Button
+import { PillarProvider } from '@pillar-ai/react';
+import { useRouter } from 'next/navigation';
 
-To use your own button instead of the built-in edge trigger:
+const actions = {
+  go_to_settings: {
+    type: 'navigate' as const,
+    label: 'Open Settings',
+    description: 'Navigate to settings page',
+  },
+};
 
-```tsx
-<PillarProvider
-  helpCenter="your-help-center"
-  config={{ edgeTrigger: { enabled: false } }}
->
-  <MyApp />
-</PillarProvider>
+export function PillarClientProvider({ children }: { children: React.ReactNode }) {
+  const router = useRouter();
 
-function HelpButton() {
-  const { toggle } = useHelpPanel();
-  return <button onClick={toggle}>Get Help</button>;
+  return (
+    <PillarProvider
+      productKey="your-product-key"
+      actions={actions}
+      onTask={(actionName, data) => {
+        if (actionName === 'go_to_settings') {
+          router.push('/settings');
+        }
+      }}
+    >
+      {children}
+    </PillarProvider>
+  );
 }
 ```
 
-### Tooltip
-
-Attach contextual tooltips to any element:
-
 ```tsx
-import { Tooltip } from '@pillar-ai/react';
+// app/layout.tsx
+import { PillarClientProvider } from '@/providers/PillarClientProvider';
 
-<Tooltip tooltipId="welcome-tooltip">
-  <button>Hover me for help</button>
-</Tooltip>;
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        <PillarClientProvider>{children}</PillarClientProvider>
+      </body>
+    </html>
+  );
+}
 ```
 
-### PillarPanel
+## Defining Actions
 
-For custom panel placement (when using `container: 'manual'`):
+Actions define what your co-pilot can do. When users make requests, Pillar matches intent to actions:
 
 ```tsx
-import { PillarProvider, PillarPanel } from '@pillar-ai/react';
+import type { ActionDefinitions } from '@pillar-ai/react';
 
-function App() {
-  return (
-    <PillarProvider
-      helpCenter="your-help-center"
-      config={{ panel: { container: 'manual' } }}
-    >
-      <div className="layout">
-        <main>Your content</main>
-        <PillarPanel className="sidebar-panel" />
-      </div>
-    </PillarProvider>
-  );
-}
+const actions = {
+  // Navigation actions
+  go_to_billing: {
+    type: 'navigate' as const,
+    label: 'Open Billing',
+    description: 'Navigate to billing and subscription settings',
+  },
+
+  // Trigger actions that execute code
+  export_report: {
+    type: 'trigger' as const,
+    label: 'Export Report',
+    description: 'Export the current report to PDF or CSV',
+  },
+
+  // Actions with data schemas (AI extracts parameters)
+  invite_team_member: {
+    type: 'trigger' as const,
+    label: 'Invite Team Member',
+    description: 'Send an invitation to join the team',
+    dataSchema: {
+      email: { type: 'string' as const, required: true },
+      role: { type: 'string' as const, enum: ['admin', 'member', 'viewer'] },
+    },
+  },
+} satisfies ActionDefinitions;
 ```
 
 ## Hooks
@@ -109,69 +192,124 @@ function MyComponent() {
 
   if (!isReady) return <div>Loading...</div>;
 
-  return <div>Panel is {isOpen ? 'open' : 'closed'}</div>;
+  return <div>Co-pilot is {isOpen ? 'open' : 'closed'}</div>;
 }
 ```
 
 ### useHelpPanel
 
-Control the help panel:
+Control the co-pilot panel:
 
 ```tsx
 import { useHelpPanel } from '@pillar-ai/react';
 
-function HelpButton() {
+function CopilotButton() {
   const { open, close, toggle, isOpen } = useHelpPanel();
 
   return (
-    <button onClick={toggle}>{isOpen ? 'Close Help' : 'Get Help'}</button>
+    <button onClick={toggle}>
+      {isOpen ? 'Close Co-pilot' : 'Open Co-pilot'}
+    </button>
   );
 }
 ```
 
-## Type-Safe Actions
+## Components
+
+### PillarProvider
 
-Define custom actions with full TypeScript support:
+The root provider that initializes the SDK:
 
 ```tsx
-import { PillarProvider, usePillar } from '@pillar-ai/react';
-import type { ActionDefinitions } from '@pillar-ai/react';
+<PillarProvider
+  productKey="your-product-key"
+  actions={actions}
+  onTask={(actionName, data) => { /* handle actions */ }}
+  config={{
+    panel: { position: 'right', mode: 'push' },
+    edgeTrigger: { enabled: true },
+    theme: { mode: 'auto' },
+  }}
+>
+  {children}
+</PillarProvider>
+```
 
-// Define your actions
-const actions = {
-  openSettings: {
-    type: 'navigate' as const,
-    label: 'Open Settings',
-    description: 'Navigate to settings page',
-  },
-  showNotification: {
-    type: 'trigger' as const,
-    label: 'Show Notification',
-    description: 'Display a notification',
-    dataSchema: {
-      message: { type: 'string' as const, required: true },
-    },
-  },
-} satisfies ActionDefinitions;
+### PillarPanel
+
+For custom panel placement:
+
+```tsx
+import { PillarProvider, PillarPanel } from '@pillar-ai/react';
 
 function App() {
   return (
     <PillarProvider
-      helpCenter="your-help-center"
-      actions={actions}
-      onTask={(type, data) => {
-        // TypeScript knows the exact shape of data based on type
-        if (type === 'showNotification') {
-          console.log(data.message); // Typed!
-        }
-      }}
+      productKey="your-product-key"
+      config={{ panel: { container: 'manual' } }}
     >
-      <MyApp />
+      <div className="layout">
+        <main>Your content</main>
+        <PillarPanel className="sidebar-panel" />
+      </div>
     </PillarProvider>
   );
 }
 ```
 
+### Tooltip
+
+Attach contextual tooltips to elements:
+
+```tsx
+import { Tooltip } from '@pillar-ai/react';
+
+<Tooltip tooltipId="export-help">
+  <button>Export Data</button>
+</Tooltip>
+```
+
+## Custom Action Cards
+
+Render custom UI for inline actions:
+
+```tsx
+import { PillarProvider } from '@pillar-ai/react';
+import type { CardComponentProps } from '@pillar-ai/react';
+
+function InviteCard({ data, onConfirm, onCancel }: CardComponentProps<{ email: string; role: string }>) {
+  return (
+    <div className="card">
+      <p>Invite {data.email} as {data.role}?</p>
+      <button onClick={() => onConfirm()}>Send Invite</button>
+      <button onClick={onCancel}>Cancel</button>
+    </div>
+  );
+}
+
+<PillarProvider
+  productKey="your-product-key"
+  cards={{
+    invite_team_member: InviteCard,
+  }}
+>
+  {children}
+</PillarProvider>
+```
+
+## Related Packages
+
+| Package | Description |
+|---------|-------------|
+| [@pillar-ai/sdk](https://github.com/pillarhq/sdk) | Core vanilla JavaScript SDK |
+| [@pillar-ai/vue](https://github.com/pillarhq/sdk-vue) | Vue 3 bindings |
+| [@pillar-ai/svelte](https://github.com/pillarhq/sdk-svelte) | Svelte bindings |
+
+## Requirements
+
+- React 17.0.0 or higher
+- React DOM 17.0.0 or higher
+
 ## License
 
 MIT

package/dist/PillarPanel.d.ts

@@ -20,8 +20,7 @@ export interface PillarPanelProps extends HTMLAttributes<HTMLDivElement> {
  * @example
  * ```tsx
  * <PillarProvider
- *   helpCenter="my-help"
- *   publicKey="pk_xxx"
+ *   productKey="my-product-key"
  *   config={{ panel: { container: 'manual' } }}
  * >
  *   <div className="my-layout">

package/dist/PillarProvider.d.ts

@@ -2,7 +2,7 @@
  * PillarProvider
  * Context provider that initializes and manages the Pillar SDK
  */
-import { Pillar, type PillarConfig, type PillarEvents, type PillarState, type TaskExecutePayload, type ThemeConfig } from "@pillar-ai/sdk";
+import { Pillar, type CompactScanResult, type PillarConfig, type PillarEvents, type PillarState, type ScanOptions, type TaskExecutePayload, type ThemeConfig } from "@pillar-ai/sdk";
 import React, { type ComponentType, type ReactNode } from "react";
 /**
  * Props passed to custom card components.
@@ -53,12 +53,25 @@ export interface PillarContextValue {
     setTheme: (theme: Partial<ThemeConfig>) => void;
     /** Enable or disable the text selection "Ask AI" popover */
     setTextSelectionEnabled: (enabled: boolean) => void;
+    /** Enable or disable DOM scanning */
+    setDOMScanningEnabled: (enabled: boolean) => void;
+    /** Whether DOM scanning is enabled */
+    isDOMScanningEnabled: boolean;
+    /** Manually scan the page and get the compact result */
+    scanPage: (options?: ScanOptions) => CompactScanResult | null;
     /** Subscribe to SDK events */
     on: <K extends keyof PillarEvents>(event: K, callback: (data: PillarEvents[K]) => void) => () => void;
 }
 export interface PillarProviderProps {
-    /** Help center subdomain or identifier */
-    helpCenter: string;
+    /**
+     * Your product key from the Pillar app.
+     * Get it at app.trypillar.com
+     */
+    productKey?: string;
+    /**
+     * @deprecated Use `productKey` instead. Will be removed in v1.0.
+     */
+    helpCenter?: string;
     /**
      * Additional SDK configuration
      *
@@ -66,7 +79,7 @@ export interface PillarProviderProps {
      * - `panel.useShadowDOM`: Whether to isolate styles in Shadow DOM (default: false).
      *   Set to false to let custom cards inherit your app's CSS (Tailwind, etc.)
      */
-    config?: Omit<PillarConfig, "helpCenter">;
+    config?: Omit<PillarConfig, "productKey" | "helpCenter">;
     /**
      * Handler called when a task action is triggered from the chat.
      * Use this to handle AI-suggested actions like opening modals, navigating, etc.
@@ -74,7 +87,7 @@ export interface PillarProviderProps {
      * @example
      * ```tsx
      * <PillarProvider
-     *   helpCenter="my-app"
+     *   productKey="my-product-key"
      *   onTask={(task) => {
      *     switch (task.name) {
      *       case 'invite_team_member':
@@ -98,7 +111,7 @@ export interface PillarProviderProps {
      * import { InviteMembersCard } from './cards/InviteMembersCard';
      *
      * <PillarProvider
-     *   helpCenter="my-app"
+     *   productKey="my-product-key"
      *   cards={{
      *     invite_members: InviteMembersCard,
      *     confirm_delete: ConfirmDeleteCard,
@@ -107,8 +120,18 @@ export interface PillarProviderProps {
      * ```
      */
     cards?: Record<string, CardComponent>;
+    /**
+     * Enable DOM scanning to send page context with messages.
+     * When enabled, interactable elements and text content are captured and sent to the LLM.
+     * @default false
+     */
+    domScanning?: boolean;
+    /**
+     * Enable DOM scanning dev mode to preview the scanned page before sending.
+     * Shows a modal with the AST tree visualization before each message is sent.
+     * Useful for debugging what context will be sent to the LLM.
     /** Children components */
     children: ReactNode;
 }
-export declare function PillarProvider({ helpCenter, config, onTask, cards, children, }: PillarProviderProps): React.ReactElement;
+export declare function PillarProvider({ productKey, helpCenter, config, onTask, cards, domScanning, children, }: PillarProviderProps): React.ReactElement;
 export declare function usePillarContext(): PillarContextValue;

package/dist/Tooltip.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Tooltip Component
+ * Wrapper component that adds tooltip functionality to children
+ */
+import React, { type ReactNode, type CSSProperties } from 'react';
+export interface TooltipProps {
+    /** Unique tooltip ID that matches a tooltip in your Pillar dashboard */
+    tooltipId: string;
+    /** Trigger behavior: hover, click, focus, or icon (shows info icon) */
+    trigger?: 'hover' | 'click' | 'focus' | 'icon';
+    /** Tooltip position relative to the target */
+    position?: 'top' | 'bottom' | 'left' | 'right' | 'auto';
+    /** Children elements to attach the tooltip to */
+    children: ReactNode;
+    /** Additional class name for the wrapper */
+    className?: string;
+    /** Additional inline styles for the wrapper */
+    style?: CSSProperties;
+    /** Whether the wrapper should be a span (inline) or div (block) */
+    inline?: boolean;
+}
+/**
+ * Tooltip wrapper component that adds Pillar tooltip functionality to children
+ *
+ * @example
+ * ```tsx
+ * <Tooltip tooltipId="feature-explanation" trigger="hover">
+ *   <button>Learn More</button>
+ * </Tooltip>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <Tooltip tooltipId="input-help" trigger="icon">
+ *   <label>Email Address</label>
+ * </Tooltip>
+ * ```
+ */
+export declare function Tooltip({ tooltipId, trigger, position, children, className, style, inline, }: TooltipProps): React.ReactElement;

package/dist/hooks/usePillarTool.d.ts

@@ -0,0 +1,73 @@
+/**
+ * usePillarTool Hook
+ *
+ * Register one or more tools with co-located metadata and handlers.
+ * Tools are registered on mount and unregistered on unmount.
+ *
+ * @example Single tool
+ * ```tsx
+ * import { usePillarTool } from '@pillar-ai/react';
+ *
+ * function CartButton() {
+ *   usePillarTool({
+ *     name: 'add_to_cart',
+ *     description: 'Add a product to the shopping cart',
+ *     inputSchema: {
+ *       type: 'object',
+ *       properties: {
+ *         productId: { type: 'string', description: 'Product ID' },
+ *         quantity: { type: 'number', description: 'Quantity to add' },
+ *       },
+ *       required: ['productId', 'quantity'],
+ *     },
+ *     execute: async ({ productId, quantity }) => {
+ *       await cartApi.add(productId, quantity);
+ *       return { content: [{ type: 'text', text: 'Added to cart' }] };
+ *     },
+ *   });
+ *
+ *   return <button>Cart</button>;
+ * }
+ * ```
+ *
+ * @example Multiple tools
+ * ```tsx
+ * import { usePillarTool } from '@pillar-ai/react';
+ *
+ * function BillingPage() {
+ *   usePillarTool([
+ *     {
+ *       name: 'get_current_plan',
+ *       description: 'Get the current billing plan',
+ *       execute: async () => ({ plan: 'pro', price: 29 }),
+ *     },
+ *     {
+ *       name: 'upgrade_plan',
+ *       description: 'Upgrade to a higher plan',
+ *       inputSchema: {
+ *         type: 'object',
+ *         properties: { planId: { type: 'string' } },
+ *         required: ['planId'],
+ *       },
+ *       execute: async ({ planId }) => {
+ *         await billingApi.upgrade(planId);
+ *         return { content: [{ type: 'text', text: 'Upgraded!' }] };
+ *       },
+ *     },
+ *   ]);
+ *
+ *   return <div>Billing Content</div>;
+ * }
+ * ```
+ */
+import type { ToolSchema } from '@pillar-ai/sdk';
+/**
+ * Register a single Pillar tool with co-located metadata and handler.
+ */
+export declare function usePillarTool<TInput = Record<string, unknown>>(schema: ToolSchema<TInput>): void;
+/**
+ * Register multiple Pillar tools with co-located metadata and handlers.
+ */
+export declare function usePillarTool(schemas: ToolSchema[]): void;
+/** @deprecated Use usePillarTool instead */
+export declare const usePillarAction: typeof usePillarTool;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * @pillar-ai/react - React bindings for Pillar Embedded Help SDK
+ * @pillar-ai/react - React bindings for Pillar SDK
  *
  * @example
  * ```tsx
@@ -7,7 +7,7 @@
  *
  * function App() {
  *   return (
- *     <PillarProvider helpCenter="your-help-center" publicKey="pk_live_xxx">
+ *     <PillarProvider productKey="your-product-key">
  *       <MyApp />
  *     </PillarProvider>
  *   );
@@ -20,7 +20,7 @@
  *   return (
  *     <div>
  *       <h1>Welcome!</h1>
- *       <button onClick={toggle}>Get Help</button>
+ *       <button onClick={toggle}>Open Co-pilot</button>
  *     </div>
  *   );
  * }
@@ -29,8 +29,7 @@
  * function AppWithCustomPanel() {
  *   return (
  *     <PillarProvider
- *       helpCenter="your-help-center"
- *       publicKey="pk_live_xxx"
+ *       productKey="your-product-key"
  *       config={{ panel: { container: 'manual' } }}
  *     >
  *       <div className="layout">
@@ -46,4 +45,5 @@ export { PillarProvider, usePillarContext, type PillarContextValue, type PillarP
 export { PillarPanel, type PillarPanelProps } from './PillarPanel';
 export { useHelpPanel, type UseHelpPanelResult } from './hooks/useHelpPanel';
 export { usePillar, type UsePillarResult, type TypedUsePillarResult } from './hooks/usePillar';
-export type { EdgeTriggerConfig, MobileTriggerConfig, MobileTriggerPosition, MobileTriggerIcon, MobileTriggerSize, PanelConfig, PillarConfig, PillarEvents, PillarState, ResolvedConfig, ResolvedMobileTriggerConfig, ResolvedThemeConfig, TaskExecutePayload, TextSelectionConfig, ThemeColors, ThemeConfig, ThemeMode, CardCallbacks, CardRenderer, SidebarTabConfig, ActionDefinitions, SyncActionDefinitions, ActionDataType, ActionNames, ChatContext, } from '@pillar-ai/sdk';
+export { usePillarTool, usePillarAction } from './hooks/usePillarTool';
+export type { EdgeTriggerConfig, MobileTriggerConfig, MobileTriggerPosition, MobileTriggerIcon, MobileTriggerSize, PanelConfig, PillarConfig, PillarEvents, PillarState, ResolvedConfig, ResolvedMobileTriggerConfig, ResolvedThemeConfig, TaskExecutePayload, TextSelectionConfig, ThemeColors, ThemeConfig, ThemeMode, CardCallbacks, CardRenderer, SidebarTabConfig, ToolDefinitions, SyncToolDefinitions, ToolDataType, ToolNames, ToolExecuteResult, ToolSchema, ToolType, ActionDefinitions, SyncActionDefinitions, ActionDataType, ActionNames, ActionResult, ActionSchema, ActionType, ChatContext, DOMScanningConfig, ResolvedDOMScanningConfig, ScanOptions, CompactScanResult, InteractionType, scanPageDirect, } from '@pillar-ai/sdk';