feat(core): auto-commit con 10 cambios

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-06-06 13:20:36 +02:00
parent 3f6b652f3f
commit 029dbf57bd
10 changed files with 408 additions and 55 deletions
@@ -0,0 +1,51 @@
+---
+name: cdp_click_ref
+kind: function
+lang: go
+domain: browser
+version: "1.0.0"
+purity: impure
+signature: "func CdpClickRef(c *CDPConn, backendNodeID int, opts MouseHumanOpts) error"
+description: "Click humanizado (Bézier + jitter) sobre el elemento identificado por su #ref del AX outline. El #ref es el backendDOMNodeId estable del nodo DOM. Hace scroll al elemento si no está en viewport antes de calcular las coordenadas vía DOM.getBoxModel."
+tags: [cdp, browser, action, ref, humanized, navegator]
+uses_functions: [cdp_click_xy_human_go_browser]
+uses_types: []
+returns: []
+returns_optional: false
+error_type: "error_go_core"
+imports: []
+tested: false
+tests: []
+test_file_path: ""
+params:
+  - name: c
+    desc: "Conexión CDP activa al tab objetivo."
+  - name: backendNodeID
+    desc: "El #ref del AX outline = backendDOMNodeId estable del nodo DOM. Se obtiene de page_perceive / render_ax_outline."
+  - name: opts
+    desc: "Opciones de trayectoria humanizada (jitter, velocidad, curva Bézier). Zero-value da humanización por defecto."
+output: "nil si el click se completó; error si la conexión es nil, el nodo no tiene boxModel visible, o el click CDP falla."
+file_path: "functions/browser/cdp_click_ref.go"
+---
+
+## Ejemplo
+
+```go
+// Tras un page_perceive que devuelve outline con #ref=1234:
+conn, _ := CdpConnect(9222)
+err := CdpClickRef(conn, 1234, MouseHumanOpts{})
+if err != nil {
+    log.Fatal(err)
+}
+```
+
+## Cuando usarla
+
+Tras `page_perceive` / `render_ax_outline`, cuando el agente tiene el `#ref` de un elemento del outline y quiere hacer click sobre él sin necesitar un selector CSS — cierra el bucle percibir→actuar. Preferir sobre `CdpClickHuman` cuando el nodo viene del AX outline (más estable que un selector).
+
+## Gotchas
+
+- El `#ref` es un **backendDOMNodeId**, no el nodeId efímero del AX tree. Si la página recargó o navegó tras el snapshot, el ref puede estar muerto — re-percibir antes de actuar.
+- `DOM.getBoxModel` falla si el elemento no está en el DOM renderizado (display:none, fuera del shadow DOM accesible, o ya eliminado). El error describe la causa.
+- `DOM.scrollIntoViewIfNeeded` se invoca antes del cálculo de coordenadas pero su fallo se ignora (no fatal) — si el elemento no es scrollable al viewport el click puede caer en coordenadas incorrectas.
+- El click va por `CdpClickXYHuman` (Bézier): no despaches `Input.dispatchMouseEvent` crudo en código que use esta función.