@mydatavalue/polter 0.1.1 → 0.1.3

package/dist/index.d.mts

@@ -73,6 +73,8 @@ interface AgentTargetEntry {
     value?: string;
     /** Named target key — used for static lazy resolution via `fromTarget`. */
     name?: string;
+    /** Run a callback to prepare component state before the agent interacts with this target. */
+    prepareView?: (params: Record<string, unknown>) => void | Promise<void>;
 }
 interface RegisteredAction {
     name: string;
@@ -88,6 +90,8 @@ interface RegisteredAction {
     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;
@@ -117,7 +121,7 @@ interface ExecutorConfig {
     /** 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>;
+    resolveNamedTarget?: (actionName: string, name: string, signal?: AbortSignal, params?: Record<string, unknown>) => Promise<HTMLElement | null>;
 }
 interface AgentActionProviderProps {
     mode?: ExecutionMode;
@@ -194,6 +198,8 @@ interface AgentTargetProps {
     value?: string;
     /** Named target key (for fromTarget resolution — static elements inside popovers/dropdowns). */
     name?: string;
+    /** Run a callback to prepare component state before the agent interacts with this target. Runs in the child's scope so it can access internal state. */
+    prepareView?: (params: Record<string, unknown>) => void | Promise<void>;
 }
 /**
  * Register a DOM element as a selectable target for an agent action step.
@@ -217,7 +223,7 @@ interface AgentTargetProps {
  * </AgentTarget>
  * ```
  */
-declare function AgentTarget({ action, param, value, name, children }: AgentTargetProps): react_jsx_runtime.JSX.Element;
+declare function AgentTarget({ action, param, value, name, prepareView, children }: AgentTargetProps): react_jsx_runtime.JSX.Element;
 
 interface AgentDevToolsProps {
     /** Default open state. */

package/dist/index.d.ts

@@ -73,6 +73,8 @@ interface AgentTargetEntry {
     value?: string;
     /** Named target key — used for static lazy resolution via `fromTarget`. */
     name?: string;
+    /** Run a callback to prepare component state before the agent interacts with this target. */
+    prepareView?: (params: Record<string, unknown>) => void | Promise<void>;
 }
 interface RegisteredAction {
     name: string;
@@ -88,6 +90,8 @@ interface RegisteredAction {
     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;
@@ -117,7 +121,7 @@ interface ExecutorConfig {
     /** 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>;
+    resolveNamedTarget?: (actionName: string, name: string, signal?: AbortSignal, params?: Record<string, unknown>) => Promise<HTMLElement | null>;
 }
 interface AgentActionProviderProps {
     mode?: ExecutionMode;
@@ -194,6 +198,8 @@ interface AgentTargetProps {
     value?: string;
     /** Named target key (for fromTarget resolution — static elements inside popovers/dropdowns). */
     name?: string;
+    /** Run a callback to prepare component state before the agent interacts with this target. Runs in the child's scope so it can access internal state. */
+    prepareView?: (params: Record<string, unknown>) => void | Promise<void>;
 }
 /**
  * Register a DOM element as a selectable target for an agent action step.
@@ -217,7 +223,7 @@ interface AgentTargetProps {
  * </AgentTarget>
  * ```
  */
-declare function AgentTarget({ action, param, value, name, children }: AgentTargetProps): react_jsx_runtime.JSX.Element;
+declare function AgentTarget({ action, param, value, name, prepareView, children }: AgentTargetProps): react_jsx_runtime.JSX.Element;
 
 interface AgentDevToolsProps {
     /** Default open state. */

package/dist/index.js

@@ -330,7 +330,7 @@ async function resolveStepElement(target, actionName, params, config) {
     return config.resolveTarget(actionName, target.fromParam, paramValue, config.signal);
   }
   if (target.fromTarget && config.resolveNamedTarget) {
-    return config.resolveNamedTarget(actionName, target.fromTarget, config.signal);
+    return config.resolveNamedTarget(actionName, target.fromTarget, config.signal, params);
   }
   return target.element;
 }
@@ -542,7 +542,7 @@ function AgentActionProvider({
     []
   );
   const resolveNamedTarget = react.useCallback(
-    async (actionName, name, signal) => {
+    async (actionName, name, signal, params) => {
       const maxWait = 3e3;
       const pollInterval = 50;
       const start = Date.now();
@@ -550,6 +550,9 @@ function AgentActionProvider({
         if (signal?.aborted) return null;
         for (const entry of targetsRef.current.values()) {
           if ((!entry.action || entry.action === actionName) && entry.name === name && entry.element.isConnected) {
+            if (entry.prepareView && params) {
+              await entry.prepareView(params);
+            }
             return entry.element;
           }
         }
@@ -567,7 +570,7 @@ function AgentActionProvider({
       while (Date.now() - start < maxWait) {
         if (signal?.aborted) return null;
         const current = actionsRef.current.get(name);
-        if (current && current.getExecutionTargets().length > 0) {
+        if (current && (current.componentBacked || current.getExecutionTargets().length > 0)) {
           return current;
         }
         await new Promise((r) => setTimeout(r, pollInterval));
@@ -606,6 +609,15 @@ function AgentActionProvider({
           resolveTarget,
           resolveNamedTarget
         };
+        const schema = action.parameters;
+        if (schema?.safeParse) {
+          const validation = schema.safeParse(params ?? {});
+          if (!validation.success) {
+            const missing = validation.error.issues.map((i) => i.path.join(".")).filter(Boolean);
+            const error = missing.length > 0 ? `Required parameters missing: ${missing.join(", ")}` : validation.error.issues.map((i) => i.message).join("; ");
+            return { success: false, actionName, error };
+          }
+        }
         if (action.navigateVia && action.navigateVia.length > 0) {
           for (const viaName of action.navigateVia) {
             if (controller.signal.aborted) break;
@@ -629,7 +641,7 @@ function AgentActionProvider({
             }
           }
           const mounted = await waitForActionMount(actionName, controller.signal, action.mountTimeout ?? 1e4);
-          if (!mounted || mounted.getExecutionTargets().length === 0) {
+          if (!mounted || !mounted.componentBacked) {
             return {
               success: false,
               actionName,
@@ -781,7 +793,8 @@ function AgentAction(props) {
       onExecute: onExecuteRef.current ? stableOnExecute : void 0,
       disabled,
       disabledReason,
-      getExecutionTargets
+      getExecutionTargets,
+      componentBacked: true
     });
     return () => unregisterAction(name);
   }, [name, description, disabled, disabledReason, stableOnExecute, getExecutionTargets, registerAction, unregisterAction]);
@@ -838,10 +851,12 @@ function AgentStep({
   if (!children) return null;
   return /* @__PURE__ */ jsxRuntime.jsx("div", { ref: wrapperRef, style: { display: "contents" }, children });
 }
-function AgentTarget({ action, param, value, name, children }) {
+function AgentTarget({ action, param, value, name, prepareView, children }) {
   const id = react.useId();
   const wrapperRef = react.useRef(null);
   const context = react.useContext(AgentActionContext);
+  const prepareViewRef = react.useRef(prepareView);
+  prepareViewRef.current = prepareView;
   if (!context) {
     throw new Error("AgentTarget must be used within an AgentActionProvider");
   }
@@ -849,7 +864,7 @@ function AgentTarget({ action, param, value, name, children }) {
   react.useEffect(() => {
     const element = wrapperRef.current?.firstElementChild;
     if (element) {
-      registerTarget(id, { action, param, value, name, element });
+      registerTarget(id, { action, param, value, name, element, prepareView: prepareViewRef.current });
     }
     return () => unregisterTarget(id);
   }, [id, action, param, value, name, registerTarget, unregisterTarget]);