teamshare-bridge 0.26.13 → 0.26.15

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 } from './network-log';
+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 NativeDialogState, type PageSnapshot, type WaitForKind } from './page-context';
+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). */
@@ -176,13 +201,73 @@ export declare class BrowserSession {
         error?: string;
     }>;
     /**
-     * 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.
+     */
+    pagination(): Promise<PagePaginationState>;
+    /** Stable-ish signature used to prove a page actually changed. */
+    private paginationSignature;
+    private waitPaginationChange;
+    private clickPagination;
+    /** Move to the next page (or Load more) and wait for the content to change. */
+    nextPage(timeoutMs?: number): Promise<{
+        moved: boolean;
+        elapsedMs: number;
+        state: PagePaginationState;
+        reason?: string;
+    }>;
+    /** Move to the previous page. */
+    prevPage(timeoutMs?: number): Promise<{
+        moved: boolean;
+        elapsedMs: number;
+        state: PagePaginationState;
+        reason?: string;
+    }>;
+    /** Go to a numbered page; walks next if the page control is not rendered. */
+    gotoPage(page: number, timeoutMs?: number): Promise<{
+        moved: boolean;
+        elapsedMs: number;
+        state: PagePaginationState;
+        reason?: string;
+    }>;
+    /** Select a native page-size option (custom comboboxes use click + waitFor). */
+    setPageSize(size: number): Promise<{
+        ok: boolean;
+        state: PagePaginationState;
+        error?: string;
+    }>;
+    /**
+     * 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.
      */
+    collectTable(opts?: {
+        selector?: string;
+        maxPages?: number;
+        maxRows?: number;
+        pageSize?: number;
+    }): Promise<{
+        headers: string[];
+        rows: string[][];
+        rowCount: number;
+        pagesVisited: number;
+        total?: number;
+        complete: boolean;
+        duplicates: number;
+        truncated: boolean;
+        stoppedBecause: string;
+    }>;
     navigate(url: string): Promise<PageInfo>;
     /**
      * 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
@@ -196,11 +281,99 @@ export declare class BrowserSession {
     }): Promise<{
         requests: NetworkEntry[];
         console: ConsoleEntry[];
+        websockets: WebSocketFrame[];
+        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.
      *
@@ -208,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
@@ -368,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