/** * 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 ``, 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. */ import { type CdpPage } from './cdp'; /** A JSON-safe description of one interactive element. */ export interface RefElement { ref: string; tag: string; role: string; name: string; disabled: boolean; inDialog: boolean; inPortal: boolean; /** Length only - a field VALUE must never travel through a tool result. */ valueLength?: number; x: number; y: number; width: number; height: number; } /** Hard cap on refs per scan: keeps the tool result readable and bounded. */ export declare const MAX_REFS = 300; /** * The one scan. Returns `{ at, list }` and stores the live nodes on * `window.__tsRefs.nodes` for later `isConnected` checks / focus calls. */ export declare function buildRefScanScript(): string; /** * Human/LLM-readable ref lines. One line per element: * `e7 button "Publish draft" (640,412) [in menu]` */ export declare function formatRefs(list: RefElement[], maxLines?: number): string[]; /** Run a fresh scan and return it (the caller keeps the list). */ export declare function scanRefs(page: CdpPage): Promise<{ at: number; list: RefElement[]; }>; /** Liveness + geometry of one ref, from the node the scan stored. */ export declare function buildRefInfoScript(ref: string): string; /** * 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. */ export declare function buildRefFocusScript(ref: string): string; /** * 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. */ export declare function buildRefPointerScript(ref: string): string; /** * 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. */ export declare function buildAnnotateScript(): string; /** Remove the ref overlay (always called, even when the capture failed). */ export declare function buildClearAnnotationScript(): string; /** How many popovers/menus are currently open (used by closePopup). */ export declare function buildPopoverCountScript(): string; /** * 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 `` * at the layer's own outside point instead. */ export declare function buildOutsidePointerScript(): string;