Browser e DOM

`g.dom.*` — Azioni DOM

Metodo	Firma	Descrizione
`g.dom.click`	`(selector, options?) → Promise`	Fa clic su un elemento
`g.dom.enterText`	`(selector, value, options?) → Promise`	Digita testo in un input
`g.dom.selectOption`	`(selector, options?) → Promise`	Seleziona un’opzione in un elemento HTML `<select>` nativo per valore, etichetta (label) o indice a base zero
`g.dom.scrollTo`	`(selector, options?) → Promise`	Scorre fino a rendere visibile un elemento
`g.dom.pressKey`	`(key, options?) → Promise`	Preme un tasto della tastiera
`g.dom.highlight`	`(selector, durationMs?, options?) → Promise`	Evidenzia visivamente un elemento
`g.dom.waitForElement`	`(selector, options?) → Promise`	Attende un elemento usando MutationObserver (senza interrogazione periodica)
`g.dom.waitForDomStable`	`(options?) → Promise`	Attende che il DOM smetta di mutare per un periodo di quiete
`g.dom.waitForReady`	`(selector, options?) → Promise`	Attesa combinata elemento + stabilità DOM: la scelta pratica per applicazioni JavaScript a pagina singola (Single Page Applications)

ElementOptions (il parametro options per i metodi DOM):

{
  selectorType?: "css" | "xpath" | "text" | "text-contains"  // predefinito: "css"
  browserTabId?: string  // predefinito: scheda attiva
}

ClickOptions:

{
  selectorType?: "css" | "xpath" | "text" | "text-contains"
  browserTabId?: string
  mode?: "default" | "human"  // predefinito: input CDP deterministico; "human" usa movimento visibile del mouse
}

Usa la modalità di clic predefinita per automazioni stabili. Usa { mode: "human" } quando la pagina richiede movimento visibile del puntatore o comportamento del browser simile a un hover prima del clic.

SelectOptionOptions:

{
  value?: string          // valore dell'opzione da selezionare
  label?: string          // etichetta visibile dell'opzione da selezionare
  index?: number          // indice dell'opzione a base zero da selezionare
  selectorType?: "css" | "xpath"
  browserTabId?: string
}

Usa g.dom.selectOption per controlli <select> nativi. Per combobox, listbox e menu a discesa personalizzati visualizzati da framework, usa invece i controlli visibili della pagina con i metodi click/tastiera/attesa.

WaitForElementOptions:

{
  timeout?: number        // predefinito: 10000
  visible?: boolean       // richiede visibilità: offsetHeight > 0, non display:none (predefinito: false)
  selectorType?: "css" | "xpath"
  browserTabId?: string
}

WaitForDomStableOptions:

{
  timeout?: number        // predefinito: 15000
  quietPeriod?: number    // ms senza mutazioni DOM prima di dichiarare stabilità (predefinito: 500)
  browserTabId?: string
}

WaitForReadyOptions:

{
  timeout?: number        // predefinito: 15000; copre sia rilevamento elemento sia stabilità
  quietPeriod?: number    // ms senza mutazioni DOM dopo il rilevamento dell'elemento (predefinito: 500)
  selectorType?: "css" | "xpath"
  browserTabId?: string
}

`g.dom.*` — Estrazione contenuto

Metodo	Firma	Descrizione
`g.dom.extractContent`	`(selector, options?) → Promise<string>`	Estrae il contenuto testuale da un elemento
`g.dom.getElements`	`(selector, attributeNames, options?) → Promise<Record[]>`	Ottiene attributi dagli elementi corrispondenti
`g.dom.countElements`	`(selector, options?) → Promise<number>`	Conta gli elementi corrispondenti
`g.dom.getElementXPaths`	`(selector, options?) → Promise<string[]>`	Ottiene l’XPath per ogni elemento corrispondente

`g.page.*` — Ispezione pagina

Metodo	Firma	Descrizione
`g.page.getDom`	`(options?) → Promise<string>`	Ottiene l’HTML della pagina
`g.page.getPageSource`	`(options?) → Promise<string>`	Ottiene il sorgente grezzo della pagina
`g.page.getPageElements`	`(options?) → Promise<PageElement[]>`	Ottiene elementi strutturati della pagina (heading, link, pulsanti, input)
`g.page.executeJS`	`(script, options?) → Promise<any>`	Esegue JavaScript nella scheda del browser e restituisce il risultato del browser
`g.page.getUrl`	`(options?) → Promise<string>`	Ottiene l’URL della pagina corrente
`g.page.ocr`	`(options?) → Promise<OcrResult>`	Esegue OCR sul viewport o su una regione

g.page.executeJS() restituisce direttamente valori strutturati. Se l’espressione del browser restituisce un oggetto, array, numero, booleano, stringa o null, JavaScript e Janet ricevono il valore corrispondente. Non racchiudere snippet browser in JSON.stringify(...) per poi fare JSON.parse(...) nello script host, a meno che tu voglia trasportare intenzionalmente testo.

Gli snippet browser restituiscono l’ultima espressione valutata da WebView2. Approccio consigliato:

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

Usa testo JSON esplicito solo quando il risultato deve essere una stringa:

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        // per i link
  selector: string
  selectorType: string
  context: string     // "nav", "header", "footer", "main", "article"
  visibility: string  // "visible" o "suspicious"
  headingLevel: number
}

`g.nav.*` — Navigazione

Metodo	Firma	Descrizione
`g.nav.navigateToUrl`	`(url, options?) → Promise<NavigateResult>`	Naviga verso un URL, restituisce stato e intestazioni
`g.nav.blockRedirects`	`() → void`	Blocca tutti i reindirizzamenti lato server (301/302/307)
`g.nav.allowRedirects`	`() → void`	Ripristina il comportamento predefinito dei reindirizzamenti

NavigateOptions:

{
  waitForLoad?: boolean                   // predefinito: true
  browserTabId?: string
  stealth?: boolean | StealthOptions      // inietta patch anti-rilevamento prima degli script pagina
  detectRedirects?: boolean               // rileva reindirizzamenti JS/meta (predefinito: false)
}

StealthOptions — controllo granulare delle patch anti-rilevamento (tutte predefinite a true quando stealth è abilitato):

{
  webdriver?: boolean      // nasconde navigator.webdriver
  chromeRuntime?: boolean  // inietta window.chrome.runtime
  permissions?: boolean    // corregge Permissions.prototype.query per le notifiche
  plugins?: boolean        // inietta navigator.plugins con voci Chrome
  languages?: boolean      // garantisce che navigator.languages restituisca ["en-US", "en"]
}

NavigateResult:

{
  statusCode: number                    // codice stato HTTP (200, 301, 404, ecc.)
  headers: Record<string, string>       // intestazioni della risposta
  finalUrl?: string                     // URL effettivo dopo la navigazione (solo con detectRedirects)
  redirectDetected?: boolean            // true se l'URL finale differisce da quello richiesto
  metaRefresh?: string                  // contenuto di <meta http-equiv="refresh"> se trovato
}

`g.tabs.*` — Gestione schede

Metodo	Firma	Descrizione
`g.tabs.getTabs`	`() → TabInfo[]`	Ottiene tutte le schede aperte
`g.tabs.newBrowserTab`	`(options?) → Promise<string>`	Crea una nuova scheda, restituisce l’ID scheda
`g.tabs.closeTab`	`(tabId?) → Promise`	Chiude una scheda (predefinito: attiva)
`g.tabs.closeAllTabs`	`()`	Chiude tutte le schede
`g.tabs.closeOtherTabs`	`(tabId?)`	Chiude tutte le schede tranne quella specificata
`g.tabs.setActiveBrowserTab`	`(tabId)`	Passa a una scheda
`g.tabs.getActiveBrowserTab`	`() → string \| null`	Ottiene l’ID della scheda attiva
`g.tabs.getBrowserTabInfo`	`(tabId) → TabInfo`	Ottiene informazioni su una scheda specifica
`g.tabs.setBrowserTabName`	`(tabId, name)`	Rinomina una scheda
`g.tabs.findTabByUrl`	`(pattern) → TabInfo \| null`	Trova una scheda il cui URL contiene il pattern
`g.tabs.findTabByTitle`	`(pattern) → TabInfo \| null`	Trova una scheda il cui titolo contiene il pattern
`g.tabs.nextTab`	`()`	Passa alla scheda successiva
`g.tabs.prevTab`	`()`	Passa alla scheda precedente
`g.tabs.moveTab`	`(tabId, index)`	Sposta una scheda in una posizione diversa

TabInfo:

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

`g.screenshot.*` — Screenshot

Metodo	Firma	Descrizione
`g.screenshot.screenshot`	`(path?) → Promise<string>`	Cattura il viewport, restituisce base64 o percorso file
`g.screenshot.screenshotElement`	`(selector, path?, options?) → Promise<string>`	Cattura un elemento specifico
`g.screenshot.screenshotFullPage`	`(path?, options?) → Promise<string>`	Cattura l’intera pagina scorrevole

ScreenshotFullPageOptions:

{
  clean?: boolean       // rimuove overlay (predefinito: false)
  browserTabId?: string
}

`g.viewport.*` — Viewport

Metodo	Firma	Descrizione
`g.viewport.setViewport`	`(options)`	Imposta la dimensione del viewport (per nome preset o dimensioni personalizzate)
`g.viewport.getViewport`	`(tabId?) → ViewportInfo \| null`	Ottiene informazioni sul viewport corrente
`g.viewport.getViewportPresets`	`() → string[]`	Elenca i nomi dei preset disponibili

ViewportOptions:

{
  tabId?: string
  preset?: string    // es. "iPhone 12", "Desktop"
  width?: number     // larghezza personalizzata in pixel
  height?: number    // altezza personalizzata in pixel
}

Guida usa due modalità viewport:

I preset desktop come Full HD, QHD e 4K UHD usano adattamento al pannello, così layout desktop grandi possono essere verificati dentro una scheda più piccola.
I preset mobile e tablet come Mobile M e Tablet Portrait usano emulazione dispositivo, inclusi larghezza viewport responsiva, fattore di scala del dispositivo e comportamento touch.

Le dimensioni personalizzate restano in modalità desktop adattata al pannello per impostazione predefinita.

ViewportInfo include metadati sulla modalità:

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

`g.layout.*` — Layout documento

Dispone le schede del browser in pannelli divisi.

Metodo	Firma	Async	Descrizione
`single`	`()`	No	Collassa in un solo pannello
`horizontal`	`(n?)`	No	Layout affiancato
`vertical`	`(n?)`	No	Layout impilato
`quad`	`()`	No	Griglia 2x2
`grid`	`(rows, cols)`	No	Layout a griglia personalizzata
`moveToPane`	`(docId, paneIndex)`	No	Sposta un documento in un pannello specifico
`focusPane`	`(paneIndex)`	No	Porta il focus su un pannello
`getPanes`	`() → PaneInfo[]`	No	Ottiene tutti i pannelli e i relativi documenti
`arrange`	`(docIds)`	No	Dispone documenti specifici
`arrangeByPattern`	`(urlPattern)`	No	Dispone documenti che corrispondono a un pattern URL

`g.clipboard.*` — Appunti (Clipboard)

Metodo	Firma	Async	Descrizione
`copy`	`(text)`	No	Copia testo negli appunti
`paste`	`() → string`	No	Legge testo dagli appunti
`copyElement`	`(selector, options?) → Promise<string>`	Sì	Copia il contenuto testuale di un elemento

`g.pane.*` — Visibilità pannelli

Controlla i pannelli dell’interfaccia di Guida dagli script.

Metodo	Firma	Async	Descrizione
`show`	`(paneName)`	No	Mostra un pannello
`hide`	`(paneName)`	No	Nasconde un pannello
`toggle`	`(paneName)`	No	Alterna la visibilità di un pannello
`focus`	`(paneName)`	No	Porta il focus su un pannello

Nomi dei pannelli: console, workspace, llminsight, secrets, taskmanager, history, searchIndex, store, queues, queueprocessor, mcphistory, terminal.

`g.html.*` — Utilità HTML

Metodo	Firma	Async	Descrizione
`toMarkdown`	`(html, options?) → string`	No	Converte HTML in Markdown

HtmlToMarkdownOptions:

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

Browser e DOM

g.dom.* — Azioni DOM

g.dom.* — Estrazione contenuto

g.page.* — Ispezione pagina

g.nav.* — Navigazione

g.tabs.* — Gestione schede

g.screenshot.* — Screenshot

g.viewport.* — Viewport

g.layout.* — Layout documento

g.clipboard.* — Appunti (Clipboard)

g.pane.* — Visibilità pannelli

g.html.* — Utilità HTML