feat: bucle percibir->actuar — dom_click_ref/type_ref/hover_ref por #ref + auto-observe

app.md

@@ -2,8 +2,8 @@
 name: browser_mcp
 lang: go
 domain: infra
-version: 0.2.0
-description: "Servidor MCP que expone control total del navegador via CDP (36 tools: navegación, DOM, cookies, iframes, teclado/scroll, diálogos, estado de sesión, selección determinista de pestaña + lectura compacta texto/AX) reusando funciones del dominio browser del registry con un pool de conexiones CDP vivas. Por defecto opera sobre un Chrome aislado (puerto 9333) separado del navegador diario."
+version: 0.3.0
+description: "Servidor MCP que expone control total del navegador via CDP (39 tools: navegación, DOM, cookies, iframes, teclado/scroll, diálogos, estado de sesión, selección determinista de pestaña, lectura compacta texto/AX + bucle percibir→actuar por #ref con auto-observe) reusando funciones del dominio browser del registry con un pool de conexiones CDP vivas. Por defecto opera sobre un Chrome aislado (puerto 9333) separado del navegador diario."
 tags: [mcp, browser, cdp, automation, scraping]
 uses_functions:
   - chrome_launch_go_browser
@@ -42,6 +42,10 @@ uses_functions:
   - cdp_get_text_go_browser
   - cdp_connect_target_go_browser
   - cdp_perceive_outline_py_pipelines
+  - cdp_click_ref_go_browser
+  - cdp_type_ref_go_browser
+  - cdp_hover_ref_go_browser
+  - cdp_click_xy_human_go_browser
 uses_types: []
 framework: ""
 entry_point: "main.go"
@@ -100,7 +104,7 @@ podría manipular pestañas ajenas del usuario (banca, correo). Para evitarlo:
 - Para adjuntarte deliberadamente al navegador diario, pasa `port: 9222` explícito en cada
   tool. Hazlo solo con cuidado.
 
-## Tools (36)
+## Tools (39)
 
 ### Sesión (`tools_session.go`)
 - `browser_launch` (MUTA) — lanza Chrome con CDP. args: port, headless, user_data_dir, url.
@@ -141,6 +145,26 @@ podría manipular pestañas ajenas del usuario (banca, correo). Para evitarlo:
 - `dom_type` (MUTA) — escribe texto en el elemento enfocado. args: port, text.
 - `dom_find_by_text` — devuelve un selector CSS único para un texto visible. args: port, text.
 - `dom_wait_element` — espera a que aparezca un selector. args: port, selector, timeout_ms (default 10000).
+- `dom_click_ref` (MUTA) — click humanizado por `#ref` (backendDOMNodeId del outline de `page_perceive`) + auto-observe. args: port, ref.
+- `dom_type_ref` (MUTA) — enfoca el `#ref` y escribe texto + auto-observe. args: port, ref, text.
+- `dom_hover_ref` (MUTA) — hover humanizado por `#ref` + auto-observe. args: port, ref.
+
+#### Bucle percibir→actuar (por `#ref`)
+
+`page_perceive` devuelve un outline accionable donde cada elemento lleva un `#ref`
+estable (su `backendDOMNodeId`). Las tools `dom_click_ref` / `dom_type_ref` /
+`dom_hover_ref` actúan directamente sobre ese `#ref` — no necesitas resolver un
+selector CSS. Tras la acción esperan un settle breve (400ms) y **devuelven el
+outline actualizado** (auto-observe), cerrando el bucle percibir→actuar:
+
+```
+page_perceive   →  outline con #ref de cada elemento
+dom_click_ref   →  click humanizado + outline nuevo tras la acción
+dom_type_ref    →  escribe + outline nuevo
+```
+
+Las tools `*_ref` usan humanización por defecto (Bézier+jitter). Una política de
+sesión `fast`/`instant` para scraping masivo está pendiente (ver TODO en el código).
 
 ### Input (`tools_input.go`) — todas MUTA
 - `press_key` — presiona una tecla nombrada (Enter/Tab/Escape/ArrowDown/...). args: port, key.
@@ -205,6 +229,12 @@ Funciones del dominio `browser` que NO se exponen como tools en esta versión, c
 
 ## Capability growth log
 
+- v0.3.0 (2026-06-06) — Cierre del bucle percibir→actuar. Nuevas tools `dom_click_ref`,
+  `dom_type_ref`, `dom_hover_ref`: actúan sobre el `#ref` (backendDOMNodeId estable) del
+  outline de `page_perceive` con humanización por defecto (Bézier+jitter) y auto-observe
+  (devuelven el outline actualizado tras la acción). Refactor: la generación del outline
+  se extrajo a `deps.perceiveOutline`/`perceiveOutlineTab`, reusado por `page_perceive` y
+  por las tools `*_ref`. 36 → 39 tools.
 - v0.2.0 (2026-06-06) — P0 LLM-readiness. Seguridad: Chrome aislado por defecto (puerto 9333
   + perfil dedicado `<tmp>/browser_mcp_userdata`), separado del navegador diario en 9222.
   Nuevas tools: `tab_select` (selección determinista de pestaña por id/URL), `page_get_text`