teamshare-bridge 0.26.14 → 0.26.17

package/dist/lib/browser/refs.js

@@ -0,0 +1,430 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_REFS = void 0;
+exports.buildRefScanScript = buildRefScanScript;
+exports.formatRefs = formatRefs;
+exports.scanRefs = scanRefs;
+exports.buildRefInfoScript = buildRefInfoScript;
+exports.buildRefFocusScript = buildRefFocusScript;
+exports.buildRefPointerScript = buildRefPointerScript;
+exports.buildAnnotateScript = buildAnnotateScript;
+exports.buildClearAnnotationScript = buildClearAnnotationScript;
+exports.buildPopoverCountScript = buildPopoverCountScript;
+exports.buildOutsidePointerScript = buildOutsidePointerScript;
+/**
+ * Element references for the debug/MCP browser (2026-10).
+ *
+ * WHY THIS EXISTS: the QA agent used to identify controls with raw CSS
+ * selectors, `getElements` indexes or x/y coordinates. On TeamShare's own
+ * shadcn/Radix UI that failed constantly: a dropdown, popover or kebab menu
+ * renders into a PORTAL at the end of `<body>`, the selector the model guessed
+ * matched nothing, and a coordinate read from a screenshot was device-scale.
+ * Most of a QA run was spent re-guessing selectors.
+ *
+ * A ref is a short opaque handle (`e1`, `e2`, ...) minted by ONE in-page scan:
+ *
+ *  - the scanner walks every interactive element in the document, INCLUDING
+ *    portalled menus/popovers/dialogs (they are still in the DOM, just not
+ *    where the markup suggests), filters to what is actually visible, and
+ *    records role/name/coords plus a direct reference to the live node in
+ *    `window.__tsRefs.nodes`;
+ *  - actions resolve a ref to the live node first and its centre point second,
+ *    so an action is never sent to a coordinate that a re-render invalidated;
+ *  - the live node is checked with `isConnected` before every use. A dead ref
+ *    is refused with `REF_STALE` AND, when a unique same-role/same-name match
+ *    exists in the fresh scan, transparently re-pointed at it.
+ *
+ * A ref list is invalidated by navigating or by a re-render, exactly like a
+ * Playwright locator; the session keeps the last list so it can explain what
+ * happened instead of failing mute.
+ *
+ * The scan deliberately runs in the page (one `Runtime.evaluate`) instead of
+ * joining `Accessibility.getFullAXTree` with `DOMSnapshot.captureSnapshot`:
+ * the DOM scan gives portal content AND geometry in one round trip, and it is
+ * the same document the actions operate on. Roles/names are computed from the
+ * explicit ARIA attributes first, then the implicit HTML semantics.
+ */
+const cdp_1 = require("./cdp");
+/** Hard cap on refs per scan: keeps the tool result readable and bounded. */
+exports.MAX_REFS = 300;
+/** Elements that can be interacted with (and are useful to name). */
+const REF_SELECTOR = [
+    'a[href]',
+    'button',
+    'input:not([type="hidden"])',
+    'select',
+    'textarea',
+    'summary',
+    '[role="button"]',
+    '[role="link"]',
+    '[role="menuitem"]',
+    '[role="menuitemcheckbox"]',
+    '[role="menuitemradio"]',
+    '[role="option"]',
+    '[role="tab"]',
+    '[role="checkbox"]',
+    '[role="radio"]',
+    '[role="switch"]',
+    '[role="combobox"]',
+    '[role="textbox"]',
+    '[contenteditable="true"]',
+    '[tabindex]:not([tabindex="-1"])',
+].join(',');
+/**
+ * The one scan. Returns `{ at, list }` and stores the live nodes on
+ * `window.__tsRefs.nodes` for later `isConnected` checks / focus calls.
+ */
+function buildRefScanScript() {
+    return `
+    (() => {
+      const MAX = ${exports.MAX_REFS};
+      const SEL = ${JSON.stringify(REF_SELECTOR)};
+      const PORTAL_SEL = '[data-radix-popper-content-wrapper],[data-radix-portal],[data-floating-ui-portal]';
+      const DIALOG_SEL = 'dialog[open],[role="dialog"],[aria-modal="true"]';
+      const vis = (el) => {
+        if (!el || el.nodeType !== 1) return false;
+        const r = el.getBoundingClientRect();
+        if (r.width === 0 || r.height === 0) return false;
+        const cs = getComputedStyle(el);
+        if (cs.visibility === 'hidden' || cs.display === 'none' || cs.opacity === '0') return false;
+        if (cs.pointerEvents === 'none') return false;
+        return true;
+      };
+      const clean = (v, cap) => String(v == null ? '' : v)
+        .replace(/\\s+/g, ' ')
+        .trim()
+        .slice(0, cap || 80);
+      const nameOf = (el) => {
+        const aria = el.getAttribute('aria-label');
+        if (aria) return clean(aria, 80);
+        const by = el.getAttribute('aria-labelledby');
+        if (by) {
+          const t = by.split(/\\s+/).map((id) => {
+            const n = document.getElementById(id);
+            return n ? (n.innerText || n.textContent || '') : '';
+          }).join(' ');
+          if (t.trim()) return clean(t, 80);
+        }
+        const tag = String(el.tagName || '').toLowerCase();
+        if (tag === 'input' || tag === 'textarea' || tag === 'select') {
+          const id = el.id;
+          if (id) {
+            try {
+              const l = document.querySelector('label[for="' + CSS.escape(id) + '"]');
+              if (l) return clean(l.innerText || l.textContent, 80);
+            } catch (e) {}
+          }
+          const wrap = el.closest && el.closest('label');
+          if (wrap) return clean(wrap.innerText || wrap.textContent, 80);
+          const ph = el.getAttribute('placeholder');
+          if (ph) return clean(ph, 80);
+          const nm = el.getAttribute('name');
+          if (nm) return clean(nm, 80);
+          if (el.id) return clean(el.id, 80);
+        }
+        const txt = el.innerText || el.textContent || '';
+        if (txt.trim()) return clean(txt, 80);
+        return clean(
+          el.getAttribute('title') ||
+          el.getAttribute('alt') ||
+          el.getAttribute('value') ||
+          '',
+          80,
+        );
+      };
+      const roleOf = (el) => {
+        const explicit = el.getAttribute('role');
+        if (explicit) return clean(explicit, 24);
+        const tag = String(el.tagName || '').toLowerCase();
+        const type = String(el.type || '').toLowerCase();
+        if (tag === 'a') return 'link';
+        if (tag === 'button' || tag === 'summary') return 'button';
+        if (tag === 'select') return 'combobox';
+        if (tag === 'textarea') return 'textbox';
+        if (tag === 'input') {
+          if (type === 'submit' || type === 'button' || type === 'reset') return 'button';
+          if (type === 'checkbox') return 'checkbox';
+          if (type === 'radio') return 'radio';
+          if (type === 'search') return 'searchbox';
+          return 'textbox';
+        }
+        if (el.isContentEditable === true) return 'textbox';
+        return tag || 'element';
+      };
+      const seen = new Set();
+      const nodes = {};
+      const list = [];
+      const all = [...document.querySelectorAll(SEL)];
+      for (const el of all) {
+        if (list.length >= MAX) break;
+        if (seen.has(el)) continue;
+        seen.add(el);
+        // Skip an element wholly covered by another candidate we already took
+        // only when it IS that element - nested buttons are real (icon spans
+        // are not in the selector, so this is only a dedupe guard).
+        if (!vis(el)) continue;
+        const r = el.getBoundingClientRect();
+        const ref = 'e' + (list.length + 1);
+        const row = {
+          ref,
+          tag: clean(String(el.tagName || '').toLowerCase(), 20) || 'element',
+          role: roleOf(el),
+          name: nameOf(el),
+          disabled:
+            el.disabled === true || el.getAttribute('aria-disabled') === 'true',
+          inDialog: !!(el.closest && el.closest(DIALOG_SEL)),
+          inPortal: !!(el.closest && el.closest(PORTAL_SEL)),
+          x: Math.round(r.x + r.width / 2),
+          y: Math.round(r.y + r.height / 2),
+          width: Math.round(r.width),
+          height: Math.round(r.height),
+        };
+        if (
+          (row.tag === 'input' || row.tag === 'textarea') &&
+          typeof el.value === 'string'
+        ) {
+          row.valueLength = el.value.length;
+        }
+        nodes[ref] = el;
+        list.push(row);
+      }
+      window.__tsRefs = { at: Date.now(), list, nodes };
+      return { at: window.__tsRefs.at, list };
+    })()
+  `;
+}
+/**
+ * Human/LLM-readable ref lines. One line per element:
+ * `e7  button "Publish draft" (640,412) [in menu]`
+ */
+function formatRefs(list, maxLines = 300) {
+    return list.slice(0, maxLines).map((r) => {
+        const parts = [r.ref, r.role];
+        if (r.name)
+            parts.push(JSON.stringify(r.name.slice(0, 80)));
+        if (r.valueLength !== undefined)
+            parts.push(`${r.valueLength} chars`);
+        parts.push(`(${r.x},${r.y})`);
+        if (r.disabled)
+            parts.push('[disabled]');
+        if (r.inDialog)
+            parts.push('[in dialog]');
+        if (r.inPortal)
+            parts.push('[in menu/popover]');
+        return parts.join(' ');
+    });
+}
+/** Run a fresh scan and return it (the caller keeps the list). */
+async function scanRefs(page) {
+    const raw = await (0, cdp_1.evaluateJs)(page, buildRefScanScript());
+    if (!raw || typeof raw !== 'object')
+        return { at: 0, list: [] };
+    const rec = raw;
+    return {
+        at: typeof rec.at === 'number' ? rec.at : 0,
+        list: Array.isArray(rec.list) ? rec.list : [],
+    };
+}
+/** Liveness + geometry of one ref, from the node the scan stored. */
+function buildRefInfoScript(ref) {
+    const id = JSON.stringify(ref);
+    return `(() => {
+    const s = window.__tsRefs;
+    const el = s && s.nodes ? s.nodes[${id}] : null;
+    if (!el || el.isConnected !== true) return { ref: ${id}, alive: false };
+    const r = el.getBoundingClientRect();
+    return {
+      ref: ${id},
+      alive: true,
+      x: Math.round(r.x + r.width / 2),
+      y: Math.round(r.y + r.height / 2),
+      width: Math.round(r.width),
+      height: Math.round(r.height),
+      inViewport:
+        r.top >= 0 && r.left >= 0 &&
+        r.bottom <= (window.innerHeight || 0) && r.right <= (window.innerWidth || 0),
+    };
+  })()`;
+}
+/**
+ * Focus a ref'd element, scrolling it to the middle first. Returns whether the
+ * element actually took focus plus its tag/role, so `focus` is never a silent
+ * no-op: a div without `tabindex` cannot be focused and says so.
+ */
+function buildRefFocusScript(ref) {
+    const id = JSON.stringify(ref);
+    return `(() => {
+    const s = window.__tsRefs;
+    const el = s && s.nodes ? s.nodes[${id}] : null;
+    if (!el || el.isConnected !== true) return { ref: ${id}, ok: false, alive: false };
+    try { el.scrollIntoView({ block: 'center', inline: 'center' }); } catch (e) {}
+    try { el.focus({ preventScroll: true }); } catch (e) {}
+    const a = document.activeElement;
+    return {
+      ref: ${id},
+      ok: a === el,
+      alive: true,
+      focused: a === el,
+      tag: String((el.tagName || '')).toLowerCase(),
+      contentEditable: el.isContentEditable === true,
+      valueLength: typeof el.value === 'string' ? el.value.length : undefined,
+    };
+  })()`;
+}
+/**
+ * Dispatch the FULL pointer sequence on a ref'd element, in-page.
+ *
+ * This is the fallback for controls that ignore a coordinate click: the
+ * frontend tours (`frontend/src/modules/tour/utils/acts.ts`) taught us that a
+ * bare `.click()` is a SILENT no-op on Radix tabs/menus, which activate on
+ * `pointerdown`/`mousedown`. Same recipe, one copy per side of the wire.
+ */
+function buildRefPointerScript(ref) {
+    const id = JSON.stringify(ref);
+    return `(() => {
+    const s = window.__tsRefs;
+    const el = s && s.nodes ? s.nodes[${id}] : null;
+    if (!el || el.isConnected !== true) return { ref: ${id}, ok: false, alive: false };
+    try { el.scrollIntoView({ block: 'center', inline: 'center' }); } catch (e) {}
+    const rect = el.getBoundingClientRect();
+    const x = Math.round(rect.x + rect.width / 2);
+    const y = Math.round(rect.y + rect.height / 2);
+    const base = {
+      bubbles: true,
+      cancelable: true,
+      composed: true,
+      clientX: x,
+      clientY: y,
+      view: window,
+      button: 0,
+      buttons: 1,
+    };
+    const pointer = (type) => {
+      try {
+        return new PointerEvent(type, Object.assign({}, base, {
+          pointerId: 1,
+          pointerType: 'mouse',
+          isPrimary: true,
+        }));
+      } catch (e) {
+        return new MouseEvent(type, base);
+      }
+    };
+    const mouse = (type) => new MouseEvent(type, base);
+    el.dispatchEvent(pointer('pointerover'));
+    el.dispatchEvent(pointer('pointerenter'));
+    el.dispatchEvent(pointer('pointermove'));
+    el.dispatchEvent(pointer('pointerdown'));
+    el.dispatchEvent(mouse('mousedown'));
+    try { el.focus({ preventScroll: true }); } catch (e) {}
+    el.dispatchEvent(pointer('pointerup'));
+    el.dispatchEvent(mouse('mouseup'));
+    el.dispatchEvent(mouse('click'));
+    return { ref: ${id}, ok: true, alive: true, clicked: true, x, y };
+  })()`;
+}
+/**
+ * Draw ref labels over the live page (2026-10).
+ *
+ * A plain screenshot shows WHAT is on screen; the model still has to guess
+ * which button is `e7`. The overlay draws a numbered box on every ref'd
+ * element so ONE image both shows the page and names the targets. Removed
+ * immediately after the capture - the page is never left modified.
+ */
+function buildAnnotateScript() {
+    return `(() => {
+    const s = window.__tsRefs;
+    if (!s || !s.list) return 0;
+    const ID = 'ts-ref-overlay';
+    const old = document.getElementById(ID);
+    if (old) old.remove();
+    const root = document.createElement('div');
+    root.id = ID;
+    root.style.cssText = 'position:fixed;left:0;top:0;width:0;height:0;z-index:2147483647;pointer-events:none;';
+    let n = 0;
+    for (const item of s.list) {
+      const el = s.nodes ? s.nodes[item.ref] : null;
+      if (!el || el.isConnected !== true) continue;
+      const r = el.getBoundingClientRect();
+      if (r.width === 0 || r.height === 0) continue;
+      const box = document.createElement('div');
+      box.style.cssText =
+        'position:fixed;border:2px solid #e11d48;border-radius:3px;box-sizing:border-box;pointer-events:none;left:' +
+        Math.round(r.left) + 'px;top:' + Math.round(r.top) + 'px;width:' + Math.round(r.width) +
+        'px;height:' + Math.round(r.height) + 'px;';
+      const tag = document.createElement('div');
+      tag.textContent = item.ref;
+      tag.style.cssText =
+        'position:fixed;background:#e11d48;color:#ffffff;font:600 11px/1.2 sans-serif;padding:1px 3px;border-radius:2px;pointer-events:none;left:' +
+        Math.round(r.left) + 'px;top:' + Math.max(0, Math.round(r.top) - 14) + 'px;';
+      root.appendChild(box);
+      root.appendChild(tag);
+      if (++n >= 120) break;
+    }
+    document.documentElement.appendChild(root);
+    return n;
+  })()`;
+}
+/** Remove the ref overlay (always called, even when the capture failed). */
+function buildClearAnnotationScript() {
+    return `(() => {
+    const el = document.getElementById('ts-ref-overlay');
+    if (el) el.remove();
+    return true;
+  })()`;
+}
+/** How many popovers/menus are currently open (used by closePopup). */
+function buildPopoverCountScript() {
+    return `(() => {
+    const vis = (el) => {
+      if (!el || el.nodeType !== 1) return false;
+      const r = el.getBoundingClientRect();
+      if (r.width === 0 || r.height === 0) return false;
+      const cs = getComputedStyle(el);
+      return cs.visibility !== 'hidden' && cs.display !== 'none' && cs.opacity !== '0';
+    };
+    const n = [...document.querySelectorAll('[data-radix-popper-content-wrapper],[role="menu"],[role="listbox"]')]
+      .filter(vis).length;
+    return n;
+  })()`;
+}
+/**
+ * Click OUTSIDE every open layer (the Radix DismissableLayer listens for a
+ * document-level `pointerdown`). Coordinate clicks can land on something
+ * dangerous in a corner, so this dispatches the pointer sequence on `<body>`
+ * at the layer's own outside point instead.
+ */
+function buildOutsidePointerScript() {
+    return `(() => {
+    const target = document.body;
+    if (!target) return false;
+    const base = {
+      bubbles: true,
+      cancelable: true,
+      composed: true,
+      clientX: 4,
+      clientY: 4,
+      view: window,
+      button: 0,
+      buttons: 1,
+    };
+    const pointer = (type) => {
+      try {
+        return new PointerEvent(type, Object.assign({}, base, {
+          pointerId: 1,
+          pointerType: 'mouse',
+          isPrimary: true,
+        }));
+      } catch (e) {
+        return new MouseEvent(type, base);
+      }
+    };
+    target.dispatchEvent(pointer('pointerdown'));
+    target.dispatchEvent(new MouseEvent('mousedown', base));
+    target.dispatchEvent(pointer('pointerup'));
+    target.dispatchEvent(new MouseEvent('mouseup', base));
+    target.dispatchEvent(new MouseEvent('click', base));
+    return true;
+  })()`;
+}
+//# sourceMappingURL=refs.js.map

package/dist/lib/browser/refs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refs.js","sourceRoot":"","sources":["../../../src/lib/browser/refs.ts"],"names":[],"mappings":";;;AAmFA,gDAsHC;AAMD,gCAWC;AAGD,4BAUC;AAGD,gDAmBC;AAOD,kDAmBC;AAUD,sDA2CC;AAUD,kDAiCC;AAGD,gEAMC;AAGD,0DAaC;AAQD,8DAgCC;AAxbD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,+BAAiD;AAmBjD,6EAA6E;AAChE,QAAA,QAAQ,GAAG,GAAG,CAAC;AAE5B,qEAAqE;AACrE,MAAM,YAAY,GAAG;IACnB,SAAS;IACT,QAAQ;IACR,4BAA4B;IAC5B,QAAQ;IACR,UAAU;IACV,SAAS;IACT,iBAAiB;IACjB,eAAe;IACf,mBAAmB;IACnB,2BAA2B;IAC3B,wBAAwB;IACxB,iBAAiB;IACjB,cAAc;IACd,mBAAmB;IACnB,gBAAgB;IAChB,iBAAiB;IACjB,mBAAmB;IACnB,kBAAkB;IAClB,0BAA0B;IAC1B,iCAAiC;CAClC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAEZ;;;GAGG;AACH,SAAgB,kBAAkB;IAChC,OAAO;;oBAEW,gBAAQ;oBACR,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiH7C,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,SAAgB,UAAU,CAAC,IAAkB,EAAE,QAAQ,GAAG,GAAG;IAC3D,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QACvC,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;QAC9B,IAAI,CAAC,CAAC,IAAI;YAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;QAC5D,IAAI,CAAC,CAAC,WAAW,KAAK,SAAS;YAAE,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,WAAW,QAAQ,CAAC,CAAC;QACtE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QAC9B,IAAI,CAAC,CAAC,QAAQ;YAAE,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QACzC,IAAI,CAAC,CAAC,QAAQ;YAAE,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QAC1C,IAAI,CAAC,CAAC,QAAQ;YAAE,KAAK,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;QAChD,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACzB,CAAC,CAAC,CAAC;AACL,CAAC;AAED,kEAAkE;AAC3D,KAAK,UAAU,QAAQ,CAC5B,IAAa;IAEb,MAAM,GAAG,GAAG,MAAM,IAAA,gBAAU,EAAC,IAAI,EAAE,kBAAkB,EAAE,CAAC,CAAC;IACzD,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,EAAE,EAAE,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;IAChE,MAAM,GAAG,GAAG,GAAsC,CAAC;IACnD,OAAO;QACL,EAAE,EAAE,OAAO,GAAG,CAAC,EAAE,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QAC3C,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAE,GAAG,CAAC,IAAqB,CAAC,CAAC,CAAC,EAAE;KAChE,CAAC;AACJ,CAAC;AAED,qEAAqE;AACrE,SAAgB,kBAAkB,CAAC,GAAW;IAC5C,MAAM,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IAC/B,OAAO;;wCAE+B,EAAE;wDACc,EAAE;;;aAG7C,EAAE;;;;;;;;;;OAUR,CAAC;AACR,CAAC;AAED;;;;GAIG;AACH,SAAgB,mBAAmB,CAAC,GAAW;IAC7C,MAAM,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IAC/B,OAAO;;wCAE+B,EAAE;wDACc,EAAE;;;;;aAK7C,EAAE;;;;;;;;OAQR,CAAC;AACR,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,qBAAqB,CAAC,GAAW;IAC/C,MAAM,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IAC/B,OAAO;;wCAE+B,EAAE;wDACc,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBAoCtC,EAAE;OACf,CAAC;AACR,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,mBAAmB;IACjC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BF,CAAC;AACR,CAAC;AAED,4EAA4E;AAC5E,SAAgB,0BAA0B;IACxC,OAAO;;;;OAIF,CAAC;AACR,CAAC;AAED,uEAAuE;AACvE,SAAgB,uBAAuB;IACrC,OAAO;;;;;;;;;;;OAWF,CAAC;AACR,CAAC;AAED;;;;;GAKG;AACH,SAAgB,yBAAyB;IACvC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BF,CAAC;AACR,CAAC"}

package/dist/lib/browser/session.d.ts

@@ -1,9 +1,10 @@
 import type { CdpPage, ElementInfo, PageInfo, PageText, PageLink } from './cdp';
 import { type NetworkEntry, type ConsoleEntry, type WebSocketFrame, type NetworkLogStatus } from './network-log';
 import { type ReadStagedResult, type FillExcelResult } from './xlsx-template';
-import { type LoginResult, type PerformLoginOptions } from './login';
+import { type LoginResult, type PerformLoginOptions, type TypeResult } from './login';
 import { type NativeDialogState, type PagePaginationState, type PageSnapshot, type WaitForKind } from './page-context';
 import { type PageEvent } from './page-events';
+import { type RefElement } from './refs';
 /**
  * Persistent Chrome profile for the AUTO-ANSWER browser (research reads,
  * `browse --auto-answer`, the web-auto-answer tool).
@@ -55,6 +56,16 @@ export interface BrowserSessionOptions {
      * `type()` keeps throwing `LOGIN_BLOCKED` for a credential field.
      */
     allowCredentials?: boolean;
+    /**
+     * OPT-IN (default false): QA VISION mode (2026-10).
+     *
+     * When on, every mutating action result carries an inline screenshot (the
+     * bridge handler captures it) and `snapshot({refs:true})` can hand back an
+     * accessibility-style ref list. Only a QA run turns it on
+     * (`browser_open({ qaVision: true })`, instructed by the QA brief), so the
+     * interactive browser and the auto-answer path are unchanged.
+     */
+    qaVision?: boolean;
 }
 export declare class BrowserSession {
     private readonly id;
@@ -68,6 +79,14 @@ export declare class BrowserSession {
     private _connected;
     /** Opt-in credential entry (see BrowserSessionOptions.allowCredentials). */
     private _allowCredentials;
+    /** Opt-in QA vision mode (see BrowserSessionOptions.qaVision). */
+    private _qaVision;
+    /**
+     * The last ref scan (2026-10). Kept so a stale ref can be explained and,
+     * when a unique same-role/same-name element exists in the fresh scan,
+     * transparently re-pointed - instead of failing with a mute miss.
+     */
+    private _lastRefs;
     /**
      * True when THIS bridge process launched the Chrome this session is attached
      * to. Only such a browser may be terminated by the bridge; one the human
@@ -108,6 +127,12 @@ export declare class BrowserSession {
      */
     setAllowCredentials(allow: boolean): void;
     get allowCredentials(): boolean;
+    /**
+     * Toggle QA vision mode (2026-10). Persists across actions, exactly like
+     * allowCredentials: `browser_open({ qaVision: true })` sets it once.
+     */
+    setQaVision(on: boolean): void;
+    get qaVision(): boolean;
     /** The native JS dialog currently blocking the page, if any. */
     get nativeDialog(): NativeDialogState | null;
     /** Last time a command actually used this session (drives idle close). */
@@ -237,6 +262,12 @@ export declare class BrowserSession {
      * Capture a screenshot. Returns base64-encoded data.
      */
     screenshot(format?: 'jpeg' | 'png', quality?: number): Promise<string>;
+    /**
+     * Capture a screenshot with numbered ref labels drawn over the interactive
+     * elements, then remove the overlay (2026-10). One image shows the page AND
+     * names every target; the page is never left modified.
+     */
+    annotatedScreenshot(format?: 'jpeg' | 'png', quality?: number): Promise<string>;
     /**
      * Read the network + console evidence collected for this session (QA).
      * `onlyProblems` narrows to failures/redirects; `clear` empties the buffer
@@ -254,9 +285,95 @@ export declare class BrowserSession {
         status: NetworkLogStatus;
     }>;
     /**
-     * Click at (x, y) coordinates.
+     * Click at (x, y) CSS pixels. Coordinates OUTSIDE the current viewport are
+     * refused loudly — a screenshot pixel is not a CSS pixel (the capture is
+     * device-scale), so clicking one lands on the wrong element.
      */
     click(x: number, y: number): Promise<void>;
+    /**
+     * Click by reference instead of raw coordinates: an element REF (`e7`, from
+     * getRefs / snapshot refs:true), explicit x/y, a fresh `getElements` index,
+     * or a CSS selector resolved in-page. Coordinates from a screenshot image are
+     * NEVER accepted here — they are device-scale.
+     */
+    clickRef(ref: {
+        ref?: string;
+        x?: number;
+        y?: number;
+        elementIndex?: number;
+        selector?: string;
+    }): Promise<{
+        x: number;
+        y: number;
+        refreshedFrom?: string;
+    }>;
+    /**
+     * Fresh element-ref scan (2026-10).
+     *
+     * Returns the interactive elements of the CURRENT page as `e1 … eN` with
+     * role, accessible name, state and CSS-pixel centre. Includes elements
+     * inside portalled menus/popovers/dialogs, which is the whole point: a kebab
+     * menu that just opened is findable without guessing a selector.
+     */
+    getRefs(): Promise<{
+        at: number;
+        count: number;
+        refs: RefElement[];
+        lines: string[];
+    }>;
+    /**
+     * Resolve a ref to a clickable point. A ref whose node left the DOM is
+     * either re-pointed at a UNIQUE same-role/same-name element from a fresh
+     * scan (the common case: a re-render replaced the node), or refused with
+     * `REF_STALE` - never silently clicked at stale coordinates.
+     */
+    private resolveRefPoint;
+    /** Move the pointer to (x, y) without clicking (hover menus/tooltips). */
+    hover(x: number, y: number): Promise<void>;
+    /** Hover an element by ref (preferred) or CSS selector. */
+    hoverRef(ref: {
+        ref?: string;
+        selector?: string;
+    }): Promise<{
+        x: number;
+        y: number;
+        refreshedFrom?: string;
+    }>;
+    /**
+     * Click a ref'd element with the IN-PAGE pointer sequence instead of a CDP
+     * coordinate click (2026-10). This is the rescue for a control that ignores
+     * a normal click (the Radix lesson from the web tours: some activators only
+     * react to a full pointerdown/mousedown gesture). Explicit, never automatic:
+     * a blind second click after "nothing happened" could double-submit a form.
+     */
+    clickPointerRef(ref: string): Promise<{
+        x: number;
+        y: number;
+    }>;
+    /**
+     * Focus an element by ref (2026-10). Reports whether focus actually moved:
+     * a plain div without tabindex cannot take focus, and claiming `ok:true`
+     * while the active element is unchanged is how a QA step "passes" having
+     * done nothing.
+     */
+    focusRef(ref: string): Promise<{
+        ok: boolean;
+        alive: boolean;
+        tag?: string;
+        contentEditable?: boolean;
+        refreshedFrom?: string;
+    }>;
+    /**
+     * Close whatever menu/popover layer is open (2026-10): Escape first (Radix
+     * DismissableLayer), then a document-level outside pointer sequence for
+     * layers that ignore Escape. Reports what is left, so a "still open" menu is
+     * visible instead of silently swallowing the next click.
+     */
+    closePopup(): Promise<{
+        closed: boolean;
+        popoversLeft: number;
+    }>;
+    private countPopovers;
     /**
      * Type text at the current cursor position, VERIFYING it landed.
      *
@@ -264,10 +381,13 @@ export declare class BrowserSession {
      * caller opted in (`browser_open({ allowCredentials: true })`) AND passed a
      * credential for the run - the debug browser is the QA surface, the
      * auto-answer loop is a separate path that still never touches credentials.
+     *
+     * An insert the page does not reflect is refused with `TYPE_NOT_VERIFIED`
+     * (carrying the observed field state) — never reported as success.
      */
     type(text: string, opts?: {
         clearFirst?: boolean;
-    }): Promise<void>;
+    }): Promise<TypeResult>;
     /**
      * Deterministically fill a login form (username + password) and submit.
      * Handles the common two-step email -> Continue -> password flow. Requires
@@ -424,7 +544,12 @@ export declare class BrowserSession {
         includeText?: boolean;
         maxTextChars?: number;
         maxFields?: number;
-    }): Promise<PageSnapshot>;
+        /** Also return the interactive element refs (QA vision, 2026-10). */
+        refs?: boolean;
+    }): Promise<PageSnapshot & {
+        refs?: RefElement[];
+        refsText?: string[];
+    }>;
     /**
      * Bounded state attached to every mutating action result. Never include the
      * page text (that is what `snapshot` is for); a failure returns null so an