@mydatavalue/polter 0.1.2 → 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;
@@ -119,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;
@@ -196,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.
@@ -219,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;
@@ -119,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;
@@ -196,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.
@@ -219,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;
           }
         }
@@ -848,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");
   }
@@ -859,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]);