@jackwener/opencli 1.7.5 → 1.7.6

package/dist/src/browser/target-resolver.js

@@ -1,42 +1,168 @@
 /**
  * Unified target resolver for browser actions.
  *
- * Replaces the ad-hoc 4-strategy fallback in dom-helpers.ts with a
- * principled resolution pipeline:
+ * Resolution pipeline:
  *
- * 1. Input classification: numeric → ref path, CSS-like → CSS path
- * 2. Ref path: lookup by data-opencli-ref, then verify fingerprint
- * 3. CSS path: querySelectorAll + uniqueness check
- * 4. Structured errors: stale_ref / ambiguous / not_found
+ * 1. Input classification: all-digit → numeric ref path, otherwise → CSS path.
+ *    The CSS path passes the raw string to `querySelectorAll` and lets the
+ *    browser parser decide what's valid. No frontend regex whitelist — the
+ *    goal is that any selector accepted by `browser find --css` is accepted
+ *    by the same selector on `get/click/type/select`.
+ * 2. Ref path: cascading match levels (see below), using data-opencli-ref
+ *    plus the fingerprint map populated by snapshot + find.
+ * 3. CSS path: querySelectorAll + match-count policy (see ResolveOptions)
+ * 4. Structured errors:
+ *    - numeric: not_found / stale_ref
+ *    - CSS:     invalid_selector / selector_not_found / selector_ambiguous
+ *               / selector_nth_out_of_range
  *
  * All JS is generated as strings for page.evaluate() — runs in the browser.
+ *
+ * ── Cascading stale-ref (browser-use style) ──────────────────────────
+ * Strict equality on the fingerprint rejected too many live pages — SPA
+ * re-renders swap text / role while keeping id + testId. The resolver
+ * now walks three tiers before giving up:
+ *
+ *   1. EXACT        — tag + strong id (id or testId) agree, ≤1 soft mismatch
+ *   2. STABLE       — tag + strong id agree, soft signals drifted (aria-label,
+ *                     role, text) — agent gets a warning but the action
+ *                     proceeds so dynamic pages don't stall
+ *   3. REIDENTIFIED — original ref either missing from the DOM or fully
+ *                     mismatched, but the fingerprint uniquely identifies
+ *                     a single other live element via id / testId /
+ *                     aria-label. Re-tag that element with the old ref and
+ *                     surface match_level so the caller knows we swapped.
+ *
+ * Only when all three fail do we emit `stale_ref`. Every success envelope
+ * carries `match_level` so downstream CLIs can surface the weakest tier
+ * a caller actually traversed.
  */
 /**
  * Generate JS that resolves a target to a single DOM element.
  *
  * Returns a JS expression that evaluates to:
- *   { ok: true, el: Element }                      — success (el is assigned to `__resolved`)
- *   { ok: false, code, message, hint, candidates }  — structured error
+ *   { ok: true, matches_n, match_level }            — success (el stored in `__resolved`)
+ *   { ok: false, code, message, hint, candidates, matches_n? }  — structured error
  *
- * The resolved element is stored in `__resolved` for the caller to use.
+ * `match_level` is always set on success:
+ *   - CSS path → 'exact'
+ *   - numeric ref path → whichever tier matched ('exact' / 'stable' / 'reidentified')
+ *
+ * The resolved element is stored in `window.__resolved` for downstream helpers.
  */
-export function resolveTargetJs(ref) {
+export function resolveTargetJs(ref, opts = {}) {
     const safeRef = JSON.stringify(ref);
+    const nthJs = opts.nth !== undefined ? String(opts.nth | 0) : 'null';
+    const firstOnMulti = opts.firstOnMulti === true ? 'true' : 'false';
     return `
     (() => {
       const ref = ${safeRef};
+      const nth = ${nthJs};
+      const firstOnMulti = ${firstOnMulti};
       const identity = window.__opencli_ref_identity || {};
 
       // ── Classify input ──
+      // Numeric = snapshot ref. Everything else is handed to querySelectorAll
+      // and whatever the browser parser accepts is a valid selector. No regex
+      // shortlist up front: \`find --css\` and \`get/click/type/select\` must agree
+      // on the same selector surface (see contract note at the top of this file).
       const isNumeric = /^\\d+$/.test(ref);
-      const isCssLike = !isNumeric && /^[a-zA-Z#.\\[]/.test(ref);
 
       if (isNumeric) {
-        // ── Ref path ──
+        // ── Ref path (cascading match levels) ──
+
+        // Shared helper: compute a fingerprint off a live element, same shape
+        // snapshot + find populate into \`__opencli_ref_identity\`. Kept inline
+        // (not imported) because this source string is compiled standalone.
+        function fingerprintOf(node) {
+          return {
+            tag: node.tagName.toLowerCase(),
+            role: node.getAttribute('role') || '',
+            text: (node.textContent || '').trim().slice(0, 30),
+            ariaLabel: node.getAttribute('aria-label') || '',
+            id: node.id || '',
+            testId: node.getAttribute('data-testid') || node.getAttribute('data-test') || '',
+          };
+        }
+
+        // Classify how strongly a live element matches a stored fingerprint.
+        // Returns one of 'exact' | 'stable' | 'mismatch'.
+        //
+        // 'exact'  — tag + every non-empty stored field agrees (±text prefix).
+        // 'stable' — tag agrees AND at least one strong id (id or testId) still
+        //            matches; soft signals (aria-label, role, text) may have
+        //            drifted. This covers SPA re-render / i18n label swaps.
+        // 'mismatch' otherwise.
+        function classifyMatch(fp, liveFp) {
+          if (fp.tag !== liveFp.tag) return 'mismatch';
+
+          const idMatch = !fp.id || fp.id === liveFp.id;
+          const testIdMatch = !fp.testId || fp.testId === liveFp.testId;
+          const roleMatch = !fp.role || fp.role === liveFp.role;
+          const ariaMatch = !fp.ariaLabel || fp.ariaLabel === liveFp.ariaLabel;
+          const textMatch = !fp.text || (
+            !!liveFp.text && (liveFp.text.startsWith(fp.text) || fp.text.startsWith(liveFp.text))
+          );
+
+          if (idMatch && testIdMatch && roleMatch && ariaMatch && textMatch) return 'exact';
+
+          // Strong id decides: if id + testId still agree and we had at least one
+          // of them, accept as stable regardless of soft-signal drift.
+          const hadStrongId = !!fp.id || !!fp.testId;
+          if (hadStrongId && idMatch && testIdMatch) return 'stable';
+
+          return 'mismatch';
+        }
+
+        // Try to recover a stale ref by searching the page for a live element
+        // whose fingerprint still matches. Uniqueness is required — if two
+        // candidates match equally well, we refuse rather than silently pick
+        // the wrong one. Covers ref annotations lost to a re-mount.
+        function reidentify(fp) {
+          if (!fp) return null;
+          const candidates = [];
+          function tryAdd(el) {
+            if (el && el.nodeType === 1 && classifyMatch(fp, fingerprintOf(el)) !== 'mismatch') {
+              if (candidates.indexOf(el) === -1) candidates.push(el);
+            }
+          }
+          // Prefer strong-id lookups. If id / testId is present and yields a
+          // unique element, that's our hit.
+          try {
+            if (fp.id) {
+              const byId = document.getElementById(fp.id);
+              if (byId) tryAdd(byId);
+            }
+            if (fp.testId) {
+              const byTestIdA = document.querySelectorAll('[data-testid="' + fp.testId.replace(/"/g, '\\\\"') + '"]');
+              for (let i = 0; i < byTestIdA.length; i++) tryAdd(byTestIdA[i]);
+              const byTestIdB = document.querySelectorAll('[data-test="' + fp.testId.replace(/"/g, '\\\\"') + '"]');
+              for (let i = 0; i < byTestIdB.length; i++) tryAdd(byTestIdB[i]);
+            }
+            // aria-label is only a useful shortlist when nothing stronger is set
+            if (candidates.length === 0 && fp.ariaLabel) {
+              const byAria = document.querySelectorAll('[aria-label="' + fp.ariaLabel.replace(/"/g, '\\\\"') + '"]');
+              for (let i = 0; i < byAria.length; i++) tryAdd(byAria[i]);
+            }
+          } catch (_) { /* bad selectors from weird fp values — skip */ }
+          return candidates.length === 1 ? candidates[0] : null;
+        }
+
+        const fp = identity[ref];
         let el = document.querySelector('[data-opencli-ref="' + ref + '"]');
         if (!el) el = document.querySelector('[data-ref="' + ref + '"]');
 
+        // If the ref tag is gone from the DOM, last-chance reidentify.
         if (!el) {
+          const recovered = reidentify(fp);
+          if (recovered) {
+            try {
+              recovered.setAttribute('data-opencli-ref', ref);
+              identity[ref] = fingerprintOf(recovered);
+            } catch (_) {}
+            window.__resolved = recovered;
+            return { ok: true, matches_n: 1, match_level: 'reidentified' };
+          }
           return {
             ok: false,
             code: 'not_found',
@@ -45,68 +171,53 @@ export function resolveTargetJs(ref) {
           };
         }
 
-        // ── Fingerprint verification (identity vector) ──
-        const fp = identity[ref];
-        if (fp) {
-          const tag = el.tagName.toLowerCase();
-          const text = (el.textContent || '').trim().slice(0, 30);
-          const role = el.getAttribute('role') || '';
-          const ariaLabel = el.getAttribute('aria-label') || '';
-          const id = el.id || '';
-          const testId = el.getAttribute('data-testid') || el.getAttribute('data-test') || '';
-
-          // Hard fail: tag must always match
-          const tagMatch = fp.tag === tag;
+        // No stored fingerprint (older page / unknown ref) — accept as exact.
+        if (!fp) {
+          window.__resolved = el;
+          return { ok: true, matches_n: 1, match_level: 'exact' };
+        }
 
-          // Soft signals: each non-empty stored field that mismatches counts against
-          var mismatches = 0;
-          var checks = 0;
-          if (fp.id) { checks++; if (fp.id !== id) mismatches++; }
-          if (fp.testId) { checks++; if (fp.testId !== testId) mismatches++; }
-          if (fp.ariaLabel) { checks++; if (fp.ariaLabel !== ariaLabel) mismatches++; }
-          if (fp.role) { checks++; if (fp.role !== role) mismatches++; }
-          if (fp.text) {
-            checks++;
-            // Text: allow prefix match (page text can grow), but empty current text never matches
-            if (!text || (!text.startsWith(fp.text) && !fp.text.startsWith(text))) mismatches++;
-          }
+        const liveFp = fingerprintOf(el);
+        const level = classifyMatch(fp, liveFp);
 
-          // Stale if tag changed, or if any uniquely identifying field (id/testId) changed,
-          // or if majority of soft signals mismatch
-          var isStale = !tagMatch;
-          if (!isStale && checks > 0) {
-            // id and testId are strong identifiers — any mismatch on these is decisive
-            if (fp.id && fp.id !== id) isStale = true;
-            else if (fp.testId && fp.testId !== testId) isStale = true;
-            // For remaining signals, stale if more than half mismatch
-            else if (mismatches > checks / 2) isStale = true;
-          }
+        if (level === 'exact' || level === 'stable') {
+          window.__resolved = el;
+          return { ok: true, matches_n: 1, match_level: level };
+        }
 
-          if (isStale) {
-            return {
-              ok: false,
-              code: 'stale_ref',
-              message: 'ref=' + ref + ' was <' + fp.tag + '>' + (fp.text ? '"' + fp.text + '"' : '')
-                + ' but now points to <' + tag + '>' + (text ? '"' + text.slice(0, 30) + '"' : ''),
-              hint: 'The page has changed since the last snapshot. Re-run \`opencli browser state\` to refresh.',
-            };
-          }
+        // Tag / strong-id mismatch — try to find the real element elsewhere
+        // before giving up. Covers e.g. a modal re-mount that discarded the
+        // data-opencli-ref attribute on the surviving node.
+        const recovered = reidentify(fp);
+        if (recovered && recovered !== el) {
+          try {
+            el.removeAttribute('data-opencli-ref');
+            recovered.setAttribute('data-opencli-ref', ref);
+            identity[ref] = fingerprintOf(recovered);
+          } catch (_) {}
+          window.__resolved = recovered;
+          return { ok: true, matches_n: 1, match_level: 'reidentified' };
         }
 
-        window.__resolved = el;
-        return { ok: true };
+        return {
+          ok: false,
+          code: 'stale_ref',
+          message: 'ref=' + ref + ' was <' + fp.tag + '>' + (fp.text ? '"' + fp.text + '"' : '')
+            + ' but now points to <' + liveFp.tag + '>' + (liveFp.text ? '"' + liveFp.text.slice(0, 30) + '"' : ''),
+          hint: 'The page has changed since the last snapshot. Re-run \`opencli browser state\` to refresh.',
+        };
       }
 
-      if (isCssLike) {
-        // ── CSS selector path ──
+      // ── CSS selector path (any non-numeric input) ──
+      {
         let matches;
         try {
           matches = document.querySelectorAll(ref);
         } catch (e) {
           return {
             ok: false,
-            code: 'not_found',
-            message: 'Invalid CSS selector: ' + ref,
+            code: 'invalid_selector',
+            message: 'Invalid CSS selector: ' + ref + ' (' + ((e && e.message) || String(e)) + ')',
             hint: 'Check the selector syntax. Use ref numbers from snapshot for reliable targeting.',
           };
         }
@@ -114,13 +225,28 @@ export function resolveTargetJs(ref) {
         if (matches.length === 0) {
           return {
             ok: false,
-            code: 'not_found',
+            code: 'selector_not_found',
             message: 'CSS selector "' + ref + '" matched 0 elements',
-            hint: 'The element may not exist or may be hidden. Re-run \`opencli browser state\` to check.',
+            hint: 'The element may not exist or may be hidden. Re-run \`opencli browser state\` to check, or use \`opencli browser find --css\` to explore candidates.',
+            matches_n: 0,
           };
         }
 
-        if (matches.length > 1) {
+        if (nth !== null) {
+          if (nth < 0 || nth >= matches.length) {
+            return {
+              ok: false,
+              code: 'selector_nth_out_of_range',
+              message: 'CSS selector "' + ref + '" matched ' + matches.length + ' elements, but --nth=' + nth + ' is out of range',
+              hint: 'Use --nth between 0 and ' + (matches.length - 1) + ', or omit --nth to target the first match (read ops) or require explicit disambiguation (write ops).',
+              matches_n: matches.length,
+            };
+          }
+          window.__resolved = matches[nth];
+          return { ok: true, matches_n: matches.length, match_level: 'exact' };
+        }
+
+        if (matches.length > 1 && !firstOnMulti) {
           const candidates = [];
           const limit = Math.min(matches.length, 5);
           for (let i = 0; i < limit; i++) {
@@ -132,24 +258,18 @@ export function resolveTargetJs(ref) {
           }
           return {
             ok: false,
-            code: 'ambiguous',
+            code: 'selector_ambiguous',
             message: 'CSS selector "' + ref + '" matched ' + matches.length + ' elements',
-            hint: 'Use a more specific selector, or use ref numbers from \`opencli browser state\` snapshot.',
+            hint: 'Pass --nth <n> (0-based) to pick one, or use a more specific selector. Use \`opencli browser find --css\` to list all candidates.',
             candidates: candidates,
+            matches_n: matches.length,
           };
         }
 
+        // Single match, OR multi-match with firstOnMulti (read path)
         window.__resolved = matches[0];
-        return { ok: true };
+        return { ok: true, matches_n: matches.length, match_level: 'exact' };
       }
-
-      // ── Unrecognized input ──
-      return {
-        ok: false,
-        code: 'not_found',
-        message: 'Cannot parse target: ' + ref,
-        hint: 'Use a numeric ref from snapshot (e.g. "12") or a CSS selector (e.g. "#submit").',
-      };
     })()
   `;
 }

package/dist/src/browser/target-resolver.test.js

@@ -26,13 +26,37 @@ describe('resolveTargetJs', () => {
     });
     it('generates JS with ambiguity detection for CSS selectors', () => {
         const js = resolveTargetJs('.btn');
-        expect(js).toContain('ambiguous');
+        expect(js).toContain('selector_ambiguous');
         expect(js).toContain('candidates');
     });
-    it('generates JS that rejects unrecognized input', () => {
-        const js = resolveTargetJs('???');
-        expect(js).toContain('not_found');
-        expect(js).toContain('Cannot parse target');
+    it('generates JS that propagates --nth option into the CSS branch', () => {
+        const js = resolveTargetJs('.btn', { nth: 2 });
+        expect(js).toContain('selector_nth_out_of_range');
+        // opt.nth=2 should be inlined so the runtime picks matches[2]
+        expect(js).toMatch(/const nth = 2;?/);
+    });
+    it('generates JS that enables firstOnMulti for read commands', () => {
+        const js = resolveTargetJs('.btn', { firstOnMulti: true });
+        expect(js).toContain('firstOnMulti = true');
+    });
+    it('generates JS with invalid_selector branch for CSS syntax errors', () => {
+        const js = resolveTargetJs('.btn');
+        expect(js).toContain('invalid_selector');
+    });
+    it('generates JS with selector_not_found branch for 0 matches', () => {
+        const js = resolveTargetJs('#does-not-exist');
+        expect(js).toContain('selector_not_found');
+    });
+    it('hands every non-numeric input to querySelectorAll (no regex shortlist)', () => {
+        // Inputs that the old isCssLike regex rejected — must all flow into the
+        // CSS branch so `find --css` and `get/click/type/select` accept the same surface.
+        for (const sel of [':root', '*', ':has(.foo)', '::shadow-root', '???']) {
+            const js = resolveTargetJs(sel);
+            expect(js).toContain('querySelectorAll');
+            // invalid selectors still route through invalid_selector at runtime,
+            // never through a frontend "Cannot parse target" rejection.
+            expect(js).not.toContain('Cannot parse target');
+        }
     });
     it('escapes ref value safely', () => {
         const js = resolveTargetJs('"; alert(1); "');
@@ -40,4 +64,55 @@ describe('resolveTargetJs', () => {
         expect(js).not.toContain('alert(1); "');
         expect(js).toContain('\\"');
     });
+    it('tags every success envelope with match_level so agents can tell tiers apart', () => {
+        const numericJs = resolveTargetJs('7');
+        const cssJs = resolveTargetJs('.btn');
+        // Exact / reidentified emit the literal directly; stable flows through the
+        // classifier's `level` variable. All three strings must appear in the JS.
+        expect(numericJs).toContain("match_level: 'exact'");
+        expect(numericJs).toContain("match_level: 'reidentified'");
+        expect(numericJs).toContain("return 'stable'");
+        // Stable + exact share the same emit site (match_level: level) — make sure
+        // we didn't hardcode one of them and drop the other.
+        expect(numericJs).toContain('match_level: level');
+        // CSS path is always exact (selector ran successfully).
+        expect(cssJs).toContain("match_level: 'exact'");
+    });
+    it('cascading ref path — classifier + reidentifier are both wired in', () => {
+        const js = resolveTargetJs('3');
+        // Classifier distinguishes the three tiers
+        expect(js).toContain('function classifyMatch');
+        expect(js).toContain("return 'exact'");
+        expect(js).toContain("return 'stable'");
+        expect(js).toContain("return 'mismatch'");
+        // Strong id is the only thing that can rescue a drifted fingerprint
+        expect(js).toContain('hadStrongId');
+        // Reidentify searches live DOM with the same fingerprint shape the
+        // snapshot / find writers emit — id / testId / aria-label only.
+        expect(js).toContain('function reidentify');
+        expect(js).toContain('getElementById');
+        expect(js).toContain('[data-testid="');
+        expect(js).toContain('[aria-label="');
+        // Unique match required — never silently picks one of many candidates.
+        expect(js).toContain('candidates.length === 1');
+        // Recovered element is re-tagged + identity map refreshed so subsequent
+        // resolves land on 'exact' instead of re-walking the cascade.
+        expect(js).toContain("setAttribute('data-opencli-ref', ref)");
+        expect(js).toContain('identity[ref] = fingerprintOf(recovered)');
+    });
+    it('reidentify runs both when data-opencli-ref is missing AND when fingerprint is mismatched', () => {
+        const js = resolveTargetJs('9');
+        // Two call sites: one in the !el branch, one after classifyMatch returns mismatch.
+        const count = js.split('reidentify(fp)').length - 1;
+        expect(count).toBeGreaterThanOrEqual(2);
+    });
+    it('falls through to stale_ref only after reidentify exhausts', () => {
+        const js = resolveTargetJs('4');
+        // The stale_ref emit must sit *below* a reidentify attempt so the cascade
+        // is what produces the error — not the original strict check.
+        const reidentifyIdx = js.indexOf('const recovered = reidentify(fp);');
+        const staleIdx = js.indexOf("code: 'stale_ref'");
+        expect(reidentifyIdx).toBeGreaterThan(-1);
+        expect(staleIdx).toBeGreaterThan(reidentifyIdx);
+    });
 });