@mydatavalue/polter 0.1.0 → 0.1.2

package/README.md

@@ -6,15 +6,17 @@
 
 <p align="center">Declarative React library for agent-driven UI control with visual guided execution.</p>
 
-The agent drives the **real UI** — it opens the actual dropdown, clicks the actual button, with the user watching. "Let me show you how" instead of "I did it for you." After seeing it twice, users do it themselves.
+Your UI *is* the agent's interface. It opens the actual dropdown, clicks the actual button, with the user watching. No separate tools to build — single source of truth. After seeing it twice, users do it themselves.
 
 ## Why
 
-Every SaaS adding an AI agent faces the same problem: the agent does things programmatically but the user never learns where buttons are or how the UI works. They become dependent on the agent.
+Every SaaS adding an AI agent faces two problems:
 
-The alternative — agents generating UI at runtime — is worse. Generated UI is unpredictable and breaks muscle memory.
+1. **Double the work.** You build your UI, then build a whole separate set of agent tools — API endpoints, handlers, schemas — all duplicating what the UI already does.
 
-**The right pattern**: the agent drives the real UI. It scrolls to the button, spotlights it, pauses so the user sees it, then clicks it. The user watches and learns. Nothing else does this.
+2. **Users never learn.** The agent does things behind the scenes or generates throwaway UI. Either way, users never see where buttons are or how the interface works. Permanent dependency.
+
+**Polter solves both.** Your UI *is* the agent's interface — single source of truth. The agent scrolls to the real button, spotlights it, clicks it. Users watch and learn. After twice, they do it themselves. And you wrote zero agent-specific tools.
 
 ## Install
 
@@ -104,6 +106,76 @@ const handleCommand = useAgentCommandRouter(existingHandler, (cmd) => cmd.action
 4. `<div style="display: contents">` wrapper provides DOM refs without affecting layout
 5. Components that mount = actions that exist. Navigate away = actions disappear. No manual sync.
 
+## Advanced: `defineAction()` + Registry
+
+For multi-page apps, `<AgentAction>` schemas are only available when the component is mounted. If the user says "update the price on property 123" but that page isn't open, the agent can't see the action.
+
+`defineAction()` solves this — schemas are available at import time, before any component mounts. Combined with the `registry` prop, the agent gets full knowledge of every action upfront (single LLM roundtrip).
+
+### 1. Define actions (co-located with your feature)
+
+```tsx
+// features/pricing/actions.ts
+import { defineAction } from 'polter';
+import { z } from 'zod';
+
+export const updatePrice = defineAction({
+  name: 'update_price',
+  description: 'Update price markup on a property',
+  parameters: z.object({
+    property_id: z.string(),
+    markup: z.number(),
+  }),
+  route: (p) => `/properties/${p.property_id}/pricing`,
+});
+```
+
+### 2. Create a registry (barrel file)
+
+```tsx
+// registry.ts
+import { updatePrice } from './features/pricing/actions';
+import { exportCsv } from './features/reports/actions';
+
+export const agentRegistry = [updatePrice, exportCsv];
+```
+
+### 3. Pass to provider with your router
+
+```tsx
+import { agentRegistry } from './registry';
+
+<AgentActionProvider
+  registry={agentRegistry}
+  navigate={(path) => router.push(path)}
+>
+  <App />
+</AgentActionProvider>
+```
+
+### 4. Components reference the definition
+
+```tsx
+// features/pricing/PricingPage.tsx
+import { updatePrice } from './actions';
+
+<AgentAction action={updatePrice} onExecute={(p) => setMarkup(p.markup)}>
+  <SaveButton />
+</AgentAction>
+```
+
+### How it works
+
+1. On mount, the provider registers all registry actions as schema-only entries — the agent sees them immediately
+2. When the agent calls `execute('update_price', { property_id: '123', markup: 15 })`:
+   - Provider calculates the route: `/properties/123/pricing`
+   - Calls your `navigate()` function
+   - Waits for the `<AgentAction>` component to mount on the new page
+   - Runs the visual execution (spotlight, click, etc.)
+3. When the component unmounts (user navigates away), the action reverts to schema-only — never disappears from the agent's view
+
+If an action has no corresponding UI element anywhere in the app, you can provide `onExecute` directly on the definition as an escape hatch — it will execute without navigation or spotlight.
+
 ## API
 
 ### Execution modes
@@ -124,6 +196,8 @@ const handleCommand = useAgentCommandRouter(existingHandler, (cmd) => cmd.action
 | `tooltipEnabled` | `boolean` | `true` |
 | `onExecutionStart` | `(name: string) => void` | — |
 | `onExecutionComplete` | `(result: ExecutionResult) => void` | — |
+| `registry` | `ActionDefinition[]` | — |
+| `navigate` | `(path: string) => void \| Promise<void>` | — |
 
 ### Disabled actions
 
@@ -152,174 +226,7 @@ All overlay elements have class names:
 
 ## Best practices
 
-### Use `<AgentAction>` when wrapping a visible element
-
-The component pattern is for actions that have a single, visible UI element to spotlight:
-
-```tsx
-// Good — wraps the actual button
-<AgentAction name="push_changes" description="Push pending changes">
-  <PushButton />
-</AgentAction>
-
-// Bad — wraps nothing visible, renders a pointless display:contents div
-<AgentAction name="sync_data" description="Sync data"
-  onExecute={handleSync} />
-```
-
-### Wrap conditionally rendered elements with `<AgentAction>` on the outside
-
-`<AgentAction>` always registers the action regardless of whether its children are rendered. Keep the wrapper always-rendered and put the condition inside — `onExecute` works even when there's nothing visible to spotlight:
-
-```tsx
-// Bad — conditionally rendering the AgentAction itself, action disappears when button is hidden
-{selectedIds.size > 0 && (
-  <AgentAction name="grant_access" description="Grant access" onExecute={() => handleGrant()}>
-    <Button onClick={handleGrant}>Grant Access ({selectedIds.size})</Button>
-  </AgentAction>
-)}
-
-// Good — AgentAction always registered, button conditionally rendered inside
-<AgentAction name="grant_access" description="Grant access" onExecute={() => handleGrant()}>
-  {selectedIds.size > 0 && (
-    <Button onClick={handleGrant}>Grant Access ({selectedIds.size})</Button>
-  )}
-</AgentAction>
-```
-
-### Use `useAgentAction` hook for per-row and programmatic actions
-
-When N rows each have their own button (sync, edit, navigate), you can't wrap each with `<AgentAction>` — same name would register N times, each overwriting the last. Use the hook + `<AgentTarget>` on each row's element:
-
-```tsx
-// Hook registers the action once
-useAgentAction({
-  name: 'sync_property',
-  description: 'Sync a property',
-  parameters: z.object({ property_id: z.number() }),
-  onExecute: (p) => handleSync(p.property_id),
-  steps: [{ label: 'Click Sync', fromParam: 'property_id' }],
-});
-
-// AgentTarget on each row's button (in a column renderer)
-<AgentTarget action="sync_property" param="property_id" value={String(propertyId)}>
-  <SyncButton />
-</AgentTarget>
-```
-
-The hook also accepts an array to batch-register multiple actions in one call:
-
-```tsx
-useAgentAction([
-  { name: 'navigate_to_property', ... },
-  { name: 'sync_property', ... },
-  { name: 'edit_markup', ... },
-]);
-```
-
-### Never nest `AgentTarget` inside Radix `asChild` components
-
-Radix primitives (`PopoverTrigger`, `DialogTrigger`, `TooltipTrigger`) with `asChild` need their direct child to forward refs. `AgentTarget` inserts a `<div style="display:contents">` wrapper that breaks this:
-
-```tsx
-// Bad — breaks ref forwarding, trigger won't work
-<PopoverTrigger asChild>
-  <AgentTarget name="my-btn">
-    <Button>Open</Button>
-  </AgentTarget>
-</PopoverTrigger>
-
-// Good — wrap outside the Popover entirely
-<AgentTarget name="my-btn">
-  <Popover>
-    <PopoverTrigger asChild>
-      <Button>Open</Button>
-    </PopoverTrigger>
-    <PopoverContent>...</PopoverContent>
-  </Popover>
-</AgentTarget>
-```
-
-Since `Popover.Root` renders no DOM element, `AgentTarget`'s `firstElementChild` resolves to the Button directly.
-
-### Use shared targets for elements used by multiple actions
-
-When two actions need the same trigger (e.g. both open the same overflow menu), omit the `action` prop to make a shared target:
-
-```tsx
-// Shared target — any action can resolve it by name
-<AgentTarget name="overflow-menu-btn">
-  <OverflowMenuPopover>
-    <AgentTarget name="export-btn">
-      <ExportButton />
-    </AgentTarget>
-    <AgentTarget name="freeze-btn">
-      <FreezeButton />
-    </AgentTarget>
-  </OverflowMenuPopover>
-</AgentTarget>
-
-// Both actions find the same trigger
-useAgentAction([
-  { name: 'export_csv', steps: [
-    { label: 'Open menu', fromTarget: 'overflow-menu-btn' },
-    { label: 'Click Export', fromTarget: 'export-btn' },
-  ]},
-  { name: 'toggle_freeze', steps: [
-    { label: 'Open menu', fromTarget: 'overflow-menu-btn' },
-    { label: 'Click Freeze', fromTarget: 'freeze-btn' },
-  ]},
-]);
-```
-
-### Multi-step is required for dropdowns
-
-With `onExecute`, the executor skips clicking the last step (to avoid double-firing). If your action has only one step, the click never happens — the dropdown won't open:
-
-```tsx
-// Bad — single step with onExecute, dropdown never opens
-<AgentAction name="filter" onExecute={handleFilter}>
-  <Select>...</Select>
-</AgentAction>
-
-// Good — two steps: click to open, then select option
-<AgentAction name="filter" onExecute={handleFilter}>
-  <AgentStep label="Open filter">
-    <Select>
-      <SelectTrigger>...</SelectTrigger>
-      <SelectContent>
-        <AgentTarget action="filter" param="status" value="active">
-          <SelectItem value="active">Active</SelectItem>
-        </AgentTarget>
-      </SelectContent>
-    </Select>
-  </AgentStep>
-  <AgentStep label="Select option" fromParam="status" />
-</AgentAction>
-```
-
-### Don't deeply nest `<AgentAction>` wrappers
-
-Each `<AgentAction>` renders a `<div style="display:contents">`. Nesting them creates a chain of `display:contents` divs. `getBoundingClientRect()` on these returns all zeros, causing spotlights to appear at (0,0):
-
-```tsx
-// Bad — nested wrappers, inner actions resolve to display:contents divs
-<AgentAction name="action_a">
-  <AgentAction name="action_b">
-    <AgentAction name="action_c">
-      <ActualContent />
-    </AgentAction>
-  </AgentAction>
-</AgentAction>
-
-// Good — flat siblings, each wrapping its own element (or use the hook)
-<AgentAction name="action_a">
-  <ButtonA />
-</AgentAction>
-<AgentAction name="action_b">
-  <ButtonB />
-</AgentAction>
-```
+See [docs/best-practices.md](docs/best-practices.md) for patterns around conditional rendering, per-row actions, Radix integration, dropdowns, and common pitfalls.
 
 ## Zero dependencies
 

package/dist/index.d.mts

@@ -1,6 +1,52 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import React$1 from 'react';
 
+/**
+ * Define an action at import time so its schema is available before the component mounts.
+ * Pass defined actions to `<AgentActionProvider registry={[...]}>` for single-roundtrip execution.
+ *
+ * @example
+ * ```ts
+ * export const updatePrice = defineAction({
+ *   name: 'update_price',
+ *   description: 'Update price markup on a property',
+ *   parameters: z.object({ property_id: z.string(), markup: z.number() }),
+ *   route: (p) => `/properties/${p.property_id}/pricing`,
+ * });
+ * ```
+ */
+interface ActionDefinition<TParams = Record<string, unknown>> {
+    readonly name: string;
+    readonly description: string;
+    /** Zod schema for action parameters. */
+    readonly parameters?: unknown;
+    /** Client-side route to navigate to before executing. */
+    readonly route?: (params: TParams) => string;
+    /** Handler for background execution (no UI component needed). */
+    readonly onExecute?: (params: TParams) => void | Promise<void>;
+    /**
+     * Chain of action names to execute sequentially before this action.
+     * Each action in the chain is visually executed (spotlight → click), and the next
+     * action is waited on to mount before proceeding. This lets the user see the full
+     * navigation path instead of being teleported directly to a route.
+     */
+    readonly navigateVia?: string[];
+    /**
+     * How long (ms) to wait for this action's component to mount after navigation.
+     * Defaults to 5000ms. Set higher for pages that load slowly
+     */
+    readonly mountTimeout?: number;
+}
+declare function defineAction<TParams = Record<string, unknown>>(config: {
+    name: string;
+    description: string;
+    parameters?: unknown;
+    route?: (params: TParams) => string;
+    onExecute?: (params: TParams) => void | Promise<void>;
+    navigateVia?: string[];
+    mountTimeout?: number;
+}): ActionDefinition<TParams>;
+
 type ExecutionMode = 'guided' | 'instant';
 interface ExecutionTarget {
     label: string;
@@ -36,6 +82,14 @@ interface RegisteredAction {
     disabled: boolean;
     disabledReason?: string;
     getExecutionTargets: () => ExecutionTarget[];
+    /** Client-side route for navigation before execution (from defineAction). */
+    route?: (params: Record<string, unknown>) => string;
+    /** Chain of action names to execute sequentially before this action (from defineAction). */
+    navigateVia?: string[];
+    /** How long (ms) to wait for this action's component to mount after navigation. */
+    mountTimeout?: number;
+    /** True when registered by an `<AgentAction>` component (vs schema-only from registry). */
+    componentBacked?: boolean;
 }
 interface ToolSchema {
     name: string;
@@ -77,6 +131,10 @@ interface AgentActionProviderProps {
     children: React.ReactNode;
     onExecutionStart?: (actionName: string) => void;
     onExecutionComplete?: (result: ExecutionResult) => void;
+    /** Pre-defined actions whose schemas are available before their components mount. */
+    registry?: ActionDefinition<any>[];
+    /** Router integration — called when executing a registry action that needs navigation. */
+    navigate?: (path: string) => void | Promise<void>;
 }
 interface AgentActionContextValue {
     registerAction: (action: RegisteredAction) => void;
@@ -90,18 +148,25 @@ interface AgentActionContextValue {
     mode: ExecutionMode;
 }
 
-declare function AgentActionProvider({ mode, stepDelay, overlayOpacity, spotlightPadding, tooltipEnabled, cursorEnabled, children, onExecutionStart, onExecutionComplete, }: AgentActionProviderProps): react_jsx_runtime.JSX.Element;
+declare function AgentActionProvider({ mode, stepDelay, overlayOpacity, spotlightPadding, tooltipEnabled, cursorEnabled, children, onExecutionStart, onExecutionComplete, registry, navigate, }: AgentActionProviderProps): react_jsx_runtime.JSX.Element;
 
-interface AgentActionProps {
-    name: string;
-    description: string;
-    parameters?: unknown;
+type AgentActionProps = {
     onExecute?: (params: Record<string, unknown>) => void | Promise<void>;
     disabled?: boolean;
     disabledReason?: string;
     children?: React$1.ReactNode;
-}
-declare function AgentAction({ name, description, parameters, onExecute, disabled, disabledReason, children, }: AgentActionProps): react_jsx_runtime.JSX.Element | null;
+} & ({
+    action: ActionDefinition<any>;
+    name?: string;
+    description?: string;
+    parameters?: unknown;
+} | {
+    action?: never;
+    name: string;
+    description: string;
+    parameters?: unknown;
+});
+declare function AgentAction(props: AgentActionProps): react_jsx_runtime.JSX.Element | null;
 
 interface AgentStepProps {
     label: string;
@@ -200,6 +265,9 @@ declare function useAgentActions(): AgentActionContextValue;
  * it routes through `execute()` for visual guided execution. Otherwise it falls
  * through to the original handler.
  *
+ * Returns the `ExecutionResult` for registered actions, or `undefined` for
+ * fallback commands.
+ *
  * Works with any command shape — you provide `getActionName` to extract the
  * action name from your command object.
  *
@@ -211,10 +279,10 @@ declare function useAgentActions(): AgentActionContextValue;
  * );
  * ```
  */
-declare function useAgentCommandRouter<T>(fallback: ((command: T) => void | Promise<void>) | null, getActionName: (command: T) => string): (command: T) => Promise<void>;
+declare function useAgentCommandRouter<T>(fallback: ((command: T) => void | Promise<void>) | null, getActionName: (command: T) => string): (command: T) => Promise<ExecutionResult | undefined>;
 
 type JsonSchema = Record<string, unknown>;
 declare function zodToJsonSchema(schema: unknown): JsonSchema;
 declare function generateToolSchemas(actions: RegisteredAction[]): ToolSchema[];
 
-export { AgentAction, type AgentActionContextValue, AgentActionProvider, type AgentActionProviderProps, AgentDevTools, AgentStep, AgentTarget, type AgentTargetEntry, type AvailableAction, type ExecutionMode, type ExecutionResult, type ExecutionTarget, type ExecutorConfig, type RegisteredAction, type ToolSchema, generateToolSchemas, useAgentAction, useAgentActions, useAgentCommandRouter, zodToJsonSchema };
+export { type ActionDefinition, AgentAction, type AgentActionContextValue, AgentActionProvider, type AgentActionProviderProps, AgentDevTools, AgentStep, AgentTarget, type AgentTargetEntry, type AvailableAction, type ExecutionMode, type ExecutionResult, type ExecutionTarget, type ExecutorConfig, type RegisteredAction, type ToolSchema, defineAction, generateToolSchemas, useAgentAction, useAgentActions, useAgentCommandRouter, zodToJsonSchema };

package/dist/index.d.ts

@@ -1,6 +1,52 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import React$1 from 'react';
 
+/**
+ * Define an action at import time so its schema is available before the component mounts.
+ * Pass defined actions to `<AgentActionProvider registry={[...]}>` for single-roundtrip execution.
+ *
+ * @example
+ * ```ts
+ * export const updatePrice = defineAction({
+ *   name: 'update_price',
+ *   description: 'Update price markup on a property',
+ *   parameters: z.object({ property_id: z.string(), markup: z.number() }),
+ *   route: (p) => `/properties/${p.property_id}/pricing`,
+ * });
+ * ```
+ */
+interface ActionDefinition<TParams = Record<string, unknown>> {
+    readonly name: string;
+    readonly description: string;
+    /** Zod schema for action parameters. */
+    readonly parameters?: unknown;
+    /** Client-side route to navigate to before executing. */
+    readonly route?: (params: TParams) => string;
+    /** Handler for background execution (no UI component needed). */
+    readonly onExecute?: (params: TParams) => void | Promise<void>;
+    /**
+     * Chain of action names to execute sequentially before this action.
+     * Each action in the chain is visually executed (spotlight → click), and the next
+     * action is waited on to mount before proceeding. This lets the user see the full
+     * navigation path instead of being teleported directly to a route.
+     */
+    readonly navigateVia?: string[];
+    /**
+     * How long (ms) to wait for this action's component to mount after navigation.
+     * Defaults to 5000ms. Set higher for pages that load slowly
+     */
+    readonly mountTimeout?: number;
+}
+declare function defineAction<TParams = Record<string, unknown>>(config: {
+    name: string;
+    description: string;
+    parameters?: unknown;
+    route?: (params: TParams) => string;
+    onExecute?: (params: TParams) => void | Promise<void>;
+    navigateVia?: string[];
+    mountTimeout?: number;
+}): ActionDefinition<TParams>;
+
 type ExecutionMode = 'guided' | 'instant';
 interface ExecutionTarget {
     label: string;
@@ -36,6 +82,14 @@ interface RegisteredAction {
     disabled: boolean;
     disabledReason?: string;
     getExecutionTargets: () => ExecutionTarget[];
+    /** Client-side route for navigation before execution (from defineAction). */
+    route?: (params: Record<string, unknown>) => string;
+    /** Chain of action names to execute sequentially before this action (from defineAction). */
+    navigateVia?: string[];
+    /** How long (ms) to wait for this action's component to mount after navigation. */
+    mountTimeout?: number;
+    /** True when registered by an `<AgentAction>` component (vs schema-only from registry). */
+    componentBacked?: boolean;
 }
 interface ToolSchema {
     name: string;
@@ -77,6 +131,10 @@ interface AgentActionProviderProps {
     children: React.ReactNode;
     onExecutionStart?: (actionName: string) => void;
     onExecutionComplete?: (result: ExecutionResult) => void;
+    /** Pre-defined actions whose schemas are available before their components mount. */
+    registry?: ActionDefinition<any>[];
+    /** Router integration — called when executing a registry action that needs navigation. */
+    navigate?: (path: string) => void | Promise<void>;
 }
 interface AgentActionContextValue {
     registerAction: (action: RegisteredAction) => void;
@@ -90,18 +148,25 @@ interface AgentActionContextValue {
     mode: ExecutionMode;
 }
 
-declare function AgentActionProvider({ mode, stepDelay, overlayOpacity, spotlightPadding, tooltipEnabled, cursorEnabled, children, onExecutionStart, onExecutionComplete, }: AgentActionProviderProps): react_jsx_runtime.JSX.Element;
+declare function AgentActionProvider({ mode, stepDelay, overlayOpacity, spotlightPadding, tooltipEnabled, cursorEnabled, children, onExecutionStart, onExecutionComplete, registry, navigate, }: AgentActionProviderProps): react_jsx_runtime.JSX.Element;
 
-interface AgentActionProps {
-    name: string;
-    description: string;
-    parameters?: unknown;
+type AgentActionProps = {
     onExecute?: (params: Record<string, unknown>) => void | Promise<void>;
     disabled?: boolean;
     disabledReason?: string;
     children?: React$1.ReactNode;
-}
-declare function AgentAction({ name, description, parameters, onExecute, disabled, disabledReason, children, }: AgentActionProps): react_jsx_runtime.JSX.Element | null;
+} & ({
+    action: ActionDefinition<any>;
+    name?: string;
+    description?: string;
+    parameters?: unknown;
+} | {
+    action?: never;
+    name: string;
+    description: string;
+    parameters?: unknown;
+});
+declare function AgentAction(props: AgentActionProps): react_jsx_runtime.JSX.Element | null;
 
 interface AgentStepProps {
     label: string;
@@ -200,6 +265,9 @@ declare function useAgentActions(): AgentActionContextValue;
  * it routes through `execute()` for visual guided execution. Otherwise it falls
  * through to the original handler.
  *
+ * Returns the `ExecutionResult` for registered actions, or `undefined` for
+ * fallback commands.
+ *
  * Works with any command shape — you provide `getActionName` to extract the
  * action name from your command object.
  *
@@ -211,10 +279,10 @@ declare function useAgentActions(): AgentActionContextValue;
  * );
  * ```
  */
-declare function useAgentCommandRouter<T>(fallback: ((command: T) => void | Promise<void>) | null, getActionName: (command: T) => string): (command: T) => Promise<void>;
+declare function useAgentCommandRouter<T>(fallback: ((command: T) => void | Promise<void>) | null, getActionName: (command: T) => string): (command: T) => Promise<ExecutionResult | undefined>;
 
 type JsonSchema = Record<string, unknown>;
 declare function zodToJsonSchema(schema: unknown): JsonSchema;
 declare function generateToolSchemas(actions: RegisteredAction[]): ToolSchema[];
 
-export { AgentAction, type AgentActionContextValue, AgentActionProvider, type AgentActionProviderProps, AgentDevTools, AgentStep, AgentTarget, type AgentTargetEntry, type AvailableAction, type ExecutionMode, type ExecutionResult, type ExecutionTarget, type ExecutorConfig, type RegisteredAction, type ToolSchema, generateToolSchemas, useAgentAction, useAgentActions, useAgentCommandRouter, zodToJsonSchema };
+export { type ActionDefinition, AgentAction, type AgentActionContextValue, AgentActionProvider, type AgentActionProviderProps, AgentDevTools, AgentStep, AgentTarget, type AgentTargetEntry, type AvailableAction, type ExecutionMode, type ExecutionResult, type ExecutionTarget, type ExecutorConfig, type RegisteredAction, type ToolSchema, defineAction, generateToolSchemas, useAgentAction, useAgentActions, useAgentCommandRouter, zodToJsonSchema };