cdp-skill 1.0.14 → 1.0.15

package/src/dom/click-executor.js

@@ -14,6 +14,7 @@
 
 import { createActionabilityChecker } from './actionability.js';
 import { createElementValidator } from './element-validator.js';
+import { createLazyResolver } from './LazyResolver.js';
 import {
   sleep,
   elementNotFoundError,
@@ -40,6 +41,7 @@ export function createClickExecutor(session, elementLocator, inputEmulator, aria
   const getFrameContext = elementLocator.getFrameContext || null;
   const actionabilityChecker = createActionabilityChecker(session);
   const elementValidator = createElementValidator(session);
+  const lazyResolver = createLazyResolver(session, { getFrameContext });
 
   /** Build Runtime.evaluate params with frame context when in an iframe. */
   function frameEvalParams(expression, returnByValue = true) {
@@ -306,27 +308,125 @@ export function createClickExecutor(session, elementLocator, inputEmulator, aria
     return { targetReceived: true };
   }
 
+  /**
+   * Browser-side lazy resolution script that always re-resolves refs from metadata.
+   * This eliminates stale element errors by never relying on cached DOM references.
+   */
+  const LAZY_RESOLVE_SCRIPT = `
+    function lazyResolveRef(ref) {
+      const meta = window.__ariaRefMeta && window.__ariaRefMeta.get(ref);
+      if (!meta) return null;
+
+      // Helper: check if candidate matches role+name from metadata
+      function matchesRoleAndName(candidate) {
+        if (!candidate || !candidate.isConnected) return false;
+        if (!meta.role) return true;
+
+        // Get element's role
+        const explicit = candidate.getAttribute('role');
+        let candidateRole = explicit ? explicit.split(/\\s+/)[0] : null;
+        if (!candidateRole) {
+          const tag = candidate.tagName.toUpperCase();
+          const implicitMap = {
+            'A': 'link', 'BUTTON': 'button', 'SELECT': 'combobox', 'TEXTAREA': 'textbox',
+            'H1': 'heading', 'H2': 'heading', 'H3': 'heading', 'H4': 'heading', 'H5': 'heading', 'H6': 'heading',
+            'NAV': 'navigation', 'MAIN': 'main', 'LI': 'listitem', 'OPTION': 'option'
+          };
+          if (tag === 'INPUT') {
+            const type = (candidate.type || 'text').toLowerCase();
+            const typeMap = { 'checkbox': 'checkbox', 'radio': 'radio', 'range': 'slider', 'number': 'spinbutton', 'search': 'searchbox' };
+            candidateRole = typeMap[type] || 'textbox';
+          } else {
+            candidateRole = implicitMap[tag] || null;
+          }
+        }
+
+        const roleMatch = !meta.role || candidateRole === meta.role;
+        if (!roleMatch) return false;
+        if (!meta.name) return true;
+
+        // Check accessible name
+        const candidateName = (
+          candidate.getAttribute('aria-label') ||
+          candidate.getAttribute('title') ||
+          candidate.getAttribute('placeholder') ||
+          (candidate.textContent || '').replace(/\\s+/g, ' ').trim().substring(0, 200) ||
+          ''
+        );
+        return candidateName.toLowerCase().includes(meta.name.toLowerCase().substring(0, 100));
+      }
+
+      // Helper: resolve through shadow DOM
+      function queryShadow(shadowHostPath, selector) {
+        let root = document;
+        for (const hostSel of shadowHostPath) {
+          try {
+            const host = root.querySelector(hostSel);
+            if (!host || !host.shadowRoot) return null;
+            root = host.shadowRoot;
+          } catch (e) { return null; }
+        }
+        try { return root.querySelector(selector); } catch (e) { return null; }
+      }
+
+      // Strategy 1: Try selector (with shadow path if applicable)
+      if (meta.selector) {
+        const hasShadow = meta.shadowHostPath && meta.shadowHostPath.length > 0;
+        const candidate = hasShadow
+          ? queryShadow(meta.shadowHostPath, meta.selector)
+          : document.querySelector(meta.selector);
+        if (matchesRoleAndName(candidate)) return candidate;
+      }
+
+      // Strategy 2: Role+name search
+      if (meta.role) {
+        const ROLE_SELECTORS = {
+          button: 'button, input[type="button"], input[type="submit"], input[type="reset"], [role="button"]',
+          textbox: 'input:not([type]), input[type="text"], input[type="email"], input[type="password"], input[type="search"], input[type="tel"], input[type="url"], textarea, [role="textbox"]',
+          checkbox: 'input[type="checkbox"], [role="checkbox"]',
+          link: 'a[href], [role="link"]',
+          heading: 'h1, h2, h3, h4, h5, h6, [role="heading"]',
+          combobox: 'select, [role="combobox"]',
+          radio: 'input[type="radio"], [role="radio"]',
+          tab: '[role="tab"]',
+          menuitem: '[role="menuitem"]',
+          option: 'option, [role="option"]',
+          slider: 'input[type="range"], [role="slider"]',
+          spinbutton: 'input[type="number"], [role="spinbutton"]',
+          searchbox: 'input[type="search"], [role="searchbox"]',
+          switch: '[role="switch"]'
+        };
+        const selectorString = ROLE_SELECTORS[meta.role] || '[role="' + meta.role + '"]';
+        const elements = document.querySelectorAll(selectorString);
+        for (const el of elements) {
+          if (matchesRoleAndName(el)) return el;
+        }
+
+        // Strategy 3: Search in shadow roots
+        const shadowHosts = document.querySelectorAll('*');
+        for (const host of shadowHosts) {
+          if (host.shadowRoot) {
+            const els = host.shadowRoot.querySelectorAll(selectorString);
+            for (const el of els) {
+              if (matchesRoleAndName(el)) return el;
+            }
+          }
+        }
+      }
+
+      return null;
+    }
+  `;
+
   async function executeJsClickOnRef(ref) {
     const result = await session.send('Runtime.evaluate', frameEvalParams(`
         (function() {
-          let el = window.__ariaRefs && window.__ariaRefs.get(${JSON.stringify(ref)});
-
-          // Re-resolve if element is missing or stale
-          if (!el || !el.isConnected) {
-            const meta = window.__ariaRefMeta && window.__ariaRefMeta.get(${JSON.stringify(ref)});
-            if (meta && meta.selector) {
-              try {
-                const candidate = document.querySelector(meta.selector);
-                if (candidate && candidate.isConnected) {
-                  el = candidate;
-                  if (window.__ariaRefs) window.__ariaRefs.set(${JSON.stringify(ref)}, el);
-                }
-              } catch (e) {}
-            }
-          }
+          ${LAZY_RESOLVE_SCRIPT}
+
+          const el = lazyResolveRef(${JSON.stringify(ref)});
 
           if (!el) {
-            return { success: false, reason: 'ref not found in __ariaRefs' };
+            return { success: false, reason: 'ref could not be resolved - element not found' };
           }
           if (!el.isConnected) {
             return { success: false, reason: 'element is no longer attached to DOM' };
@@ -502,22 +602,15 @@ export function createClickExecutor(session, elementLocator, inputEmulator, aria
     // React re-renders between mousedown and click, destroying the original DOM node.
     // pointerdown fires synchronously before any re-render.
     // Also uses document-level capture as fallback for descendant hits.
+    // LAZY RESOLUTION: Always resolve ref from metadata, never rely on cached element.
     await session.send('Runtime.evaluate', frameEvalParams(`
         (function() {
-          let el = window.__ariaRefs && window.__ariaRefs.get(${JSON.stringify(ref)});
-          if ((!el || !el.isConnected) && window.__ariaRefMeta) {
-            const meta = window.__ariaRefMeta.get(${JSON.stringify(ref)});
-            if (meta && meta.selector) {
-              try {
-                const candidate = document.querySelector(meta.selector);
-                if (candidate && candidate.isConnected) {
-                  el = candidate;
-                  if (window.__ariaRefs) window.__ariaRefs.set(${JSON.stringify(ref)}, el);
-                }
-              } catch (e) {}
-            }
-          }
+          ${LAZY_RESOLVE_SCRIPT}
+
+          const el = lazyResolveRef(${JSON.stringify(ref)});
           if (el && el.isConnected) {
+            // Store resolved element for verification phase
+            window.__clickVerifyEl = el;
             el.__clickReceived = false;
             el.__ptrHandler = () => { el.__clickReceived = true; };
             el.addEventListener('pointerdown', el.__ptrHandler, { once: true });
@@ -539,7 +632,8 @@ export function createClickExecutor(session, elementLocator, inputEmulator, aria
     try {
       verifyResult = await session.send('Runtime.evaluate', frameEvalParams(`
           (function() {
-            const el = window.__ariaRefs && window.__ariaRefs.get(${JSON.stringify(ref)});
+            const el = window.__clickVerifyEl;
+            delete window.__clickVerifyEl;
             if (!el) return { targetReceived: false, reason: 'element not found' };
             if (el.__ptrHandler) el.removeEventListener('pointerdown', el.__ptrHandler);
             if (el.__docHandler) document.removeEventListener('pointerdown', el.__docHandler, { capture: true });
@@ -565,29 +659,41 @@ export function createClickExecutor(session, elementLocator, inputEmulator, aria
   async function clickByRef(ref, jsClick = false, opts = {}) {
     const { force = false, debug = false, nativeOnly = false, waitForNavigation, navigationTimeout = 100 } = opts;
 
-    if (!ariaSnapshot) {
-      throw new Error('ariaSnapshot is required for ref-based clicks');
-    }
-
-    const refInfo = await ariaSnapshot.getElementByRef(ref);
-    if (!refInfo) {
+    // LAZY RESOLUTION: Always resolve ref from metadata, never rely on cached element
+    // This eliminates stale element errors entirely
+    const resolved = await lazyResolver.resolveRef(ref);
+    if (!resolved) {
       throw elementNotFoundError(`ref:${ref}`, 0);
     }
 
-    if (refInfo.stale) {
-      return {
-        clicked: false,
-        stale: true,
-        warning: `Element ref:${ref} is no longer attached to the DOM. Page content may have changed. Run 'snapshot' again to get fresh refs.`
-      };
-    }
+    // Get visibility info using the resolved element
+    const visibilityResult = await session.send('Runtime.callFunctionOn', {
+      objectId: resolved.objectId,
+      functionDeclaration: `function() {
+        const style = window.getComputedStyle(this);
+        const rect = this.getBoundingClientRect();
+        return {
+          isVisible: style.display !== 'none' && style.visibility !== 'hidden' && style.opacity !== '0' && rect.width > 0 && rect.height > 0,
+          box: { x: rect.x, y: rect.y, width: rect.width, height: rect.height }
+        };
+      }`,
+      returnByValue: true
+    });
+
+    const refInfo = {
+      box: visibilityResult.result?.value?.box || resolved.box,
+      isVisible: visibilityResult.result?.value?.isVisible ?? true,
+      resolvedBy: resolved.resolvedBy
+    };
 
     if (!force && refInfo.isVisible === false) {
       // Special case: hidden radio/checkbox inputs — try to click associated label
+      // LAZY RESOLUTION: Always resolve ref from metadata
       const labelResult = await session.send('Runtime.evaluate', frameEvalParams(`
         (function() {
-          const ref = ${JSON.stringify(ref)};
-          const el = window.__ariaRefs && window.__ariaRefs.get(ref);
+          ${LAZY_RESOLVE_SCRIPT}
+
+          const el = lazyResolveRef(${JSON.stringify(ref)});
           if (!el) return { found: false };
 
           const tag = el.tagName.toUpperCase();
@@ -649,20 +755,22 @@ export function createClickExecutor(session, elementLocator, inputEmulator, aria
     }
 
     // If element is outside viewport (e.g., inside an unscrolled container), scroll it into view first
+    // LAZY RESOLUTION: Always resolve ref from metadata for scroll
     const box = refInfo.box;
     if (box && (box.x < 0 || box.y < 0 || box.x + box.width > 1920 || box.y + box.height > 1080)) {
       try {
         await session.send('Runtime.evaluate', frameEvalParams(`
           (function() {
-            const el = window.__ariaRefs && window.__ariaRefs.get(${JSON.stringify(ref)});
+            ${LAZY_RESOLVE_SCRIPT}
+            const el = lazyResolveRef(${JSON.stringify(ref)});
             if (el) el.scrollIntoView({ block: 'center', inline: 'center', behavior: 'instant' });
           })()
         `, true));
         await sleep(100);
-        // Re-fetch element info after scroll
-        const updatedInfo = await ariaSnapshot.getElementByRef(ref);
-        if (updatedInfo && updatedInfo.box) {
-          refInfo.box = updatedInfo.box;
+        // Re-fetch element info after scroll using lazy resolution
+        const updatedResult = await lazyResolver.resolveRef(ref);
+        if (updatedResult && updatedResult.box) {
+          refInfo.box = updatedResult.box;
         }
       } catch {
         // Scroll failed — proceed with original coordinates
@@ -1050,12 +1158,12 @@ export function createClickExecutor(session, elementLocator, inputEmulator, aria
     const scrollUntilVisible = typeof params === 'object' && params.scrollUntilVisible === true;
     const scrollOptions = typeof params === 'object' ? params.scrollOptions : {};
 
-    // Detect if string selector looks like a versioned ref (s{N}e{M})
-    // This allows {"click": "s1e1"} to work the same as {"click": {"ref": "s1e1"}}
+    // Detect if string selector looks like a versioned ref (f{frameId}s{N}e{M})
+    // This allows {"click": "f0s1e1"} to work the same as {"click": {"ref": "f0s1e1"}}
     if (!ref && selector) {
-      if (/^s\d+e\d+$/.test(selector)) {
+      if (/^f(\d+|\[[^\]]+\])s\d+e\d+$/.test(selector)) {
         ref = selector;
-      } else if (/^ref=s\d+e\d+$/i.test(selector)) {
+      } else if (/^ref=f(\d+|\[[^\]]+\])s\d+e\d+$/i.test(selector)) {
         ref = selector.slice(4); // Remove "ref=" prefix
       }
     }

package/src/dom/fill-executor.js

@@ -16,6 +16,7 @@
 import { createActionabilityChecker } from './actionability.js';
 import { createElementValidator } from './element-validator.js';
 import { createReactInputFiller } from './react-filler.js';
+import { createLazyResolver } from './LazyResolver.js';
 import {
   sleep,
   elementNotFoundError,
@@ -44,6 +45,7 @@ export function createFillExecutor(session, elementLocator, inputEmulator, ariaS
   const actionabilityChecker = createActionabilityChecker(session);
   const elementValidator = createElementValidator(session);
   const reactInputFiller = createReactInputFiller(session);
+  const lazyResolver = createLazyResolver(session, { getFrameContext });
 
   /**
    * Build Runtime.evaluate params, injecting contextId when in an iframe.
@@ -87,36 +89,39 @@ export function createFillExecutor(session, elementLocator, inputEmulator, ariaS
   async function fillByRef(ref, value, opts = {}) {
     const { clear = true, react = false } = opts;
 
-    if (!ariaSnapshot) {
-      throw new Error('ariaSnapshot is required for ref-based fills');
-    }
-
-    const refInfo = await ariaSnapshot.getElementByRef(ref);
-    if (!refInfo) {
+    // LAZY RESOLUTION: Always resolve ref from metadata, never rely on cached element
+    // This eliminates stale element errors entirely
+    const resolved = await lazyResolver.resolveRef(ref);
+    if (!resolved) {
       throw elementNotFoundError(`ref:${ref}`, 0);
     }
 
-    if (refInfo.stale) {
-      throw new Error(`Element ref:${ref} is no longer attached to the DOM. Page content may have changed. Run 'snapshot' again to get fresh refs.`);
-    }
+    const objectId = resolved.objectId;
+
+    // Get visibility info using the resolved element
+    const visibilityResult = await session.send('Runtime.callFunctionOn', {
+      objectId,
+      functionDeclaration: `function() {
+        const style = window.getComputedStyle(this);
+        const rect = this.getBoundingClientRect();
+        return {
+          isVisible: style.display !== 'none' && style.visibility !== 'hidden' && style.opacity !== '0' && rect.width > 0 && rect.height > 0,
+          box: { x: rect.x, y: rect.y, width: rect.width, height: rect.height }
+        };
+      }`,
+      returnByValue: true
+    });
+
+    const refInfo = {
+      box: visibilityResult.result?.value?.box || resolved.box,
+      isVisible: visibilityResult.result?.value?.isVisible ?? true
+    };
 
     if (refInfo.isVisible === false) {
+      await releaseObject(session, objectId);
       throw new Error(`Element ref:${ref} exists but is not visible. It may be hidden or have zero dimensions.`);
     }
 
-    const elementResult = await session.send('Runtime.evaluate',
-      evalParams(`(function() {
-        const el = window.__ariaRefs && window.__ariaRefs.get(${JSON.stringify(ref)});
-        return el;
-      })()`, false)
-    );
-
-    if (!elementResult.result.objectId) {
-      throw elementNotFoundError(`ref:${ref}`, 0);
-    }
-
-    const objectId = elementResult.result.objectId;
-
     const editableCheck = await elementValidator.isEditable(objectId);
     if (!editableCheck.editable) {
       await releaseObject(session, objectId);
@@ -433,9 +438,9 @@ export function createFillExecutor(session, elementLocator, inputEmulator, ariaS
       throw new Error('Fill requires value');
     }
 
-    // Detect if selector looks like a versioned ref (s{N}e{M})
-    // This allows {"fill": {"selector": "s1e1", "value": "..."}} to work like {"fill": {"ref": "s1e1", "value": "..."}}
-    if (!ref && selector && /^s\d+e\d+$/.test(selector)) {
+    // Detect if selector looks like a versioned ref (f{frameId}s{N}e{M})
+    // This allows {"fill": {"selector": "f0s1e1", "value": "..."}} to work like {"fill": {"ref": "f0s1e1", "value": "..."}}
+    if (!ref && selector && /^f(\d+|\[[^\]]+\])s\d+e\d+$/.test(selector)) {
       ref = selector;
     }
 
@@ -486,8 +491,8 @@ export function createFillExecutor(session, elementLocator, inputEmulator, ariaS
 
     for (const [selector, value] of entries) {
       try {
-        // Match versioned ref format s{N}e{M}
-        const isRef = /^s\d+e\d+$/.test(selector);
+        // Match versioned ref format f{frameId}s{N}e{M}
+        const isRef = /^f(\d+|\[[^\]]+\])s\d+e\d+$/.test(selector);
 
         if (isRef) {
           await fillByRef(selector, value, { clear: true, react: useReact });

package/src/dom/index.js

@@ -76,6 +76,9 @@ export { createKeyboardExecutor } from './keyboard-executor.js';
 // Wait executor (waiting operations)
 export { createWaitExecutor } from './wait-executor.js';
 
+// Lazy resolver (stateless element resolution)
+export { createLazyResolver } from './LazyResolver.js';
+
 // ============================================================================
 // Convenience Functions
 // ============================================================================

package/src/page/page-controller.js

@@ -1035,6 +1035,51 @@ export function createPageController(cdpClient, options = {}) {
     return null;
   }
 
+  /**
+   * Get the current frame identifier for ref generation.
+   * Returns 'f0' for main frame, 'f1', 'f2', etc. for iframes by index.
+   * Uses frame name if available for better stability.
+   * @returns {Promise<string>} Frame identifier (e.g., 'f0', 'f1', 'f[frame-name]')
+   */
+  async function getFrameIdentifier() {
+    // Main frame is always f0
+    if (currentFrameId === mainFrameId || !currentFrameId) {
+      return 'f0';
+    }
+
+    // Get frame tree to find index or name
+    const { frameTree } = await cdpClient.send('Page.getFrameTree');
+
+    function findAllChildFrames(node) {
+      const frames = [];
+      if (node.childFrames) {
+        for (const child of node.childFrames) {
+          frames.push(child);
+          frames.push(...findAllChildFrames(child));
+        }
+      }
+      return frames;
+    }
+
+    const childFrames = findAllChildFrames(frameTree);
+
+    // Find current frame
+    for (let i = 0; i < childFrames.length; i++) {
+      if (childFrames[i].frame.id === currentFrameId) {
+        // Prefer name if available (more stable than index)
+        const frameName = childFrames[i].frame.name;
+        if (frameName) {
+          return `f[${frameName}]`;
+        }
+        // Fall back to index (1-based for iframes)
+        return `f${i + 1}`;
+      }
+    }
+
+    // Fallback: unknown frame, use hash of frameId
+    return `f[${currentFrameId.substring(0, 8)}]`;
+  }
+
   /**
    * Execute code in the current frame context
    * @param {string} expression - JavaScript expression
@@ -1295,6 +1340,7 @@ export function createPageController(cdpClient, options = {}) {
     getNetworkStatus,
     searchAllFrames,
     getFrameContext,
+    getFrameIdentifier,
     dispose,
     get mainFrameId() { return mainFrameId; },
     get currentFrameId() { return currentFrameId; },

package/src/runner/execute-interaction.js

@@ -75,9 +75,9 @@ export async function executeHover(elementLocator, inputEmulator, ariaSnapshot,
   const text = typeof params === 'object' ? params.text : null;
   const duration = typeof params === 'object' ? (params.duration || 0) : 0;
 
-  // Detect if string selector looks like a ref (e.g., "s1e1", "s2e12")
-  // This allows {"hover": "s1e1"} to work the same as {"hover": {"ref": "s1e1"}}
-  if (!ref && selector && /^s\d+e\d+$/.test(selector)) {
+  // Detect if string selector looks like a ref (e.g., "f0s1e1", "f[frame-top]s2e12")
+  // This allows {"hover": "f0s1e1"} to work the same as {"hover": {"ref": "f0s1e1"}}
+  if (!ref && selector && /^f(\d+|\[[^\]]+\])s\d+e\d+$/.test(selector)) {
     ref = selector;
   }
   const force = typeof params === 'object' && params.force === true;
@@ -383,8 +383,8 @@ export async function executeDrag(elementLocator, inputEmulator, pageController,
     // String - could be selector or ref
     const selectorOrRef = spec;
 
-    // Check if it looks like a ref (e.g., "s1e1", "s2e12")
-    if (/^s\d+e\d+$/.test(selectorOrRef)) {
+    // Check if it looks like a ref (e.g., "f0s1e1", "f[frame-top]s2e12")
+    if (/^f(\d+|\[[^\]]+\])s\d+e\d+$/.test(selectorOrRef)) {
       const box = await getRefBox(selectorOrRef);
       return { ...box, offsetX: 0, offsetY: 0 };
     }
@@ -400,7 +400,7 @@ export async function executeDrag(elementLocator, inputEmulator, pageController,
   // Helper to resolve selector string for JS execution
   function getSelectorExpression(spec) {
     if (typeof spec === 'string') {
-      if (/^s\d+e\d+$/.test(spec)) {
+      if (/^f(\d+|\[[^\]]+\])s\d+e\d+$/.test(spec)) {
         return `window.__ariaRefs && window.__ariaRefs.get(${JSON.stringify(spec)})`;
       }
       return `document.querySelector(${JSON.stringify(spec)})`;

package/src/runner/execute-navigation.js

@@ -121,8 +121,8 @@ export async function executeScroll(elementLocator, inputEmulator, pageControlle
         await pageController.evaluateInFrame('window.scrollBy(0, 300)');
         break;
       default:
-        // Check if it looks like a ref (e.g., "s1e1", "s2e12")
-        if (/^s\d+e\d+$/.test(params)) {
+        // Check if it looks like a ref (e.g., "f0s1e1", "f[frame-top]s2e12")
+        if (/^f(\d+|\[[^\]]+\])s\d+e\d+$/.test(params)) {
           await scrollToRef(params);
         } else {
           // Treat as selector - scroll element into view
@@ -136,7 +136,7 @@ export async function executeScroll(elementLocator, inputEmulator, pageControlle
     }
   } else if (params && typeof params === 'object') {
     // Check for ref first
-    const ref = params.ref || (params.selector && /^s\d+e\d+$/.test(params.selector) ? params.selector : null);
+    const ref = params.ref || (params.selector && /^f(\d+|\[[^\]]+\])s\d+e\d+$/.test(params.selector) ? params.selector : null);
     if (ref) {
       await scrollToRef(ref);
     } else if (params.selector) {

package/src/runner/execute-query.js

@@ -328,9 +328,10 @@ export async function executeRefAt(session, params) {
         }
       }
 
-      // Create new versioned ref: s{snapshotId}e{counter}
+      // Create new versioned ref: f{frameId}s{snapshotId}e{counter}
       window.__ariaRefCounter++;
-      const ref = 's' + window.__ariaSnapshotId + 'e' + window.__ariaRefCounter;
+      const frameId = window.__ariaFrameIdentifier || 'f0';
+      const ref = frameId + 's' + window.__ariaSnapshotId + 'e' + window.__ariaRefCounter;
       window.__ariaRefs.set(ref, el);
 
       const rect = el.getBoundingClientRect();
@@ -396,9 +397,10 @@ export async function executeElementsAt(session, coords) {
           }
         }
 
-        // Create new versioned ref: s{snapshotId}e{counter}
+        // Create new versioned ref: f{frameId}s{snapshotId}e{counter}
         window.__ariaRefCounter++;
-        const ref = 's' + window.__ariaSnapshotId + 'e' + window.__ariaRefCounter;
+        const frameId = window.__ariaFrameIdentifier || 'f0';
+        const ref = frameId + 's' + window.__ariaSnapshotId + 'e' + window.__ariaRefCounter;
         window.__ariaRefs.set(ref, el);
         return { ref, existing: false };
       }
@@ -540,9 +542,10 @@ export async function executeElementsNear(session, params) {
           }
         }
 
-        // Create new versioned ref: s{snapshotId}e{counter}
+        // Create new versioned ref: f{frameId}s{snapshotId}e{counter}
         window.__ariaRefCounter++;
-        const ref = 's' + window.__ariaSnapshotId + 'e' + window.__ariaRefCounter;
+        const frameId = window.__ariaFrameIdentifier || 'f0';
+        const ref = frameId + 's' + window.__ariaSnapshotId + 'e' + window.__ariaRefCounter;
         window.__ariaRefs.set(ref, el);
         return { ref, existing: false };
       }

package/src/runner/step-registry.js

@@ -792,16 +792,16 @@ export const STEP_CONFIG = {
     validate: (params) => {
       const errors = [];
       if (typeof params === 'string') {
-        if (!/^s\d+e\d+$/.test(params)) {
-          errors.push('getBox ref must be in format "s{N}e{M}" (e.g., "s1e1", "s2e34")');
+        if (!/^f(\d+|\[[^\]]+\])s\d+e\d+$/.test(params)) {
+          errors.push('getBox ref must be in format "f{frameId}s{N}e{M}" (e.g., "f0s1e1", "f[frame-top]s2e34")');
         }
       } else if (Array.isArray(params)) {
         if (params.length === 0) {
           errors.push('getBox refs array cannot be empty');
         }
         for (const ref of params) {
-          if (typeof ref !== 'string' || !/^s\d+e\d+$/.test(ref)) {
-            errors.push('getBox refs must be strings in format "s{N}e{M}"');
+          if (typeof ref !== 'string' || !/^f(\d+|\[[^\]]+\])s\d+e\d+$/.test(ref)) {
+            errors.push('getBox refs must be strings in format "f{frameId}s{N}e{M}"');
             break;
           }
         }

package/src/tests/Aria.test.js

@@ -820,7 +820,7 @@ describe('ARIA Module', () => {
           return {};
         });
 
-        const refInfo = await snapshot.getElementByRef('s1e1');
+        const refInfo = await snapshot.getElementByRef('f0s1e1');
 
         // Should return ref info with box, isConnected, etc
         assert.ok(refInfo);
@@ -848,7 +848,7 @@ describe('ARIA Module', () => {
           }
         }));
 
-        const refInfo = await snapshot.getElementByRef('s1e1');
+        const refInfo = await snapshot.getElementByRef('f0s1e1');
 
         // Stale refs return object with stale flag
         if (refInfo) {
@@ -988,12 +988,12 @@ describe('ARIA Module', () => {
                 tree: {
                   role: 'document',
                   children: [
-                    { role: 'button', name: 'Click me', ref: 's1e1' }
+                    { role: 'button', name: 'Click me', ref: 'f0s1e1' }
                   ]
                 },
                 yaml: 'document:\n  button: Click me [s1e1]\n',
                 refs: new Map([
-                  ['s1e1', { ref: 's1e1', role: 'button', name: 'Click me' }]
+                  ['f0s1e1', { ref: 'f0s1e1', role: 'button', name: 'Click me' }]
                 ]),
                 snapshotId: 's1'
               }
@@ -1018,7 +1018,7 @@ describe('ARIA Module', () => {
       assert.ok(result.snapshotId);
 
       // Refs should be accessible via getElementByRef
-      const refInfo = await snapshot.getElementByRef('s1e1');
+      const refInfo = await snapshot.getElementByRef('f0s1e1');
       assert.ok(refInfo === null || typeof refInfo === 'object');
     });
   });