teamshare-bridge 0.26.13 → 0.26.15

package/dist/lib/browser/session.js

@@ -57,6 +57,7 @@ const process_1 = require("./process");
 const login_1 = require("./login");
 const page_context_1 = require("./page-context");
 const page_events_1 = require("./page-events");
+const refs_1 = require("./refs");
 const screen_change_1 = require("./screen-change");
 /**
  * Persistent Chrome profile for the AUTO-ANSWER browser (research reads,
@@ -99,6 +100,14 @@ class BrowserSession {
     _connected = false;
     /** Opt-in credential entry (see BrowserSessionOptions.allowCredentials). */
     _allowCredentials;
+    /** Opt-in QA vision mode (see BrowserSessionOptions.qaVision). */
+    _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.
+     */
+    _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
@@ -126,6 +135,7 @@ class BrowserSession {
         this._profileDir = opts?.profileDir ?? exports.DEBUG_PROFILE_DIR;
         this._chromeArgs = opts?.chromeArgs ?? [];
         this._allowCredentials = opts?.allowCredentials ?? false;
+        this._qaVision = opts?.qaVision ?? false;
     }
     /** The stable session name the browser manager keys this session by. */
     get sessionKey() {
@@ -160,6 +170,9 @@ class BrowserSession {
         if (opts.allowCredentials !== undefined) {
             this._allowCredentials = opts.allowCredentials;
         }
+        if (opts.qaVision !== undefined) {
+            this._qaVision = opts.qaVision;
+        }
     }
     /**
      * Toggle credential entry for this session. Persists across actions - a
@@ -171,6 +184,16 @@ class BrowserSession {
     get allowCredentials() {
         return this._allowCredentials;
     }
+    /**
+     * Toggle QA vision mode (2026-10). Persists across actions, exactly like
+     * allowCredentials: `browser_open({ qaVision: true })` sets it once.
+     */
+    setQaVision(on) {
+        this._qaVision = on;
+    }
+    get qaVision() {
+        return this._qaVision;
+    }
     /** The native JS dialog currently blocking the page, if any. */
     get nativeDialog() {
         return this._nativeDialog;
@@ -397,8 +420,281 @@ class BrowserSession {
         }
     }
     /**
-     * Navigate to a URL. Returns page info after navigation.
+     * Current pagination state (controls, page, page size, total, rows).
+     * Scoped to the top dialog by the page-state script.
      */
+    async pagination() {
+        this.ensureConnected();
+        const state = await (0, page_context_1.readPageState)(this.page, { includeText: false });
+        return state.pagination;
+    }
+    /** Stable-ish signature used to prove a page actually changed. */
+    async paginationSignature() {
+        const state = await (0, page_context_1.readPageState)(this.page, { includeText: false });
+        let firstRow = '';
+        try {
+            firstRow = String(await (0, cdp_1.evaluateJs)(this.page, `(() => {
+            const vis = (el) => { if (!el) return false; const r = el.getBoundingClientRect(); return r.width > 0 && r.height > 0; };
+            const rows = [...document.querySelectorAll('tbody tr,[role="row"]')].filter(vis);
+            const row = rows.find((r) => r.querySelectorAll('td').length > 0);
+            return row ? String(row.innerText || row.textContent || '').replace(/\\s+/g, ' ').trim().slice(0, 80) : '';
+          })()`));
+        }
+        catch {
+            /* navigation / context loss */
+        }
+        const p = state.pagination;
+        return [
+            p.page ?? '',
+            p.rowCount,
+            p.total ?? '',
+            firstRow,
+            p.controls.map((c) => `${c.kind}:${c.disabled ? 1 : 0}`).join(','),
+        ].join('|');
+    }
+    async waitPaginationChange(before, timeoutMs = 8000) {
+        const started = Date.now();
+        const deadline = started + Math.min(Math.max(timeoutMs, 500), 30_000);
+        while (Date.now() < deadline) {
+            await new Promise((resolve) => setTimeout(resolve, 220));
+            try {
+                if ((await this.paginationSignature()) !== before) {
+                    return {
+                        moved: true,
+                        state: await this.pagination(),
+                        elapsedMs: Date.now() - started,
+                    };
+                }
+            }
+            catch {
+                /* navigation during the poll - retry */
+            }
+        }
+        return {
+            moved: false,
+            state: await this.pagination().catch(() => ({
+                kind: 'none',
+                hasNext: false,
+                hasPrev: false,
+                rowCount: 0,
+                pageSizeOptions: [],
+                controls: [],
+            })),
+            elapsedMs: Date.now() - started,
+        };
+    }
+    async clickPagination(kind, page) {
+        const state = await this.pagination();
+        const control = state.controls.find((c) => c.kind === kind && (page === undefined || c.page === page)) ??
+            (kind === 'next'
+                ? state.controls.find((c) => c.kind === 'loadMore')
+                : undefined);
+        if (!control || control.disabled)
+            return { clicked: false };
+        await (0, cdp_1.clickAt)(this.page, control.x, control.y);
+        return { clicked: true, control };
+    }
+    /** Move to the next page (or Load more) and wait for the content to change. */
+    async nextPage(timeoutMs = 8000) {
+        this.ensureConnected();
+        const before = await this.paginationSignature();
+        const clicked = await this.clickPagination('next');
+        if (!clicked.clicked) {
+            return {
+                moved: false,
+                elapsedMs: 0,
+                state: await this.pagination(),
+                reason: 'no enabled next/load-more control',
+            };
+        }
+        const result = await this.waitPaginationChange(before, timeoutMs);
+        return {
+            ...result,
+            ...(result.moved ? {} : { reason: 'page did not change' }),
+        };
+    }
+    /** Move to the previous page. */
+    async prevPage(timeoutMs = 8000) {
+        this.ensureConnected();
+        const before = await this.paginationSignature();
+        const clicked = await this.clickPagination('prev');
+        if (!clicked.clicked) {
+            return {
+                moved: false,
+                elapsedMs: 0,
+                state: await this.pagination(),
+                reason: 'no enabled previous control',
+            };
+        }
+        const result = await this.waitPaginationChange(before, timeoutMs);
+        return {
+            ...result,
+            ...(result.moved ? {} : { reason: 'page did not change' }),
+        };
+    }
+    /** Go to a numbered page; walks next if the page control is not rendered. */
+    async gotoPage(page, timeoutMs = 8000) {
+        this.ensureConnected();
+        const target = Math.max(1, Math.floor(page));
+        const current = await this.pagination();
+        if (current.page === target) {
+            return {
+                moved: false,
+                elapsedMs: 0,
+                state: current,
+                reason: 'already on page',
+            };
+        }
+        const before = await this.paginationSignature();
+        const direct = await this.clickPagination('page', target);
+        if (direct.clicked) {
+            const result = await this.waitPaginationChange(before, timeoutMs);
+            return {
+                ...result,
+                ...(result.moved ? {} : { reason: 'page did not change' }),
+            };
+        }
+        // Walk forward (bounded) when only prev/next controls exist.
+        for (let i = 0; i < Math.min(target, 100); i += 1) {
+            const next = await this.nextPage(timeoutMs);
+            if (!next.moved)
+                return { ...next, reason: next.reason ?? 'page did not change' };
+            if (next.state.page === target)
+                return next;
+        }
+        return {
+            moved: false,
+            elapsedMs: 0,
+            state: await this.pagination(),
+            reason: 'page control not found and the target was not reached',
+        };
+    }
+    /** Select a native page-size option (custom comboboxes use click + waitFor). */
+    async setPageSize(size) {
+        this.ensureConnected();
+        const before = await this.paginationSignature();
+        const changed = await (0, cdp_1.evaluateJs)(this.page, `(() => {
+        const vis = (el) => { if (!el) return false; const r = el.getBoundingClientRect(); return r.width > 0 && r.height > 0; };
+        const target = ${Math.max(1, Math.floor(size))};
+        for (const sel of [...document.querySelectorAll('select')].filter(vis)) {
+          const options = [...sel.options];
+          const option = options.find((o) => Number(String(o.textContent || o.label || '').trim()) === target);
+          if (!option) continue;
+          const proto = HTMLSelectElement.prototype;
+          const desc = Object.getOwnPropertyDescriptor(proto, 'value');
+          if (desc && desc.set) desc.set.call(sel, option.value);
+          else sel.value = option.value;
+          sel.dispatchEvent(new Event('input', { bubbles: true }));
+          sel.dispatchEvent(new Event('change', { bubbles: true }));
+          return true;
+        }
+        return false;
+      })()`);
+        if (changed !== true) {
+            return {
+                ok: false,
+                state: await this.pagination(),
+                error: 'page size is not a native select; use getElements + click on the custom combobox',
+            };
+        }
+        const result = await this.waitPaginationChange(before);
+        return {
+            ok: true,
+            state: result.state,
+            ...(result.moved ? {} : { error: 'page did not visibly change' }),
+        };
+    }
+    /**
+     * Read the current table (headers + rows), then walk every page and return
+     * the deduplicated rows. Bounded by maxPages/maxRows; stops on a repeated
+     * page signature, a disabled pager, or an unchanged table.
+     */
+    async collectTable(opts) {
+        this.ensureConnected();
+        if (opts?.pageSize)
+            await this.setPageSize(opts.pageSize);
+        const maxPages = Math.min(Math.max(opts?.maxPages ?? 50, 1), 200);
+        const maxRows = Math.min(Math.max(opts?.maxRows ?? 2000, 1), 10_000);
+        const seen = new Set();
+        const rows = [];
+        let headers = [];
+        let duplicates = 0;
+        let pagesVisited = 0;
+        let stoppedBecause = 'unknown';
+        let truncated = false;
+        const readTable = async () => {
+            try {
+                const raw = await (0, cdp_1.evaluateJs)(this.page, `(() => {
+            const vis = (el) => { if (!el) return false; const r = el.getBoundingClientRect(); return r.width > 0 && r.height > 0; };
+            const selector = ${JSON.stringify(opts?.selector ?? '')};
+            let table = selector ? document.querySelector(selector) : null;
+            if (!table) {
+              const tables = [...document.querySelectorAll('table,[role="table"],[role="grid"]')].filter(vis);
+              table = tables.sort((a, b) => b.querySelectorAll('tr,[role="row"]').length - a.querySelectorAll('tr,[role="row"]').length)[0] || null;
+            }
+            if (!table) return null;
+            const headers = [...table.querySelectorAll('thead th,[role="columnheader"]')].map((h) => String(h.innerText || h.textContent || '').replace(/\\s+/g, ' ').trim()).filter(Boolean);
+            const bodyRows = [...table.querySelectorAll('tbody tr,[role="row"]')].filter(vis)
+              .filter((r) => r.querySelectorAll('td,[role="gridcell"],[role="cell"]').length > 0);
+            return {
+              headers,
+              rows: bodyRows.map((r) => [...r.querySelectorAll('td,[role="gridcell"],[role="cell"]')].map((c) => String(c.innerText || c.textContent || '').replace(/\\s+/g, ' ').trim())),
+            };
+          })()`);
+                if (!raw || typeof raw !== 'object')
+                    return null;
+                return raw;
+            }
+            catch {
+                return null;
+            }
+        };
+        for (let page = 0; page < maxPages; page += 1) {
+            const table = await readTable();
+            if (!table) {
+                stoppedBecause = 'no table found';
+                break;
+            }
+            pagesVisited += 1;
+            if (table.headers.length)
+                headers = table.headers;
+            for (const row of table.rows) {
+                const key = row.join('\u0001');
+                if (seen.has(key)) {
+                    duplicates += 1;
+                    continue;
+                }
+                seen.add(key);
+                rows.push(row);
+                if (rows.length >= maxRows) {
+                    truncated = true;
+                    stoppedBecause = 'maxRows';
+                    break;
+                }
+            }
+            if (truncated)
+                break;
+            const next = await this.nextPage();
+            if (!next.moved) {
+                stoppedBecause = next.reason ?? 'end of pages';
+                break;
+            }
+        }
+        const state = await this.pagination().catch(() => null);
+        return {
+            headers,
+            rows,
+            rowCount: rows.length,
+            pagesVisited,
+            ...(state?.total ? { total: state.total } : {}),
+            complete: !truncated &&
+                (stoppedBecause === 'end of pages' ||
+                    stoppedBecause === 'no enabled next/load-more control'),
+            duplicates,
+            truncated,
+            stoppedBecause,
+        };
+    }
     async navigate(url) {
         this.ensureConnected();
         return (0, cdp_1.navigateTo)(this.page, url);
@@ -408,10 +704,28 @@ class BrowserSession {
      */
     async screenshot(format = 'jpeg', quality = 70) {
         this.ensureConnected();
-        const data = await (0, cdp_1.captureScreenshot)(this.page, format, quality);
-        if (!data)
-            throw new Error('Screenshot failed');
-        return data;
+        return (0, cdp_1.captureScreenshotChecked)(this.page, format, quality);
+    }
+    /**
+     * 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.
+     */
+    async annotatedScreenshot(format = 'jpeg', quality = 70) {
+        this.ensureConnected();
+        await this.getRefs();
+        try {
+            await (0, cdp_1.evaluateJs)(this.page, (0, refs_1.buildAnnotateScript)());
+            return await (0, cdp_1.captureScreenshotChecked)(this.page, format, quality);
+        }
+        finally {
+            try {
+                await (0, cdp_1.evaluateJs)(this.page, (0, refs_1.buildClearAnnotationScript)());
+            }
+            catch {
+                /* overlay cleanup is best-effort; it is pointer-events:none */
+            }
+        }
     }
     /**
      * Read the network + console evidence collected for this session (QA).
@@ -423,12 +737,211 @@ class BrowserSession {
         return this.network.snapshot(this.page, opts);
     }
     /**
-     * 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.
      */
     async click(x, y) {
         this.ensureConnected();
+        const vp = await (0, cdp_1.viewportOf)(this.page);
+        if (vp && (x < 0 || y < 0 || x > vp.width || y > vp.height)) {
+            throw new Error(`CLICK_OUT_OF_VIEWPORT: (${Math.round(x)}, ${Math.round(y)}) is outside the ${vp.width}x${vp.height} CSS viewport. Get fresh coordinates from getElements or snapshot fields (CSS pixels, never screenshot pixels — the capture is device-scale, ~${vp.dpr}x), or click an element by selector instead.`);
+        }
         await (0, cdp_1.clickAt)(this.page, x, y);
     }
+    /**
+     * 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.
+     */
+    async clickRef(ref) {
+        this.ensureConnected();
+        if (typeof ref.ref === 'string' && ref.ref) {
+            const pt = await this.resolveRefPoint(ref.ref);
+            await this.click(pt.x, pt.y);
+            return {
+                x: pt.x,
+                y: pt.y,
+                ...(pt.refreshed ? { refreshedFrom: ref.ref } : {}),
+            };
+        }
+        if (typeof ref.x === 'number' && typeof ref.y === 'number') {
+            await this.click(ref.x, ref.y);
+            return { x: ref.x, y: ref.y };
+        }
+        if (typeof ref.elementIndex === 'number') {
+            const elements = await this.getElements();
+            const el = elements[ref.elementIndex];
+            if (!el) {
+                throw new Error(`ELEMENT_INDEX_OUT_OF_RANGE: getElements returned ${elements.length} elements, no index ${ref.elementIndex}. Re-read getElements — the page changed since the last list.`);
+            }
+            await this.click(el.x, el.y);
+            return { x: el.x, y: el.y };
+        }
+        if (typeof ref.selector === 'string' && ref.selector) {
+            const pt = await (0, cdp_1.evaluateJs)(this.page, `(() => { const el = document.querySelector(${JSON.stringify(ref.selector)}); if (!el) return null; const r = el.getBoundingClientRect(); if (!r || r.width === 0 && r.height === 0) return null; return { x: Math.round(r.x + r.width / 2), y: Math.round(r.y + r.height / 2) }; })()`);
+            if (!pt || typeof pt.x !== 'number' || typeof pt.y !== 'number') {
+                throw new Error(`SELECTOR_NOT_FOUND: no visible element matches the selector. Re-check with getElements or snapshot.`);
+            }
+            await this.click(pt.x, pt.y);
+            return { x: pt.x, y: pt.y };
+        }
+        throw new Error('CLICK_TARGET_REQUIRED: pass x/y, elementIndex or selector.');
+    }
+    /**
+     * 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.
+     */
+    async getRefs() {
+        this.ensureConnected();
+        const { at, list } = await (0, refs_1.scanRefs)(this.page);
+        this._lastRefs = list;
+        return { at, count: list.length, refs: list, lines: (0, refs_1.formatRefs)(list) };
+    }
+    /**
+     * 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.
+     */
+    async resolveRefPoint(ref) {
+        const info = await (0, cdp_1.evaluateJs)(this.page, (0, refs_1.buildRefInfoScript)(ref));
+        if (info && info.alive === true && typeof info.x === 'number') {
+            return { x: Math.round(info.x), y: Math.round(info.y), refreshed: false };
+        }
+        const previous = this._lastRefs.find((r) => r.ref === ref);
+        const { list } = await (0, refs_1.scanRefs)(this.page);
+        this._lastRefs = list;
+        const candidates = previous
+            ? list.filter((r) => r.role === previous.role && r.name === previous.name)
+            : [];
+        if (candidates.length === 1) {
+            return { x: candidates[0].x, y: candidates[0].y, refreshed: true };
+        }
+        throw new Error(`REF_STALE: ${ref}${previous?.name ? ` (${previous.role} "${previous.name}")` : ''} is no longer on the page. ` +
+            'Call browser_action({action:"getRefs"}) or snapshot {refs:true} for a fresh list and use the new ref - never guess a selector.');
+    }
+    /** Move the pointer to (x, y) without clicking (hover menus/tooltips). */
+    async hover(x, y) {
+        this.ensureConnected();
+        await (0, cdp_1.hoverAt)(this.page, x, y);
+    }
+    /** Hover an element by ref (preferred) or CSS selector. */
+    async hoverRef(ref) {
+        this.ensureConnected();
+        if (typeof ref.ref === 'string' && ref.ref) {
+            const pt = await this.resolveRefPoint(ref.ref);
+            await this.hover(pt.x, pt.y);
+            return {
+                x: pt.x,
+                y: pt.y,
+                ...(pt.refreshed ? { refreshedFrom: ref.ref } : {}),
+            };
+        }
+        if (typeof ref.selector === 'string' && ref.selector) {
+            const pt = await (0, cdp_1.evaluateJs)(this.page, `(() => { const el = document.querySelector(${JSON.stringify(ref.selector)}); if (!el) return null; const r = el.getBoundingClientRect(); if (!r || (r.width === 0 && r.height === 0)) return null; return { x: Math.round(r.x + r.width / 2), y: Math.round(r.y + r.height / 2) }; })()`);
+            if (!pt || typeof pt.x !== 'number' || typeof pt.y !== 'number') {
+                throw new Error('SELECTOR_NOT_FOUND: no visible element matches the selector. Re-check getRefs or snapshot.');
+            }
+            await this.hover(pt.x, pt.y);
+            return { x: pt.x, y: pt.y };
+        }
+        throw new Error('HOVER_TARGET_REQUIRED: pass ref or selector.');
+    }
+    /**
+     * 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.
+     */
+    async clickPointerRef(ref) {
+        this.ensureConnected();
+        const result = await (0, cdp_1.evaluateJs)(this.page, (0, refs_1.buildRefPointerScript)(ref));
+        if (!result || result.alive === false) {
+            throw new Error(`REF_STALE: ${ref} is no longer on the page. Call getRefs or snapshot {refs:true} for a fresh list.`);
+        }
+        if (result.ok !== true) {
+            throw new Error(`POINTER_CLICK_FAILED: ${ref} could not be clicked in-page. Re-read the screen and retry.`);
+        }
+        return {
+            x: Math.round(Number(result.x) || 0),
+            y: Math.round(Number(result.y) || 0),
+        };
+    }
+    /**
+     * 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.
+     */
+    async focusRef(ref) {
+        this.ensureConnected();
+        let info = await (0, cdp_1.evaluateJs)(this.page, (0, refs_1.buildRefFocusScript)(ref));
+        if (info && info.alive === false) {
+            // Re-point through the same staleness ladder as click, then focus the
+            // element that now occupies those coordinates (refs were re-minted).
+            const pt = await this.resolveRefPoint(ref);
+            const target = this._lastRefs.find((r) => r.x === pt.x && r.y === pt.y);
+            if (!target) {
+                return { ok: false, alive: false };
+            }
+            info = await (0, cdp_1.evaluateJs)(this.page, (0, refs_1.buildRefFocusScript)(target.ref));
+            return {
+                ok: info?.ok === true,
+                alive: info?.alive !== false,
+                ...(typeof info?.tag === 'string' ? { tag: info.tag } : {}),
+                ...(info?.contentEditable === true ? { contentEditable: true } : {}),
+                refreshedFrom: ref,
+            };
+        }
+        return {
+            ok: info?.ok === true,
+            alive: info?.alive !== false,
+            ...(typeof info?.tag === 'string' ? { tag: info.tag } : {}),
+            ...(info?.contentEditable === true ? { contentEditable: true } : {}),
+        };
+    }
+    /**
+     * 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.
+     */
+    async closePopup() {
+        this.ensureConnected();
+        let left = await this.countPopovers();
+        if (left > 0) {
+            await (0, cdp_1.pressKey)(this.page, 'Escape');
+            await new Promise((resolve) => setTimeout(resolve, 150));
+            left = await this.countPopovers();
+        }
+        if (left > 0) {
+            try {
+                await (0, cdp_1.evaluateJs)(this.page, (0, refs_1.buildOutsidePointerScript)());
+            }
+            catch {
+                /* below reports what is still open */
+            }
+            await new Promise((resolve) => setTimeout(resolve, 150));
+            left = await this.countPopovers();
+        }
+        return { closed: left === 0, popoversLeft: left };
+    }
+    async countPopovers() {
+        try {
+            const n = await (0, cdp_1.evaluateJs)(this.page, (0, refs_1.buildPopoverCountScript)());
+            return typeof n === 'number' ? n : 0;
+        }
+        catch {
+            return 0;
+        }
+    }
     /**
      * Type text at the current cursor position, VERIFYING it landed.
      *
@@ -436,6 +949,9 @@ 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.
      */
     async type(text, opts) {
         this.ensureConnected();
@@ -443,7 +959,11 @@ class BrowserSession {
         if (credential && !this._allowCredentials) {
             throw new Error('LOGIN_BLOCKED: refusing to type into a password/credential field. Pass allowCredentials:true on browser_open (debug browser only), use browser_action({action:"login"}) with supplied credentials, or ask the human to sign in.');
         }
-        await (0, login_1.typeTextVerified)(this.page, text, opts);
+        const result = await (0, login_1.typeTextVerified)(this.page, text, opts);
+        if (!result.ok) {
+            throw new Error(`TYPE_NOT_VERIFIED: the typed text did not land (focused: ${result.focused ?? 'nothing focusable'}${result.contentEditable ? ' [contenteditable]' : ''}, before: ${result.beforeLength ?? 'unreadable'} chars, after: ${result.afterLength ?? 'unreadable'} chars). Read the field back via snapshot (focused/valueLength) and retry with clearFirst:true, or fill it with evaluate's native value setter + input/change events.`);
+        }
+        return result;
     }
     /**
      * Deterministically fill a login form (username + password) and submit.
@@ -769,7 +1289,7 @@ class BrowserSession {
             })));
         }
         const state = await (0, page_context_1.readPageState)(this.page, opts);
-        return {
+        const base = {
             ...state,
             nativeDialog: this._nativeDialog,
             pendingRequests: this.network.pendingCount(),
@@ -779,6 +1299,15 @@ class BrowserSession {
                 at: c.at,
             })),
         };
+        if (opts?.refs === true && !this._nativeDialog) {
+            const scanned = await this.getRefs();
+            return {
+                ...base,
+                refs: scanned.refs,
+                refsText: scanned.lines,
+            };
+        }
+        return base;
     }
     /**
      * Bounded state attached to every mutating action result. Never include the