cdp-skill 1.0.16 → 1.0.17

package/{src → scripts}/runner/execute-input.js

@@ -3,105 +3,14 @@
  * Fill and select step executors
  *
  * EXPORTS:
- * - executeFill(elementLocator, inputEmulator, params) → Promise<void>
  * - executeFillActive(pageController, inputEmulator, params) → Promise<Object>
  * - executeSelectOption(elementLocator, params) → Promise<Object>
  *
  * DEPENDENCIES:
- * - ../dom/index.js: createElementValidator, createReactInputFiller
- * - ../utils.js: elementNotFoundError, elementNotEditableError, resetInputState
+ * - ../utils.js: elementNotFoundError
  */
 
-import { createElementValidator, createReactInputFiller } from '../dom/index.js';
-import { elementNotFoundError, elementNotEditableError, resetInputState } from '../utils.js';
-
-export async function executeFill(elementLocator, inputEmulator, params) {
-  const { selector, value, react } = params;
-
-  if (!selector || value === undefined) {
-    throw new Error('Fill requires selector and value');
-  }
-
-  const element = await elementLocator.findElement(selector);
-  if (!element) {
-    throw elementNotFoundError(selector, 0);
-  }
-
-  // Validate element is editable before attempting fill
-  const validator = createElementValidator(elementLocator.session);
-  const editableCheck = await validator.isEditable(element._handle.objectId);
-  if (!editableCheck.editable) {
-    await element._handle.dispose();
-    throw elementNotEditableError(selector, editableCheck.reason);
-  }
-
-  // Try fast path first - scroll to center with short stability check
-  let actionable;
-  try {
-    await element._handle.scrollIntoView({ block: 'center' });
-    // Use short stability timeout - most elements stabilize quickly
-    await element._handle.waitForStability({ frames: 2, timeout: 300 });
-    actionable = await element._handle.isActionable();
-  } catch (e) {
-    // Stability check failed, check actionability anyway
-    actionable = await element._handle.isActionable();
-  }
-
-  // If not actionable, try alternative scroll strategies
-  if (!actionable.actionable) {
-    let lastError = new Error(`Element not actionable: ${actionable.reason}`);
-
-    for (const strategy of ['end', 'start', 'nearest']) {
-      try {
-        await element._handle.scrollIntoView({ block: strategy });
-        await element._handle.waitForStability({ frames: 2, timeout: 500 });
-        actionable = await element._handle.isActionable();
-
-        if (actionable.actionable) break;
-        lastError = new Error(`Element not actionable: ${actionable.reason}`);
-      } catch (e) {
-        lastError = e;
-      }
-    }
-
-    if (!actionable.actionable) {
-      await element._handle.dispose();
-      await resetInputState(elementLocator.session);
-      throw lastError;
-    }
-  }
-
-  try {
-    // Use React-specific fill approach if react option is set
-    if (react) {
-      const reactFiller = createReactInputFiller(elementLocator.session);
-      await reactFiller.fillByObjectId(element._handle.objectId, value);
-      return; // Success
-    }
-
-    // Standard fill approach using keyboard events
-    const box = await element._handle.getBoundingBox();
-    const x = box.x + box.width / 2;
-    const y = box.y + box.height / 2;
-
-    // Click to focus
-    await inputEmulator.click(x, y);
-
-    // Focus element directly - more reliable than relying on click
-    await element._handle.focus();
-
-    if (params.clear !== false) {
-      await inputEmulator.selectAll();
-    }
-
-    await inputEmulator.type(String(value));
-  } catch (e) {
-    await resetInputState(elementLocator.session);
-    throw e;
-  } finally {
-    await element._handle.dispose();
-  }
-}
+import { elementNotFoundError } from '../utils.js';
 
 /**
  * Execute a selectOption step - select option in dropdown
@@ -226,15 +135,12 @@ export async function executeSelectOption(elementLocator, params) {
  */
 
 export async function executeFillActive(pageController, inputEmulator, params) {
-  const session = pageController.session;
-
   // Parse params
   const value = typeof params === 'string' ? params : (params && params.value);
   const clear = typeof params === 'object' && params !== null ? params.clear !== false : true;
 
   // Check if there's an active element and if it's editable
-  const checkResult = await session.send('Runtime.evaluate', {
-    expression: `(function() {
+  const checkResult = await pageController.evaluateInFrame(`(function() {
       const el = document.activeElement;
       if (!el || el === document.body || el === document.documentElement) {
         return { error: 'No element is focused' };
@@ -271,9 +177,8 @@ export async function executeFillActive(pageController, inputEmulator, params) {
         selector: selector,
         valueBefore: el.value || ''
       };
-    })()`,
-    returnByValue: true
-  });
+    })()`);
+
 
   if (checkResult.exceptionDetails) {
     throw new Error(`fillActive error: ${checkResult.exceptionDetails.text}`);
@@ -302,6 +207,128 @@ export async function executeFillActive(pageController, inputEmulator, params) {
   };
 }
 
+/**
+ * Execute an upload step - set files on a file input element via CDP
+ * Uses DOM.setFileInputFiles to set file paths on <input type="file"> elements
+ *
+ * Shapes:
+ *   {"upload": "/path/to/file.txt"}                           — single file, auto-find file input
+ *   {"upload": ["/path/a.txt", "/path/b.png"]}                — multiple files, auto-find file input
+ *   {"upload": {"selector": "#file-input", "file": "a.txt"}}  — targeted single file
+ *   {"upload": {"selector": "#file-input", "files": ["a.txt", "b.png"]}} — targeted multiple files
+ *   {"upload": {"ref": "f0s1e3", "files": ["a.txt"]}}         — ref-targeted
+ */
+export async function executeUpload(elementLocator, pageController, params) {
+  const session = elementLocator.session;
+
+  // Normalize params into { files, selector?, ref? }
+  let files, selector, ref;
+  if (typeof params === 'string') {
+    files = [params];
+  } else if (Array.isArray(params)) {
+    files = params;
+  } else {
+    selector = params.selector;
+    ref = params.ref;
+    files = params.files || (params.file ? [params.file] : []);
+  }
+
+  // Find the file input element
+  let objectId;
+  try {
+    if (ref) {
+      // Resolve ref to objectId via aria refs
+      const evalParams = {
+        expression: `window.__ariaRefs && window.__ariaRefs.get(${JSON.stringify(ref)})`,
+        returnByValue: false
+      };
+      const contextId = pageController.getFrameContext();
+      if (contextId) evalParams.contextId = contextId;
+      const result = await session.send('Runtime.evaluate', evalParams);
+      if (!result.result.objectId) {
+        throw new Error(`Element ref ${ref} not found — run 'snapshot' to get fresh refs`);
+      }
+      objectId = result.result.objectId;
+    } else if (selector) {
+      // Find by CSS selector
+      const evalParams = {
+        expression: `document.querySelector(${JSON.stringify(selector)})`,
+        returnByValue: false
+      };
+      const contextId = pageController.getFrameContext();
+      if (contextId) evalParams.contextId = contextId;
+      const result = await session.send('Runtime.evaluate', evalParams);
+      if (!result.result.objectId) {
+        throw elementNotFoundError(selector, 0);
+      }
+      objectId = result.result.objectId;
+    } else {
+      // Auto-find: look for a file input on the page
+      const evalParams = {
+        expression: `document.querySelector('input[type="file"]')`,
+        returnByValue: false
+      };
+      const contextId = pageController.getFrameContext();
+      if (contextId) evalParams.contextId = contextId;
+      const result = await session.send('Runtime.evaluate', evalParams);
+      if (!result.result.objectId) {
+        throw new Error('No file input (input[type="file"]) found on the page');
+      }
+      objectId = result.result.objectId;
+    }
+
+    // Verify it's actually a file input
+    const typeCheck = await session.send('Runtime.callFunctionOn', {
+      objectId,
+      functionDeclaration: `function() {
+        return {
+          tagName: this.tagName,
+          type: this.type,
+          accept: this.accept || '',
+          multiple: this.hasAttribute('multiple')
+        };
+      }`,
+      returnByValue: true
+    });
+
+    const info = typeCheck.result.value;
+    if (!info || info.tagName !== 'INPUT' || info.type !== 'file') {
+      throw new Error(`Target element is ${info?.tagName || 'unknown'} type="${info?.type || 'unknown'}" — expected input[type="file"]`);
+    }
+
+    if (files.length > 1 && !info.multiple) {
+      throw new Error(`File input does not have 'multiple' attribute but ${files.length} files were provided`);
+    }
+
+    // Set files via CDP
+    await session.send('DOM.setFileInputFiles', {
+      objectId,
+      files
+    });
+
+    // Dispatch change event so frameworks detect the file selection
+    await session.send('Runtime.callFunctionOn', {
+      objectId,
+      functionDeclaration: `function() {
+        this.dispatchEvent(new Event('change', { bubbles: true }));
+        this.dispatchEvent(new Event('input', { bubbles: true }));
+      }`
+    });
+
+    return {
+      uploaded: true,
+      files,
+      accept: info.accept,
+      multiple: info.multiple,
+      target: selector || ref || 'input[type="file"]'
+    };
+  } finally {
+    if (objectId) {
+      try { await session.send('Runtime.releaseObject', { objectId }); } catch {}
+    }
+  }
+}
+
 /**
  * Execute a refAt step - get or create a ref for the element at given coordinates
  * Uses document.elementFromPoint to find the element, then assigns/retrieves a ref

package/{src → scripts}/runner/execute-interaction.js

@@ -4,6 +4,7 @@
  *
  * EXPORTS:
  * - executeClick(elementLocator, inputEmulator, ariaSnapshot, params) → Promise<Object>
+ * - clickWithVerification: removed (stale, superseded by click-executor.js pointerdown version)
  * - executeHover(elementLocator, inputEmulator, ariaSnapshot, params) → Promise<Object>
  * - executeDrag(elementLocator, inputEmulator, pageController, ariaSnapshot, params) → Promise<Object>
  *
@@ -15,8 +16,6 @@
 import { createClickExecutor, createActionabilityChecker } from '../dom/index.js';
 import { elementNotFoundError, sleep, resetInputState, releaseObject } from '../utils.js';
 
-const SCROLL_STRATEGIES = ['center', 'end', 'start', 'nearest'];
-
 export async function executeClick(elementLocator, inputEmulator, ariaSnapshot, params) {
   // Delegate to ClickExecutor for improved click handling with JS fallback
   const clickExecutor = createClickExecutor(
@@ -28,42 +27,6 @@ export async function executeClick(elementLocator, inputEmulator, ariaSnapshot,
   return clickExecutor.execute(params);
 }
 
-export async function clickWithVerification(elementLocator, inputEmulator, x, y, targetObjectId) {
-  const session = elementLocator.session;
-
-  // Setup event listener on target before clicking
-  await session.send('Runtime.callFunctionOn', {
-    objectId: targetObjectId,
-    functionDeclaration: `function() {
-      this.__clickReceived = false;
-      this.__clickHandler = () => { this.__clickReceived = true; };
-      this.addEventListener('click', this.__clickHandler, { once: true });
-    }`
-  });
-
-  // Perform click
-  await inputEmulator.click(x, y);
-  await sleep(50);
-
-  // Check if target received the click
-  const verifyResult = await session.send('Runtime.callFunctionOn', {
-    objectId: targetObjectId,
-    functionDeclaration: `function() {
-      this.removeEventListener('click', this.__clickHandler);
-      const received = this.__clickReceived;
-      delete this.__clickReceived;
-      delete this.__clickHandler;
-      return received;
-    }`,
-    returnByValue: true
-  });
-
-  return {
-    clicked: true,
-    targetReceived: verifyResult.result.value === true
-  };
-}
-
 /**
  * Execute a hover step - moves mouse over an element to trigger hover events
  * Uses Playwright-style auto-waiting for element to be visible and stable
@@ -187,7 +150,9 @@ export async function executeHover(elementLocator, inputEmulator, ariaSnapshot,
 
   // Use Playwright-style auto-waiting for element to be actionable
   // Hover requires: visible, stable
-  const actionabilityChecker = createActionabilityChecker(elementLocator.session);
+  const actionabilityChecker = createActionabilityChecker(elementLocator.session, {
+    getFrameContext: elementLocator.getFrameContext || null
+  });
   const waitResult = await actionabilityChecker.waitForActionable(selector, 'hover', {
     timeout,
     force
@@ -428,7 +393,7 @@ export async function executeDrag(elementLocator, inputEmulator, pageController,
   const sourceSelector = getSelectorExpression(source);
   const targetSelector = getSelectorExpression(target);
 
-  const jsDragResult = await session.send('Runtime.evaluate', {
+  const dragEvalParams = {
     expression: `
       (function() {
         const sourceEl = ${sourceSelector || 'null'};
@@ -523,21 +488,41 @@ export async function executeDrag(elementLocator, inputEmulator, pageController,
         if (method === 'mouse') return doMouseDrag();
         if (method === 'html5') return doHtml5Drag();
 
-        // auto: try mouse first (works for jQuery UI, sortable lists), then HTML5 DnD
-        const mouseResult = doMouseDrag();
-        if (mouseResult.success) return mouseResult;
-
-        if (sourceEl && targetEl) {
+        // auto: detect HTML5 DnD indicators before choosing method
+        const needsHtml5 = sourceEl && targetEl && (
+          sourceEl.draggable ||
+          sourceEl.hasAttribute('ondragstart') ||
+          sourceEl.hasAttribute('ondrag') ||
+          targetEl.hasAttribute('ondrop') ||
+          targetEl.hasAttribute('ondragover')
+        );
+
+        if (needsHtml5) {
+          // Try HTML5 DnD first for elements that clearly use it
           const html5Result = doHtml5Drag();
           if (html5Result.success) return html5Result;
+          // Fall back to mouse if HTML5 failed
+          return doMouseDrag();
         }
 
+        // No HTML5 indicators — use mouse events, fall back to HTML5
+        const mouseResult = doMouseDrag();
+        if (!mouseResult.success && sourceEl && targetEl) {
+          const html5Result = doHtml5Drag();
+          if (html5Result.success) return html5Result;
+        }
         return mouseResult;
       })()
     `,
     returnByValue: true,
     awaitPromise: false
-  });
+  };
+
+  // Add frame context if in an iframe
+  const contextId = pageController.getFrameContext();
+  if (contextId) dragEvalParams.contextId = contextId;
+
+  const jsDragResult = await session.send('Runtime.evaluate', dragEvalParams);
 
   const dragResult = jsDragResult.result?.value;
 

package/{src → scripts}/runner/execute-navigation.js

@@ -31,11 +31,10 @@ export async function executeWait(elementLocator, params) {
  * @returns {Promise<void>}
  */
 export async function executeWaitForNavigation(pageController, params) {
-  const options = params === true ? {} : params;
+  const options = (params && typeof params === 'object') ? params : {};
   const timeout = options.timeout || 30000;
   const waitUntil = options.waitUntil || 'load';
 
-  const session = pageController.session;
   const startTime = Date.now();
 
   // Poll for page ready state
@@ -47,11 +46,8 @@ export async function executeWaitForNavigation(pageController, params) {
       }
 
       try {
-        const result = await session.send('Runtime.evaluate', {
-          expression: 'document.readyState',
-          returnByValue: true
-        });
-        const readyState = result.result.value;
+        const result = await pageController.evaluateInFrame('document.readyState');
+        const readyState = result.result?.value;
 
         if (waitUntil === 'commit') {
           resolve();
@@ -130,8 +126,11 @@ export async function executeScroll(elementLocator, inputEmulator, pageControlle
           if (!el) {
             throw elementNotFoundError(params, 0);
           }
-          await el.scrollIntoView();
-          await el.dispose();
+          try {
+            await el.scrollIntoView();
+          } finally {
+            await el.dispose();
+          }
         }
     }
   } else if (params && typeof params === 'object') {
@@ -145,8 +144,11 @@ export async function executeScroll(elementLocator, inputEmulator, pageControlle
       if (!el) {
         throw elementNotFoundError(params.selector, 0);
       }
-      await el.scrollIntoView();
-      await el.dispose();
+      try {
+        await el.scrollIntoView();
+      } finally {
+        await el.dispose();
+      }
     } else if (params.deltaY !== undefined || params.deltaX !== undefined) {
       // Scroll by delta using JavaScript (more reliable than CDP mouse wheel events)
       await pageController.evaluateInFrame(`window.scrollBy(${params.deltaX || 0}, ${params.deltaY || 0})`);
@@ -161,5 +163,5 @@ export async function executeScroll(elementLocator, inputEmulator, pageControlle
     '({ scrollX: window.scrollX, scrollY: window.scrollY })'
   );
 
-  return posResult.result.value;
+  return posResult.result?.value ?? { scrollX: 0, scrollY: 0 };
 }

package/{src → scripts}/runner/step-executors.js

@@ -9,7 +9,7 @@
  * SUBMODULES:
  * - ./execute-navigation.js: executeWait, executeWaitForNavigation, executeScroll
  * - ./execute-interaction.js: executeClick, executeHover, executeDrag
- * - ./execute-input.js: executeFill, executeFillActive, executeSelectOption
+ * - ./execute-input.js: executeFillActive, executeSelectOption
  * - ./execute-query.js: executeSnapshot, executeQuery, executeQueryAll, executeInspect, etc.
  * - ./execute-form.js: executeValidate, executeSubmit, executeFormState, executeExtract, executeAssert
  * - ./execute-browser.js: executePdf, executeEval, executeCookies, executeConsole, etc.
@@ -47,10 +47,10 @@ import { validateSteps } from './step-validator.js';
 // Import domain executors
 import { executeWait, executeWaitForNavigation, executeScroll } from './execute-navigation.js';
 import { executeClick, executeHover, executeDrag } from './execute-interaction.js';
-import { executeFillActive, executeSelectOption } from './execute-input.js';
+import { executeFillActive, executeSelectOption, executeUpload } from './execute-input.js';
 import { executeSnapshot, executeSnapshotSearch, executeQuery, executeQueryAll, executeInspect, executeGetDom, executeGetBox, executeRefAt, executeElementsAt, executeElementsNear } from './execute-query.js';
 // executeRefAt, executeElementsNear kept for internal dispatch from unified elementsAt
-import { executeSubmit, executeExtract } from './execute-form.js';
+import { executeSubmit, executeExtract, executeAssert } from './execute-form.js';
 import { executePdf, executeEval, executeCookies, executeListTabs, executeCloseTab, executeConsole, formatCommandConsole } from './execute-browser.js';
 // executeEval kept for internal dispatch from unified pageFunction
 import { executePageFunction, executePoll, executeWriteSiteProfile, executeReadSiteProfile, loadSiteProfile } from './execute-dynamic.js';
@@ -115,7 +115,7 @@ export async function executeStep(deps, step, options = {}) {
     if (actionValue && typeof actionValue === 'object' && actionValue.readyWhen) {
       const readyResult = await executePoll(pageController, {
         fn: actionValue.readyWhen,
-        timeout: options.stepTimeout || 30000
+        timeout: stepTimeout || 30000
       });
       if (!readyResult.resolved) {
         throw new Error(`readyWhen did not resolve within timeout`);
@@ -397,6 +397,9 @@ export async function executeStep(deps, step, options = {}) {
     } else if (step.drag !== undefined) {
       stepResult.action = 'drag';
       stepResult.output = await executeDrag(elementLocator, inputEmulator, pageController, deps.ariaSnapshot, step.drag);
+    } else if (step.upload !== undefined) {
+      stepResult.action = 'upload';
+      stepResult.output = await executeUpload(elementLocator, pageController, step.upload);
     } else if (step.get !== undefined) {
       stepResult.action = 'get';
       const getParams = step.get;
@@ -416,10 +419,29 @@ export async function executeStep(deps, step, options = {}) {
         const selector = typeof getParams === 'string' ? getParams : getParams.selector;
         stepResult.output = await formValidator.getFormState(selector);
         stepResult.output.mode = 'value';
+      } else if (mode === 'attributes') {
+        // Attributes extraction — return all HTML attributes of the element
+        const selector = getParams.selector || getParams.ref;
+        const attrResult = await pageController.evaluateInFrame(`
+          (function() {
+            const el = document.querySelector(${JSON.stringify(selector)});
+            if (!el) return { error: 'Element not found: ' + ${JSON.stringify(selector)} };
+            const attrs = {};
+            for (const attr of el.attributes) {
+              attrs[attr.name] = attr.value;
+            }
+            return { attributes: attrs };
+          })()
+        `, { returnByValue: true });
+        const data = attrResult.result?.value;
+        if (data?.error) {
+          throw new Error(data.error);
+        }
+        stepResult.output = { attributes: data?.attributes || {}, mode: 'attributes' };
       } else {
-        // Default: text/attributes extraction → use extract
+        // Default: text extraction (with auto table/list detection)
         stepResult.output = await executeExtract(deps, getParams);
-        stepResult.output.mode = mode || 'text';
+        stepResult.output.mode = 'text';
       }
     } else if (step.selectOption !== undefined) {
       stepResult.action = 'selectOption';
@@ -564,9 +586,6 @@ export async function executeStep(deps, step, options = {}) {
   return stepResult;
 }
 
-// Import executeAssert from execute-form.js
-import { executeAssert } from './execute-form.js';
-
 /**
  * Run an array of test steps
  * @param {Object} deps - Dependencies

package/{src → scripts}/runner/step-registry.js

@@ -57,7 +57,8 @@ export const STEP_TYPES = {
   READ_SITE_PROFILE: 'readSiteProfile',
   SWITCH_TAB: 'switchTab',
   GET_URL: 'getUrl',
-  GET_TITLE: 'getTitle'
+  GET_TITLE: 'getTitle',
+  UPLOAD: 'upload'
 };
 
 /**
@@ -152,7 +153,7 @@ export const STEP_CONFIG = {
           errors.push('wait hidden must be a boolean');
         }
       } else {
-        errors.push('wait requires a number (ms), selector string, or params object');
+        errors.push('wait requires a selector string or params object with selector/text/textRegex/urlContains');
       }
       return errors;
     },
@@ -309,7 +310,8 @@ export const STEP_CONFIG = {
       if (!params || typeof params !== 'object') {
         errors.push('queryAll requires an object mapping names to selectors');
       } else {
-        const entries = Object.entries(params);
+        const hookKeys = new Set(['readyWhen', 'settledWhen', 'observe', 'timeout', 'optional']);
+        const entries = Object.entries(params).filter(([name]) => !hookKeys.has(name));
         if (entries.length === 0) {
           errors.push('queryAll requires at least one query');
         }
@@ -341,13 +343,14 @@ export const STEP_CONFIG = {
     validate: (params) => {
       const errors = [];
       if (typeof params === 'string') {
-        if (!['top', 'bottom', 'up', 'down'].includes(params)) {
-          errors.push(`Invalid scroll direction: ${params}. Must be one of: top, bottom, up, down`);
+        if (params.length === 0) {
+          errors.push('scroll requires a non-empty string');
         }
+        // Accepts direction ("top","bottom","up","down"), CSS selector, or ref string
       } else if (params && typeof params === 'object') {
-        // selector, x, y, deltaX, deltaY are all valid
+        // selector, ref, x, y, deltaX, deltaY are all valid
       } else {
-        errors.push('scroll requires direction string or params object');
+        errors.push('scroll requires a direction/selector string or params object');
       }
       return errors;
     },
@@ -358,7 +361,7 @@ export const STEP_CONFIG = {
   [STEP_TYPES.CONSOLE]: {
     validate: (params) => {
       const errors = [];
-      if (params !== true && params !== false && typeof params !== 'object') {
+      if (params !== true && params !== false && (typeof params !== 'object' || params === null)) {
         errors.push('console requires true, false, or params object');
       }
       return errors;
@@ -808,6 +811,10 @@ export const STEP_CONFIG = {
       } else if (typeof params === 'object' && params !== null) {
         if (!params.refs && !params.ref) {
           errors.push('getBox requires ref or refs');
+        } else if (params.ref && typeof params.ref !== 'string') {
+          errors.push('getBox ref must be a string');
+        } else if (params.refs && !Array.isArray(params.refs)) {
+          errors.push('getBox refs must be an array');
         }
       } else {
         errors.push('getBox requires a ref string, array of refs, or options object');
@@ -1001,6 +1008,48 @@ export const STEP_CONFIG = {
     },
     isVisual: false,
     hooks: []
+  },
+
+  [STEP_TYPES.UPLOAD]: {
+    validate: (params) => {
+      const errors = [];
+      if (typeof params === 'string') {
+        // Shape 1: single file path
+        if (params.length === 0) {
+          errors.push('upload requires a non-empty file path');
+        }
+      } else if (Array.isArray(params)) {
+        // Shape 2: array of file paths
+        if (params.length === 0) {
+          errors.push('upload requires at least one file path');
+        }
+        for (const p of params) {
+          if (typeof p !== 'string' || p.length === 0) {
+            errors.push('upload file paths must be non-empty strings');
+            break;
+          }
+        }
+      } else if (params && typeof params === 'object') {
+        // Shape 3: object with selector/ref + files
+        if (!params.selector && !params.ref) {
+          errors.push('upload object requires selector or ref to target a file input');
+        }
+        if (!params.files && !params.file) {
+          errors.push('upload object requires files (array) or file (string)');
+        }
+        if (params.files && !Array.isArray(params.files)) {
+          errors.push('upload files must be an array of file path strings');
+        }
+        if (params.file && typeof params.file !== 'string') {
+          errors.push('upload file must be a string');
+        }
+      } else {
+        errors.push('upload requires a file path string, array of paths, or object with selector/ref and files');
+      }
+      return errors;
+    },
+    isVisual: true,
+    hooks: ['readyWhen', 'settledWhen', 'observe']
   }
 };
 

package/{src → scripts}/runner/step-validator.js

@@ -10,7 +10,7 @@
  * - ./step-registry.js: getAllStepTypes, getStepConfig, validateHooks
  */
 
-import { getAllStepTypes, getStepConfig, validateHooks } from './step-registry.js';
+import { getAllStepTypes, getStepConfig, validateHooks, stepSupportsHooks } from './step-registry.js';
 
 /**
  * Validate a single step definition
@@ -53,8 +53,18 @@ export function validateStepInternal(step) {
   errors.push(...stepErrors);
 
   // Validate hooks on action steps (readyWhen, settledWhen, observe)
-  const hookErrors = validateHooks(params);
-  errors.push(...hookErrors);
+  if (stepSupportsHooks(action)) {
+    const hookErrors = validateHooks(params);
+    errors.push(...hookErrors);
+  } else if (params && typeof params === 'object' && params !== null) {
+    // Reject hook keys on steps that don't support them
+    const hookKeys = ['readyWhen', 'settledWhen', 'observe'];
+    for (const key of hookKeys) {
+      if (params[key] !== undefined) {
+        errors.push(`${action} does not support the '${key}' hook`);
+      }
+    }
+  }
 
   return errors;
 }