Navegador e DOM

## g.dom.* — ações DOM

Método	Assinatura	Descrição
g.dom.click	(selector, options?) → Promise	Clica em um elemento
g.dom.enterText	(selector, value, options?) → Promise	Digita texto em um input
g.dom.selectOption	(selector, options?) → Promise	Seleciona uma opção em um <select> HTML nativo por valor, label ou índice baseado em zero
g.dom.scrollTo	(selector, options?) → Promise	Rola até um elemento
g.dom.pressKey	(key, options?) → Promise	Pressiona uma tecla
g.dom.highlight	(selector, durationMs?, options?) → Promise	Destaca visualmente um elemento
g.dom.waitForElement	(selector, options?) → Promise	Aguarda elemento usando MutationObserver, sem polling
g.dom.waitForDomStable	(options?) → Promise	Aguarda até o DOM parar de mudar por um período silencioso
g.dom.waitForReady	(selector, options?) → Promise	Espera combinada por elemento + estabilidade do DOM; recomendada para SPAs

ElementOptions:

{
  selectorType?: "css" | "xpath" | "text" | "text-contains"  // padrão: "css"
  browserTabId?: string  // padrão: guia ativa
}

ClickOptions:

{
  selectorType?: "css" | "xpath" | "text" | "text-contains"
  browserTabId?: string
  mode?: "default" | "human"  // padrão: entrada CDP determinística; "human" usa movimento visível do mouse
}

Use o modo padrão de clique para automação estável. Use { mode: "human" } quando a página precisa de movimento visível do ponteiro ou comportamento parecido com hover antes do clique.

SelectOptionOptions:

{
  value?: string
  label?: string
  index?: number
  selectorType?: "css" | "xpath"
  browserTabId?: string
}

Use g.dom.selectOption para controles <select> nativos. Para comboboxes, listboxes e menus suspensos renderizados por frameworks, use os controles visíveis da página com métodos de clique, teclado e espera.

WaitForElementOptions:

{
  timeout?: number
  visible?: boolean
  selectorType?: "css" | "xpath"
  browserTabId?: string
}

WaitForDomStableOptions:

{
  timeout?: number
  quietPeriod?: number
  browserTabId?: string
}

WaitForReadyOptions:

{
  timeout?: number
  quietPeriod?: number
  selectorType?: "css" | "xpath"
  browserTabId?: string
}

---

## g.dom.* — extração de conteúdo

Método	Assinatura	Descrição
g.dom.extractContent	(selector, options?) → Promise<string>	Extrai texto de um elemento
g.dom.getElements	(selector, attributeNames, options?) → Promise<Record[]>	Obtém atributos de elementos correspondentes
g.dom.countElements	(selector, options?) → Promise<number>	Conta elementos correspondentes
g.dom.getElementXPaths	(selector, options?) → Promise<string[]>	Obtém XPath de cada elemento correspondente

---

## g.page.* — inspeção de página

Método	Assinatura	Descrição
g.page.getDom	(options?) → Promise<string>	Obtém o HTML da página
g.page.getPageSource	(options?) → Promise<string>	Obtém o código-fonte bruto da página
g.page.getPageElements	(options?) → Promise<PageElement[]>	Obtém elementos estruturados da página (cabeçalhos, links, botões, inputs)
g.page.executeJS	(script, options?) → Promise<any>	Executa JavaScript na guia do navegador e retorna o resultado do navegador
g.page.getUrl	(options?) → Promise<string>	Obtém a URL atual da página
g.page.ocr	(options?) → Promise<OcrResult>	Executa OCR no viewport ou em uma região

g.page.executeJS() retorna valores estruturados diretamente. Se a expressão do navegador retorna objeto, array, número, booleano, string ou null, JavaScript e Janet recebem o valor correspondente. Não envolva snippets do navegador em JSON.stringify(...) e depois JSON.parse(...) no script host salvo quando você realmente quer transportar texto.

Prefira:

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

Use JSON explícito apenas quando o próprio resultado deve ser uma string:

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

---

## g.nav.* — navegação

Método	Assinatura	Descrição
g.nav.navigateToUrl	(url, options?) → Promise<NavigateResult>	Navega para uma URL e retorna status/cabeçalhos
g.nav.blockRedirects	() → void	Bloqueia redirecionamentos server-side (301/302/307)
g.nav.allowRedirects	() → void	Restaura o comportamento padrão de redirecionamento

NavigateOptions:

{
  waitForLoad?: boolean
  browserTabId?: string
  stealth?: boolean | StealthOptions
  detectRedirects?: boolean
}

StealthOptions:

{
  webdriver?: boolean
  chromeRuntime?: boolean
  permissions?: boolean
  plugins?: boolean
  languages?: boolean
}

NavigateResult:

{
  statusCode: number
  headers: Record<string, string>
  finalUrl?: string
  redirectDetected?: boolean
  metaRefresh?: string
}

---

## g.tabs.* — gerenciamento de guias

Método	Assinatura	Descrição
g.tabs.getTabs	() → TabInfo[]	Obtém todas as guias abertas
g.tabs.newBrowserTab	(options?) → Promise<string>	Cria uma nova guia e retorna o ID
g.tabs.closeTab	(tabId?) → Promise	Fecha uma guia, padrão para a ativa
g.tabs.closeAllTabs	()	Fecha todas as guias
g.tabs.closeOtherTabs	(tabId?)	Fecha todas as guias exceto a informada
g.tabs.setActiveBrowserTab	(tabId)	Alterna para uma guia
g.tabs.getActiveBrowserTab	() → string | null	Obtém o ID da guia ativa
g.tabs.getBrowserTabInfo	(tabId) → TabInfo	Obtém informações de uma guia específica
g.tabs.setBrowserTabName	(tabId, name)	Renomeia uma guia
g.tabs.findTabByUrl	(pattern) → TabInfo | null	Encontra guia cuja URL contém o padrão
g.tabs.findTabByTitle	(pattern) → TabInfo | null	Encontra guia cujo título contém o padrão
g.tabs.nextTab	()	Alterna para a próxima guia
g.tabs.prevTab	()	Alterna para a guia anterior
g.tabs.moveTab	(tabId, index)	Move uma guia para outra posição

TabInfo:

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

---

## g.screenshot.* — capturas de tela

Método	Assinatura	Descrição
g.screenshot.screenshot	(path?) → Promise<string>	Captura o viewport e retorna base64 ou caminho de arquivo
g.screenshot.screenshotElement	(selector, path?, options?) → Promise<string>	Captura um elemento específico
g.screenshot.screenshotFullPage	(path?, options?) → Promise<string>	Captura a página rolável inteira

ScreenshotFullPageOptions:

{
  clean?: boolean
  browserTabId?: string
}

---

## g.viewport.* — viewport

Método	Assinatura	Descrição
g.viewport.setViewport	(options)	Define o tamanho do viewport por preset ou dimensões customizadas
g.viewport.getViewport	(tabId?) → ViewportInfo | null	Obtém informações do viewport atual
g.viewport.getViewportPresets	() → string[]	Lista nomes de presets disponíveis

ViewportOptions:

{
  tabId?: string
  preset?: string
  width?: number
  height?: number
}

O Guida usa dois modos de viewport:

• Presets desktop como Full HD, QHD e 4K UHD usam escala fit-to-pane para revisar layouts grandes dentro de um painel menor.
• Presets mobile/tablet como Mobile M e Tablet Portrait usam emulação de dispositivo, incluindo largura responsiva, device scale factor e comportamento touch.

Dimensões customizadas permanecem em desktop fit por padrão.

---

## g.layout.* — layout de documentos

Organiza guias do navegador em painéis divididos.

Método	Assinatura	Async	Descrição
single	()	Não	Colapsa para painel único
horizontal	(n?)	Não	Layout lado a lado
vertical	(n?)	Não	Layout empilhado
quad	()	Não	Grade 2x2
grid	(rows, cols)	Não	Layout de grade customizado
moveToPane	(docId, paneIndex)	Não	Move um documento para um painel específico
focusPane	(paneIndex)	Não	Foca um painel
getPanes	() → PaneInfo[]	Não	Obtém todos os painéis e documentos
arrange	(docIds)	Não	Organiza documentos específicos
arrangeByPattern	(urlPattern)	Não	Organiza documentos cuja URL corresponde ao padrão

---

## g.clipboard.* — área de transferência

Método	Assinatura	Async	Descrição
copy	(text)	Não	Copia texto para a área de transferência
paste	() → string	Não	Lê texto da área de transferência
copyElement	(selector, options?) → Promise<string>	Sim	Copia o texto de um elemento

---

## g.pane.* — visibilidade de painéis

Controla painéis da interface do Guida a partir de scripts.

Método	Assinatura	Async	Descrição
show	(paneName)	Não	Mostra um painel
hide	(paneName)	Não	Oculta um painel
toggle	(paneName)	Não	Alterna visibilidade do painel
focus	(paneName)	Não	Foca um painel

Nomes de painéis: console, workspace, llminsight, secrets, taskmanager, history, searchIndex, store, queues, queueprocessor, mcphistory, terminal.

---

## g.html.* — utilitários HTML

Método	Assinatura	Async	Descrição
toMarkdown	(html, options?) → string	Não	Converte HTML para Markdown

HtmlToMarkdownOptions:

{
  githubFlavored?: boolean
  removeComments?: boolean
  smartHrefHandling?: boolean
  listBulletChar?: string
}