Navegador y DOM

## `g.dom.*` — acciones DOM

Método	Firma	Descripción
`g.dom.click`	`(selector, options?) → Promise`	Hace clic en un elemento
`g.dom.enterText`	`(selector, value, options?) → Promise`	Escribe texto en un input
`g.dom.selectOption`	`(selector, options?) → Promise`	Selecciona una opción en un elemento HTML `<select>` nativo por valor, etiqueta o índice desde cero
`g.dom.scrollTo`	`(selector, options?) → Promise`	Desplaza un elemento hasta hacerlo visible
`g.dom.pressKey`	`(key, options?) → Promise`	Pulsa una tecla
`g.dom.highlight`	`(selector, durationMs?, options?) → Promise`	Resalta visualmente un elemento
`g.dom.waitForElement`	`(selector, options?) → Promise`	Espera un elemento usando MutationObserver, sin polling
`g.dom.waitForDomStable`	`(options?) → Promise`	Espera a que el DOM deje de mutar durante un periodo tranquilo
`g.dom.waitForReady`	`(selector, options?) → Promise`	Espera combinada de elemento + estabilidad DOM, la opción habitual para SPA

ElementOptions (parámetro options para métodos DOM):

{
  selectorType?: "css" | "xpath" | "text" | "text-contains"  // default: "css"
  browserTabId?: string  // defaults to active tab
}

ClickOptions:

{
  selectorType?: "css" | "xpath" | "text" | "text-contains"
  browserTabId?: string
  mode?: "default" | "human"  // default: deterministic CDP input; "human" uses visible mouse movement
}

Use el modo de clic predeterminado para automatización estable. Use { mode: "human" } cuando la página necesite movimiento visible del puntero o comportamiento tipo hover antes del clic.

SelectOptionOptions:

{
  value?: string          // option value to select
  label?: string          // visible option label to select
  index?: number          // zero-based option index to select
  selectorType?: "css" | "xpath"
  browserTabId?: string
}

Use g.dom.selectOption para controles <select> nativos. Para comboboxes, listboxes y desplegables renderizados por frameworks, use los controles visibles de la página con métodos click/teclado/wait.

WaitForElementOptions:

{
  timeout?: number        // default: 10000
  visible?: boolean       // require visibility — offsetHeight > 0, not display:none (default: false)
  selectorType?: "css" | "xpath"
  browserTabId?: string
}

WaitForDomStableOptions:

{
  timeout?: number        // default: 15000
  quietPeriod?: number    // ms of no DOM mutations before declaring stable (default: 500)
  browserTabId?: string
}

WaitForReadyOptions:

{
  timeout?: number        // default: 15000 — covers both element detection and stability
  quietPeriod?: number    // ms of no DOM mutations after element is found (default: 500)
  selectorType?: "css" | "xpath"
  browserTabId?: string
}

## `g.dom.*` — extracción de contenido

Método	Firma	Descripción
`g.dom.extractContent`	`(selector, options?) → Promise<string>`	Extrae texto de un elemento
`g.dom.getElements`	`(selector, attributeNames, options?) → Promise<Record[]>`	Obtiene atributos de elementos coincidentes
`g.dom.countElements`	`(selector, options?) → Promise<number>`	Cuenta elementos coincidentes
`g.dom.getElementXPaths`	`(selector, options?) → Promise<string[]>`	Obtiene XPath para cada elemento coincidente

## `g.page.*` — inspección de página

Método	Firma	Descripción
`g.page.getDom`	`(options?) → Promise<string>`	Obtiene el HTML de la página
`g.page.getPageSource`	`(options?) → Promise<string>`	Obtiene el código fuente bruto de la página
`g.page.getPageElements`	`(options?) → Promise<PageElement[]>`	Obtiene elementos estructurados de página: encabezados, enlaces, botones e inputs
`g.page.executeJS`	`(script, options?) → Promise<any>`	Ejecuta JavaScript en la pestaña del navegador y devuelve el resultado
`g.page.getUrl`	`(options?) → Promise<string>`	Obtiene la URL actual
`g.page.ocr`	`(options?) → Promise<OcrResult>`	Ejecuta OCR sobre el viewport o una región

g.page.executeJS() devuelve valores estructurados directamente. Si la expresión del navegador devuelve un objeto, array, número, booleano, cadena o null, JavaScript y Janet reciben el valor correspondiente. No envuelva fragmentos del navegador con JSON.stringify(...) y luego JSON.parse(...) en el script anfitrión salvo que quiera transportar texto intencionadamente.

Los fragmentos de navegador devuelven la última expresión evaluada por WebView2. Prefiera:

const links = await g.page.executeJS(`
  Array.from(document.querySelectorAll("a"))
    .map(a => ({ text: a.textContent.trim(), href: a.href }))
`);

Use texto JSON explícito solo cuando el resultado en sí deba ser una cadena:

const jsonText = await g.page.executeJS(`JSON.stringify(window.__APP_STATE__)`);
const appState = JSON.parse(jsonText);

PageElement:

{
  type: string        // "heading", "link", "button", "input"
  text: string
  href: string        // for links
  selector: string
  selectorType: string
  context: string     // "nav", "header", "footer", "main", "article"
  visibility: string  // "visible" or "suspicious"
  headingLevel: number
}

## `g.nav.*` — navegación

Método	Firma	Descripción
`g.nav.navigateToUrl`	`(url, options?) → Promise<NavigateResult>`	Navega a una URL; devuelve estado y cabeceras
`g.nav.blockRedirects`	`() → void`	Bloquea todas las redirecciones del servidor (301/302/307)
`g.nav.allowRedirects`	`() → void`	Restaura el comportamiento predeterminado de redirección

NavigateOptions:

{
  waitForLoad?: boolean                   // default: true
  browserTabId?: string
  stealth?: boolean | StealthOptions      // inject anti-detection patches before page scripts
  detectRedirects?: boolean               // detect JS/meta redirects (default: false)
}

StealthOptions — control granular de parches antidedetección:

{
  webdriver?: boolean      // hide navigator.webdriver
  chromeRuntime?: boolean  // inject window.chrome.runtime
  permissions?: boolean    // fix Permissions.prototype.query for notifications
  plugins?: boolean        // inject navigator.plugins with Chrome entries
  languages?: boolean      // ensure navigator.languages returns ["en-US", "en"]
}

NavigateResult:

{
  statusCode: number                    // HTTP status code (200, 301, 404, etc.)
  headers: Record<string, string>       // response headers
  finalUrl?: string                     // actual URL after navigation (only with detectRedirects)
  redirectDetected?: boolean            // true if final URL differs from requested
  metaRefresh?: string                  // content of <meta http-equiv="refresh"> if found
}

## `g.tabs.*` — gestión de pestañas

Método	Firma	Descripción
`g.tabs.getTabs`	`() → TabInfo[]`	Obtiene todas las pestañas abiertas
`g.tabs.newBrowserTab`	`(options?) → Promise<string>`	Crea una pestaña nueva y devuelve su ID
`g.tabs.closeTab`	`(tabId?) → Promise`	Cierra una pestaña; por defecto la activa
`g.tabs.closeAllTabs`	`()`	Cierra todas las pestañas
`g.tabs.closeOtherTabs`	`(tabId?)`	Cierra todas las pestañas salvo la especificada
`g.tabs.setActiveBrowserTab`	`(tabId)`	Cambia a una pestaña
`g.tabs.getActiveBrowserTab`	`() → string \| null`	Obtiene el ID de la pestaña activa
`g.tabs.getBrowserTabInfo`	`(tabId) → TabInfo`	Obtiene información de una pestaña específica
`g.tabs.setBrowserTabName`	`(tabId, name)`	Renombra una pestaña
`g.tabs.findTabByUrl`	`(pattern) → TabInfo \| null`	Busca una pestaña cuya URL contenga el patrón
`g.tabs.findTabByTitle`	`(pattern) → TabInfo \| null`	Busca una pestaña cuyo título contenga el patrón
`g.tabs.nextTab`	`()`	Cambia a la pestaña siguiente
`g.tabs.prevTab`	`()`	Cambia a la pestaña anterior
`g.tabs.moveTab`	`(tabId, index)`	Mueve una pestaña a otra posición

TabInfo:

{
  id: string
  name: string
  url: string
  pageTitle: string
  isActive?: boolean
}

## `g.screenshot.*` — capturas

Método	Firma	Descripción
`g.screenshot.screenshot`	`(path?) → Promise<string>`	Captura el viewport; devuelve base64 o ruta de archivo
`g.screenshot.screenshotElement`	`(selector, path?, options?) → Promise<string>`	Captura un elemento específico
`g.screenshot.screenshotFullPage`	`(path?, options?) → Promise<string>`	Captura toda la página desplazable

ScreenshotFullPageOptions:

{
  clean?: boolean       // remove overlays (default: false)
  browserTabId?: string
}

## `g.viewport.*` — viewport

Método	Firma	Descripción
`g.viewport.setViewport`	`(options)`	Define tamaño de viewport por preset o dimensiones personalizadas
`g.viewport.getViewport`	`(tabId?) → ViewportInfo \| null`	Obtiene información del viewport actual
`g.viewport.getViewportPresets`	`() → string[]`	Lista nombres de presets disponibles

ViewportOptions:

{
  tabId?: string
  preset?: string    // e.g., "iPhone 12", "Desktop"
  width?: number     // custom width in pixels
  height?: number    // custom height in pixels
}

Guida usa dos modos de viewport:

Los presets de escritorio como Full HD, QHD y 4K UHD usan escalado fit-to-pane para revisar diseños grandes dentro de un panel de pestaña más pequeño.
Los presets móviles y de tableta como Mobile M y Tablet Portrait usan emulación de dispositivo, incluidos ancho de viewport responsivo, factor de escala y comportamiento táctil.

Las dimensiones personalizadas permanecen en modo escritorio ajustado por defecto.

ViewportInfo incluye metadatos de modo:

{
  name: string
  width: number
  height: number
  isNative: boolean
  mode: "Native" | "DesktopFit" | "DeviceEmulation" | string
  deviceScaleFactor: number
  mobile: boolean
  touch: boolean
  visualScale?: number
}

## `g.layout.*` — layout de documentos

Organiza pestañas del navegador en paneles divididos.

Método	Firma	Async	Descripción
`single`	`()`	No	Contrae a un solo panel
`horizontal`	`(n?)`	No	Diseño lado a lado
`vertical`	`(n?)`	No	Diseño apilado
`quad`	`()`	No	Cuadrícula 2x2
`grid`	`(rows, cols)`	No	Diseño de cuadrícula personalizado
`moveToPane`	`(docId, paneIndex)`	No	Mueve un documento a un panel específico
`focusPane`	`(paneIndex)`	No	Enfoca un panel
`getPanes`	`() → PaneInfo[]`	No	Obtiene todos los paneles y sus documentos
`arrange`	`(docIds)`	No	Organiza documentos específicos
`arrangeByPattern`	`(urlPattern)`	No	Organiza documentos que coinciden con un patrón URL

## `g.clipboard.*` — portapapeles

Método	Firma	Async	Descripción
`copy`	`(text)`	No	Copia texto al portapapeles
`paste`	`() → string`	No	Lee texto del portapapeles
`copyElement`	`(selector, options?) → Promise<string>`	Sí	Copia el texto de un elemento

## `g.pane.*` — visibilidad de paneles

Controla los paneles de interfaz de Guida desde scripts.

Método	Firma	Async	Descripción
`show`	`(paneName)`	No	Muestra un panel
`hide`	`(paneName)`	No	Oculta un panel
`toggle`	`(paneName)`	No	Alterna la visibilidad de un panel
`focus`	`(paneName)`	No	Enfoca un panel

Nombres de panel: console, workspace, llminsight, secrets, taskmanager, history, searchIndex, store, queues, queueprocessor, mcphistory, terminal.

## `g.html.*` — utilidades HTML

Método	Firma	Async	Descripción
`toMarkdown`	`(html, options?) → string`	No	Convierte HTML a Markdown

HtmlToMarkdownOptions:

{
  githubFlavored?: boolean       // default: false
  removeComments?: boolean       // default: false
  smartHrefHandling?: boolean    // default: false
  listBulletChar?: string        // default: "-"
}

Navegador y DOM

## g.dom.* — acciones DOM

## g.dom.* — extracción de contenido

## g.page.* — inspección de página

## g.nav.* — navegación

## g.tabs.* — gestión de pestañas

## g.screenshot.* — capturas

## g.viewport.* — viewport

## g.layout.* — layout de documentos

## g.clipboard.* — portapapeles

## g.pane.* — visibilidad de paneles

## g.html.* — utilidades HTML