Navigateur et DOM

g.dom.* — actions DOM

Méthode	Signature	Description
g.dom.click	(selector, options?) → Promise	Clique sur un élément
g.dom.enterText	(selector, value, options?) → Promise	Saisit du texte dans un champ
g.dom.selectOption	(selector, options?) → Promise	Sélectionne une option dans un élément HTML <select> natif par valeur, libellé ou index à partir de zéro
g.dom.scrollTo	(selector, options?) → Promise	Fait défiler jusqu’à rendre un élément visible
g.dom.pressKey	(key, options?) → Promise	Appuie sur une touche du clavier
g.dom.highlight	(selector, durationMs?, options?) → Promise	Met visuellement un élément en évidence
g.dom.waitForElement	(selector, options?) → Promise	Attend un élément avec MutationObserver, sans polling
g.dom.waitForDomStable	(options?) → Promise	Attend que le DOM cesse de muter pendant une période calme
g.dom.waitForReady	(selector, options?) → Promise	Attente combinée élément + stabilité DOM, le choix habituel pour les SPA

ElementOptions, paramètre options des méthodes 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
}

Utilisez le mode de clic par défaut pour une automatisation stable. Utilisez { mode: "human" } lorsque la page a besoin d’un mouvement visible du pointeur ou d’un comportement de type survol avant le 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
}

Utilisez g.dom.selectOption pour les contrôles <select> natifs. Pour les comboboxes, listboxes et listes déroulantes rendues par des frameworks, utilisez les contrôles visibles de la page avec les méthodes click, clavier et 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.* — extraction de contenu

Méthode	Signature	Description
g.dom.extractContent	(selector, options?) → Promise<string>	Extrait le contenu texte d’un élément
g.dom.getElements	(selector, attributeNames, options?) → Promise<Record[]>	Récupère les attributs des éléments correspondants
g.dom.countElements	(selector, options?) → Promise<number>	Compte les éléments correspondants
g.dom.getElementXPaths	(selector, options?) → Promise<string[]>	Récupère le XPath de chaque élément correspondant

---

g.page.* — inspection de page

Méthode	Signature	Description
g.page.getDom	(options?) → Promise<string>	Récupère le HTML de la page
g.page.getPageSource	(options?) → Promise<string>	Récupère le source brut de la page
g.page.getPageElements	(options?) → Promise<PageElement[]>	Récupère les éléments structurés de la page : titres, liens, boutons, champs
g.page.executeJS	(script, options?) → Promise<any>	Exécute du JavaScript dans l’onglet et renvoie le résultat navigateur
g.page.getUrl	(options?) → Promise<string>	Récupère l’URL courante
g.page.ocr	(options?) → Promise<OcrResult>	Lance l’OCR sur le viewport ou une région
g.page.profileDocument	(options?) → Promise<DocumentProfileResult>	Mesure structure et empreintes exactes dans des limites déclarées, sans classer la page
g.page.profileVisual	(options) → Promise<VisualProfileResult>	Mesure une navigation et un viewport précis avec métriques et signatures visuelles bornées
g.page.compareVisualProfiles	(left, right) → VisualProfileComparisonResult	Compare des profils compatibles sans décider si la page est valide

Le profil du document fournit les nombres de noeuds, la profondeur, les longueurs du texte visible et du titre, les éléments sémantiques, les empreintes SHA-256 exactes, les limites et les indicateurs de troncature. Le profil visuel exige le navigationId renvoyé par la navigation et la taille attendue du viewport. Ce sont des mesures neutres: une page presque blanche, un DOM réduit ou une grande distance ne prouvent à eux seuls ni blocage, ni malformation, ni validité. Vérifiez d’abord les troncatures et le diagnostic de compatibilité.

g.page.executeJS() renvoie directement des valeurs structurées. Si l’expression navigateur renvoie un objet, tableau, nombre, booléen, chaîne ou null, JavaScript et Janet reçoivent la valeur correspondante. N’enveloppez pas les snippets navigateur dans JSON.stringify(...) puis JSON.parse(...) côté script hôte sauf si vous voulez vraiment transporter du texte.

Les snippets navigateur renvoient la dernière expression évaluée par WebView2. Préférez :

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

Utilisez du texte JSON explicite seulement lorsque le résultat lui-même doit être une chaîne :

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.* — navigation

Méthode	Signature	Description
g.nav.navigateToUrl	(url, options?) → Promise<NavigateResult>	Navigue et ne renvoie que les faits WebView2 observés par Guida
g.nav.blockRedirects	() → void	Bloque toutes les redirections côté serveur (301/302/307)
g.nav.allowRedirects	() → void	Rétablit le comportement de redirection par défaut

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 — contrôle fin des correctifs anti-détection, tous à true par défaut lorsque stealth est activé :

{
  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 :

{
  version: number
  requestedUrl: string
  finalUrl: string | null
  navigationId: string | null
  started: boolean
  completionObserved: boolean
  contentLoadingObserved: boolean
  navigationSucceeded: boolean | null
  statusCode: number | null
  statusSource: "navigationCompleted" | null
  webErrorStatus: string | null
  redirectDetected: boolean
  metaRefresh: string | null
}

Les faits inconnus ou non observés valent null. Avec waitForLoad: false, Guida rend la main après le démarrage: fin, statut HTTP et réussite restent donc inconnus. statusCode provient uniquement de l’événement NavigationCompleted correspondant; le résultat ne contient pas les en-têtes HTTP.

---

g.tabs.* — gestion des onglets

Méthode	Signature	Description
g.tabs.getTabs	() → TabInfo[]	Récupère tous les onglets ouverts
g.tabs.newBrowserTab	(options?) → Promise<string>	Crée un nouvel onglet et renvoie son ID
g.tabs.closeTab	(tabId?) → Promise	Ferme un onglet, par défaut l’onglet actif
g.tabs.closeAllTabs	()	Ferme tous les onglets
g.tabs.closeOtherTabs	(tabId?)	Ferme tous les onglets sauf celui indiqué
g.tabs.setActiveBrowserTab	(tabId)	Bascule vers un onglet
g.tabs.getActiveBrowserTab	() → string | null	Récupère l’ID de l’onglet actif
g.tabs.getBrowserTabInfo	(tabId) → TabInfo	Récupère les informations d’un onglet
g.tabs.setBrowserTabName	(tabId, name)	Renomme un onglet
g.tabs.findTabByUrl	(pattern) → TabInfo | null	Trouve un onglet dont l’URL contient le motif
g.tabs.findTabByTitle	(pattern) → TabInfo | null	Trouve un onglet dont le titre contient le motif
g.tabs.nextTab	()	Passe à l’onglet suivant
g.tabs.prevTab	()	Passe à l’onglet précédent
g.tabs.moveTab	(tabId, index)	Déplace un onglet vers une autre position

TabInfo :

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

---

g.screenshot.* — captures d’écran

Méthode	Signature	Description
g.screenshot.screenshot	(path?) → Promise<string>	Capture le viewport et renvoie du base64 ou un chemin de fichier
g.screenshot.screenshotElement	(selector, path?, options?) → Promise<string>	Capture un élément précis
g.screenshot.screenshotFullPage	(path?, options?) → Promise<string>	Capture toute la page défilable

ScreenshotFullPageOptions :

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

---

g.viewport.* — viewport

Méthode	Signature	Description
g.viewport.setViewport	(options)	Définit la taille du viewport, par preset ou dimensions personnalisées
g.viewport.getViewport	(tabId?) → ViewportInfo | null	Récupère les informations du viewport courant
g.viewport.getViewportPresets	() → string[]	Liste les noms 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 utilise deux modes de viewport :

• Les presets desktop comme Full HD, QHD et 4K UHD utilisent une mise à l’échelle fit-to-pane pour réviser de grands layouts desktop dans un panneau d’onglet plus petit.
• Les presets mobile et tablette comme Mobile M et Tablet Portrait utilisent l’émulation d’appareil, avec largeur responsive, device scale factor et comportement tactile.

Les dimensions personnalisées restent en mode desktop fit par défaut.

ViewportInfo inclut les métadonnées de mode :

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

---

g.layout.* — disposition des documents

Arrange les onglets de navigateur en panneaux fractionnés.

Méthode	Signature	Async	Description
single	()	Non	Réduit à un seul panneau
horizontal	(n?)	Non	Disposition côte à côte
vertical	(n?)	Non	Disposition empilée
quad	()	Non	Grille 2x2
grid	(rows, cols)	Non	Disposition en grille personnalisée
moveToPane	(docId, paneIndex)	Non	Déplace un document vers un panneau précis
focusPane	(paneIndex)	Non	Donne le focus à un panneau
getPanes	() → PaneInfo[]	Non	Récupère tous les panneaux et leurs documents
arrange	(docIds)	Non	Arrange des documents précis
arrangeByPattern	(urlPattern)	Non	Arrange les documents dont l’URL correspond à un motif

---

g.clipboard.* — presse-papiers

Méthode	Signature	Async	Description
copy	(text)	Non	Copie du texte dans le presse-papiers
paste	() → string	Non	Lit le texte du presse-papiers
copyElement	(selector, options?) → Promise<string>	Oui	Copie le contenu texte d’un élément

---

g.pane.* — visibilité des panneaux

Contrôle les panneaux d’interface de Guida depuis les scripts.

Méthode	Signature	Async	Description
show	(paneName)	Non	Affiche un panneau
hide	(paneName)	Non	Masque un panneau
toggle	(paneName)	Non	Bascule la visibilité d’un panneau
focus	(paneName)	Non	Donne le focus à un panneau

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

---

g.html.* — utilitaires HTML

Méthode	Signature	Async	Description
toMarkdown	(html, options?) → string	Non	Convertit du HTML en Markdown

HtmlToMarkdownOptions :

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