@mydatavalue/polter 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 myDataValue
+
+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

@@ -0,0 +1,330 @@
+<p align="center">
+  <img src="logo.svg?raw=true" alt="Polter" width="200" />
+</p>
+
+<h1 align="center">polter</h1>
+
+<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.
+
+## 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.
+
+The alternative — agents generating UI at runtime — is worse. Generated UI is unpredictable and breaks muscle memory.
+
+**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.
+
+## Install
+
+```bash
+npm install polter
+# peer deps
+npm install react react-dom zod
+```
+
+## Quick Start
+
+```tsx
+import { AgentActionProvider, AgentAction, useAgentActions } from 'polter';
+import { z } from 'zod';
+```
+
+### 1. Wrap your app
+
+```tsx
+<AgentActionProvider mode="guided" stepDelay={600}>
+  <App />
+</AgentActionProvider>
+```
+
+### 2. Register actions
+
+**Visual actions** — wrap an element, the agent spotlights and clicks it:
+
+```tsx
+<AgentAction name="export_csv" description="Export properties to CSV">
+  <ExportButton />
+</AgentAction>
+```
+
+**Parameterized actions** — spotlight the element, call your function:
+
+```tsx
+<AgentAction
+  name="sync_properties"
+  description="Sync specific properties"
+  parameters={z.object({
+    property_ids: z.array(z.number()).optional().describe("IDs to sync")
+  })}
+  onExecute={(params) => triggerSync(params.property_ids)}
+>
+  <SyncButton />
+</AgentAction>
+```
+
+**Multi-step actions** — sequential clicks (e.g. open dropdown, then select):
+
+```tsx
+<AgentAction name="sync_data" description="Sync from API">
+  <AgentStep label="Open sync menu">
+    <DropdownTrigger />
+  </AgentStep>
+  <AgentStep label="Click sync">
+    <SyncButton />
+  </AgentStep>
+</AgentAction>
+```
+
+### 3. Connect to your agent
+
+```tsx
+const { schemas, execute, availableActions, isExecuting } = useAgentActions();
+
+// Send schemas to your agent backend (auto-updates as components mount/unmount)
+// Call execute("action_name", params) when the agent responds with a tool call
+```
+
+### 4. Integrate with existing handlers
+
+```tsx
+import { useAgentCommandRouter } from 'polter';
+
+// Wraps any existing command handler — registered actions get visual execution,
+// unregistered ones fall through to your original handler.
+const handleCommand = useAgentCommandRouter(existingHandler, (cmd) => cmd.action);
+```
+
+## How it works
+
+1. `<AgentAction>` registers actions in a React context on mount, deregisters on unmount
+2. The registry always reflects exactly what's on screen — schemas auto-generate from Zod parameter definitions
+3. `execute(name, params)` looks up the action, finds the DOM element via refs, runs: **scroll into view → dim surroundings → spotlight with pulsing ring → tooltip → pause → click/execute → cleanup**
+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.
+
+## API
+
+### Execution modes
+
+| Mode | Behavior | Use case |
+|------|----------|----------|
+| `"guided"` | Scroll → spotlight → pause → click | Teaching users, first-time flows |
+| `"instant"` | Execute immediately, no visual | Power users, repeat actions |
+
+### Provider props
+
+| Prop | Type | Default |
+|------|------|---------|
+| `mode` | `"guided" \| "instant"` | `"guided"` |
+| `stepDelay` | `number` | `600` |
+| `overlayOpacity` | `number` | `0.5` |
+| `spotlightPadding` | `number` | `8` |
+| `tooltipEnabled` | `boolean` | `true` |
+| `onExecutionStart` | `(name: string) => void` | — |
+| `onExecutionComplete` | `(result: ExecutionResult) => void` | — |
+
+### Disabled actions
+
+```tsx
+<AgentAction
+  name="push_changes"
+  description="Push pending changes"
+  disabled={!hasPendingChanges}
+  disabledReason="No pending changes to push"
+>
+  <PushButton />
+</AgentAction>
+```
+
+Disabled actions appear in `availableActions` but are excluded from `schemas`. Calling `execute()` on a disabled action returns `{ success: false, error: "No pending changes to push" }`.
+
+### CSS customization
+
+All overlay elements have class names:
+
+```css
+.polter-spotlight { /* box-shadow overlay with cutout */ }
+.polter-ring { /* pulsing border around target */ }
+.polter-tooltip { /* label tooltip */ }
+```
+
+## 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>
+```
+
+## Zero dependencies
+
+Peer deps only: React 18+ and Zod. No runtime dependencies.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,220 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React$1 from 'react';
+
+type ExecutionMode = 'guided' | 'instant';
+interface ExecutionTarget {
+    label: string;
+    element: HTMLElement | null;
+    /** Resolve element from AgentTarget registry by matching this param's value. */
+    fromParam?: string;
+    /** Resolve element from AgentTarget registry by matching a named target. */
+    fromTarget?: string;
+    /** Simulate typing the value of this param into the element. */
+    setParam?: string;
+    /** Set a value programmatically via onSetValue callback. */
+    setValue?: string;
+    onSetValue?: (value: unknown) => void;
+    /** Run a callback to prepare the DOM (e.g. scroll virtualized list) before resolving. */
+    prepareView?: (params: Record<string, unknown>) => void | Promise<void>;
+}
+interface AgentTargetEntry {
+    /** Action name — when omitted, the target is shared and matches any action. */
+    action?: string;
+    element: HTMLElement;
+    /** Parameter key — used with `value` for param-based resolution. */
+    param?: string;
+    /** Parameter value — matched against the agent's param value. */
+    value?: string;
+    /** Named target key — used for static lazy resolution via `fromTarget`. */
+    name?: string;
+}
+interface RegisteredAction {
+    name: string;
+    description: string;
+    parameters?: unknown;
+    onExecute?: (params: Record<string, unknown>) => void | Promise<void>;
+    disabled: boolean;
+    disabledReason?: string;
+    getExecutionTargets: () => ExecutionTarget[];
+}
+interface ToolSchema {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+}
+interface ExecutionResult {
+    success: boolean;
+    actionName: string;
+    error?: string;
+}
+interface AvailableAction {
+    name: string;
+    description: string;
+    disabled: boolean;
+    disabledReason?: string;
+    hasParameters: boolean;
+}
+interface ExecutorConfig {
+    mode: ExecutionMode;
+    stepDelay: number;
+    overlayOpacity: number;
+    spotlightPadding: number;
+    tooltipEnabled: boolean;
+    cursorEnabled: boolean;
+    signal?: AbortSignal;
+    /** Resolve an element from the AgentTarget registry. Used by fromParam steps. */
+    resolveTarget?: (actionName: string, param: string, value: string, signal?: AbortSignal) => Promise<HTMLElement | null>;
+    /** Resolve a named target from the AgentTarget registry. Used by fromTarget steps. */
+    resolveNamedTarget?: (actionName: string, name: string, signal?: AbortSignal) => Promise<HTMLElement | null>;
+}
+interface AgentActionProviderProps {
+    mode?: ExecutionMode;
+    stepDelay?: number;
+    overlayOpacity?: number;
+    spotlightPadding?: number;
+    tooltipEnabled?: boolean;
+    cursorEnabled?: boolean;
+    children: React.ReactNode;
+    onExecutionStart?: (actionName: string) => void;
+    onExecutionComplete?: (result: ExecutionResult) => void;
+}
+interface AgentActionContextValue {
+    registerAction: (action: RegisteredAction) => void;
+    unregisterAction: (name: string) => void;
+    registerTarget: (id: string, entry: AgentTargetEntry) => void;
+    unregisterTarget: (id: string) => void;
+    execute: (actionName: string, params?: Record<string, unknown>) => Promise<ExecutionResult>;
+    availableActions: AvailableAction[];
+    schemas: ToolSchema[];
+    isExecuting: boolean;
+    mode: ExecutionMode;
+}
+
+declare function AgentActionProvider({ mode, stepDelay, overlayOpacity, spotlightPadding, tooltipEnabled, cursorEnabled, children, onExecutionStart, onExecutionComplete, }: AgentActionProviderProps): react_jsx_runtime.JSX.Element;
+
+interface AgentActionProps {
+    name: string;
+    description: string;
+    parameters?: unknown;
+    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;
+
+interface AgentStepProps {
+    label: string;
+    children?: React$1.ReactNode;
+    /** Resolve the target element from the AgentTarget registry by matching this param's value. */
+    fromParam?: string;
+    /** Resolve a named target from the AgentTarget registry (for static elements inside popovers/dropdowns). */
+    fromTarget?: string;
+    /** Simulate typing the value of this param into the element. */
+    setParam?: string;
+    /** Set a value programmatically via onSetValue callback. */
+    setValue?: string;
+    /** Callback for setValue — receives the param value and sets it on the component. */
+    onSetValue?: (value: unknown) => void;
+    /** Run a callback to prepare the DOM (e.g. scroll a virtualized list) before resolving the target. */
+    prepareView?: (params: Record<string, unknown>) => void | Promise<void>;
+}
+declare function AgentStep({ label, children, fromParam, fromTarget, setParam, setValue, onSetValue, prepareView, }: AgentStepProps): react_jsx_runtime.JSX.Element | null;
+
+interface AgentTargetProps {
+    /** The action name this target belongs to. Omit to make a shared target that any action can resolve. */
+    action?: string;
+    children: React$1.ReactNode;
+    /** The parameter key this target maps to (for fromParam resolution). */
+    param?: string;
+    /** The parameter value this target represents (for fromParam resolution). */
+    value?: string;
+    /** Named target key (for fromTarget resolution — static elements inside popovers/dropdowns). */
+    name?: string;
+}
+/**
+ * Register a DOM element as a selectable target for an agent action step.
+ *
+ * Use this to wrap lazily-rendered elements (dropdown options, search results, etc.)
+ * so that `AgentStep fromParam` or `AgentStep fromTarget` can find and interact
+ * with them after they mount.
+ *
+ * Works through React portals — context flows regardless of DOM position.
+ *
+ * @example
+ * ```tsx
+ * // Dynamic: match by param value (inside a dropdown's renderOption):
+ * <AgentTarget action="filter_by_tag" param="tag_name" value={option.label}>
+ *   <DropdownOption>{option.label}</DropdownOption>
+ * </AgentTarget>
+ *
+ * // Static: match by name (inside a popover that mounts lazily):
+ * <AgentTarget action="toggle_frozen_columns" name="freeze-btn">
+ *   <button>Freeze columns</button>
+ * </AgentTarget>
+ * ```
+ */
+declare function AgentTarget({ action, param, value, name, children }: AgentTargetProps): react_jsx_runtime.JSX.Element;
+
+interface AgentDevToolsProps {
+    /** Default open state. */
+    defaultOpen?: boolean;
+}
+declare function AgentDevTools({ defaultOpen }: AgentDevToolsProps): react_jsx_runtime.JSX.Element;
+
+interface StepConfig {
+    label: string;
+    fromParam?: string;
+    fromTarget?: string;
+    setParam?: string;
+    setValue?: string;
+    onSetValue?: (value: unknown) => void;
+    prepareView?: (params: Record<string, unknown>) => void | Promise<void>;
+}
+interface AgentActionConfig {
+    name: string;
+    description: string;
+    parameters?: unknown;
+    onExecute?: (params: Record<string, unknown>) => void | Promise<void>;
+    disabled?: boolean;
+    disabledReason?: string;
+    steps?: StepConfig[];
+}
+/**
+ * Hook-based action registration for actions that don't wrap a single element.
+ * Use this for per-row actions where AgentTargets are on scattered elements
+ * and the action resolves to them via fromParam/fromTarget.
+ *
+ * Accepts a single config or an array to batch-register multiple actions.
+ *
+ * For actions that wrap a visible element, prefer the <AgentAction> component.
+ */
+declare function useAgentAction(config: AgentActionConfig | AgentActionConfig[]): void;
+
+declare function useAgentActions(): AgentActionContextValue;
+
+/**
+ * Wraps an existing command handler with agent action routing.
+ *
+ * When a command arrives, if a matching `<AgentAction>` is mounted and enabled,
+ * it routes through `execute()` for visual guided execution. Otherwise it falls
+ * through to the original handler.
+ *
+ * Works with any command shape — you provide `getActionName` to extract the
+ * action name from your command object.
+ *
+ * @example
+ * ```tsx
+ * const handleCommand = useAgentCommandRouter(
+ *   existingHandler,
+ *   (cmd) => cmd.action,
+ * );
+ * ```
+ */
+declare function useAgentCommandRouter<T>(fallback: ((command: T) => void | Promise<void>) | null, getActionName: (command: T) => string): (command: T) => Promise<void>;
+
+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 };