/** * Rich page state for the debug/MCP browser (2026-10). * * The auto-answer loop already extracts title/URL/headings/errors/toasts/full * text (`extractPageContext` in browse-editor.ts). The debug browser had only a * flat text read, so a QA agent could not SEE a login dialog, its buttons, its * field state, a toast that had already disappeared, or the validation error * that explained a failed submit. In the live Soludesks run that cost five * minutes of raw `evaluate` calls and still ended on the wrong page. * * This module is the shared, structured equivalent: one in-page script returns * a JSON-safe `PageState` with the topmost dialog, its buttons and fields, * visible errors, the persistent toast buffer (page-events.ts), headings, * focus, busy state and optional page text. `compactPageState` is the bounded * version attached to ordinary action results. * * Rules: * - NEVER return a field VALUE - only `valueLength` (a password must not * travel through a tool result). * - The topmost open dialog is the interaction scope. Page fields behind a * modal are not offered as primary targets. * - Everything is capped so one snapshot cannot balloon a tool response. */ import { type CdpPage } from './cdp'; import type { PageEvent } from './page-events'; export interface PageFieldState { tag: string; type: string; label: string; name: string; autocomplete: string; valueLength: number; required: boolean; invalid: boolean; disabled: boolean; readonly: boolean; focused: boolean; inDialog: boolean; x: number; y: number; } export interface PageButtonState { text: string; type: string; disabled: boolean; x: number; y: number; } export interface PageDialogState { index: number; role: string; title: string; text: string; z: number; x: number; y: number; width: number; height: number; fields: PageFieldState[]; buttons: PageButtonState[]; } export interface PageErrorState { text: string; role: string; } export interface PageFocusState { tag: string; type: string; label: string; valueLength: number; inDialog: boolean; } export interface PagePaginationControl { label: string; kind: 'next' | 'prev' | 'page' | 'loadMore'; page?: number; disabled: boolean; current: boolean; x: number; y: number; } export interface PagePaginationState { kind: 'none' | 'numbered' | 'prev-next' | 'load-more' | 'infinite'; page?: number; pageSize?: number; total?: number; totalPages?: number; hasNext: boolean; hasPrev: boolean; rowCount: number; pageSizeOptions: number[]; controls: PagePaginationControl[]; } export interface PageMenuItemState { text: string; role: string; disabled: boolean; x: number; y: number; } /** * An OPEN menu / popover / listbox (2026-10). * * Radix renders these into a portal at the end of `
`, not inside the * card that owns them, so the old dialog-only state never saw a kebab menu or * a combobox list at all. A `...` menu was effectively invisible to the agent * even while it was open on screen. */ export interface PageMenuState { role: string; label: string; text: string; inDialog: boolean; x: number; y: number; items: PageMenuItemState[]; } export interface PageState { url: string; title: string; readyState: string; headings: string[]; dialogs: PageDialogState[]; /** Open menus/popovers/listboxes, including portalled ones. */ menus: PageMenuState[]; modal: boolean; fields: PageFieldState[]; focused: PageFocusState | null; errors: PageErrorState[]; toasts: PageEvent[]; busy: boolean; scroll: { x: number; y: number; }; /** CSS viewport + device scale (click coords are CSS pixels, screenshots are device-scale). */ viewport: { width: number; height: number; dpr: number; }; pagination: PagePaginationState; text: string; textTruncated: boolean; maxTextChars: number; } export interface NativeDialogState { type: string; message: string; defaultPrompt?: string; at: number; } export interface PageSnapshot extends PageState { nativeDialog: NativeDialogState | null; pendingRequests: number; consoleErrors: Array<{ level: string; text: string; at: number; }>; } export interface PageStateOptions { includeText?: boolean; maxTextChars?: number; maxFields?: number; } declare const DEFAULT_TEXT_CAP = 12000; declare const MAX_FIELDS = 40; declare const MAX_DIALOGS = 8; declare const MAX_ERRORS = 8; declare const MAX_TOASTS = 10; /** * Selectors that identify an OPEN layer living outside the dialog tree * (2026-10): Radix popper wrappers, portals, and any exposed menu/listbox role. * Shared with the `waitFor:"popover"` condition, so "is a menu open?" is one * definition - never an inline guess in two places that can disagree. */ export declare const POPOVER_SELECTOR = "[data-radix-popper-content-wrapper],[data-radix-portal],[data-floating-ui-portal],[role=\"menu\"],[role=\"listbox\"]"; /** * Selectors that surface user-visible errors/alerts/validation messages. * Deliberately broad (sites use every naming scheme) but every match is * length-capped and deduped by the page script. */ export declare const PAGE_ERROR_SELECTORS: string; /** * Build the in-page state script. `includeText` and `maxTextChars` are the only * variable parts; the rest is fixed and capped inside the page. */ export declare function buildPageStateScript(opts?: PageStateOptions): string; /** Read the rich page state. Never throws for a malformed page result. */ export declare function readPageState(page: CdpPage, opts?: PageStateOptions): Promise