feat(browser): auto-commit con 60 cambios

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

python/functions/browser/cdp_press_key.md

@@ -0,0 +1,80 @@
+---
+name: cdp_press_key
+kind: function
+lang: py
+domain: browser
+version: "1.0.0"
+purity: impure
+signature: "def cdp_press_key(key: str, *, port: int = 9222, target_url_substr: str = '', modifiers: int = 0, timeout_s: float = 10.0) -> dict"
+description: "Pulsa una tecla nombrada (Enter, Escape, Backspace, Tab, ArrowDown, Delete, ...) sobre el elemento enfocado de una pestana de un Chrome con remote debugging, via CDP Input.dispatchKeyEvent (rawKeyDown + keyUp). Primitiva de input CDP reutilizable: enviar mensajes (Enter en el composer de WhatsApp), cerrar overlays (Escape), navegar resultados (ArrowDown), borrar (Backspace) o combos con modificadores (Ctrl+A)."
+tags: [cdp, browser, automation, python, navegator]
+uses_functions: []
+uses_types: []
+returns: []
+returns_optional: false
+error_type: "error_go_core"
+imports: ["json", "urllib.request", "websocket"]
+params_schema:
+  params:
+    - name: key
+      desc: "Nombre canonico de la tecla a pulsar. Soportadas: Enter, Escape, Backspace, Tab, Delete, ArrowDown, ArrowUp, ArrowLeft, ArrowRight, Home, End. Una tecla no soportada devuelve ok=False sin tocar la red."
+    - name: port
+      desc: "Puerto de remote debugging de Chrome. Default 9222."
+    - name: target_url_substr
+      desc: "Substring que debe contener la URL del target (pestana). Si vacio, usa el primer target de tipo 'page'."
+    - name: modifiers
+      desc: "Bitmask de modificadores CDP combinables con OR: Alt=1, Ctrl=2, Meta/Cmd=4, Shift=8. Ej. Ctrl+Shift = 2|8 = 10. Default 0."
+    - name: timeout_s
+      desc: "Timeout en segundos para la conexion WebSocket. Default 10.0."
+  output: "dict {ok: bool, error: str}. ok=True si los eventos rawKeyDown+keyUp se emitieron sin error. Nunca lanza: errores de red/conexion/transport y teclas no soportadas se devuelven en 'error' con ok=False."
+tested: true
+tests: ["test_golden_enter_emite_rawkeydown_y_keyup_vk13", "test_edge_tecla_no_soportada_ok_false_sin_abrir_ws", "test_error_create_connection_lanza_ok_false"]
+test_file_path: "python/functions/browser/cdp_press_key_test.py"
+file_path: "python/functions/browser/cdp_press_key.py"
+---
+
+## Ejemplo
+
+```python
+import sys, os
+sys.path.insert(0, os.path.join("python", "functions"))
+from browser.cdp_press_key import cdp_press_key
+
+# Requiere un Chrome lanzado con --remote-debugging-port=9222
+# y una pestana de WhatsApp Web abierta con el composer enfocado y texto escrito.
+res = cdp_press_key("Enter", target_url_substr="whatsapp")  # envia el mensaje
+print(res["ok"], res["error"])
+
+# Combo con modificadores (Ctrl+A para seleccionar todo): Ctrl=2.
+cdp_press_key("Home", target_url_substr="whatsapp", modifiers=2)
+```
+
+O directo por CLI: `python3 python/functions/browser/cdp_press_key.py "Enter" "whatsapp"`.
+
+## Cuando usarla
+
+Cuando necesites enviar una pulsacion de tecla sobre la pestana **ya abierta** del
+navegador diario sin abrir ventana nueva ni darle foco al sistema: **Enter** para
+enviar (composer de WhatsApp), **Escape** para cerrar overlays/dialogos,
+**ArrowDown/ArrowUp** para navegar resultados de busqueda, **Backspace/Delete** para
+borrar, o combos con `modifiers` (Ctrl/Shift/Alt/Meta). Tipicamente **despues** de
+escribir con `cdp_type_chars_py_browser` para confirmar la accion. Es la primitiva de
+input sobre la que se construyen funciones `whatsapp_*_py_browser` y cualquier script
+que opere una pestana existente via CDP.
+
+## Gotchas
+
+- Actua sobre el elemento **enfocado** de la pagina: CDP `Input.dispatchKeyEvent` no
+  apunta a un selector, va al foco actual. Asegura el foco (clic o `el.focus()` via
+  `cdp_eval_py_browser`) antes de pulsar.
+- **Enter en WhatsApp Web envia el mensaje** (no inserta salto de linea). Para newline
+  dentro del composer usa Shift+Enter (`modifiers=8`) o no uses esta funcion para eso.
+- `modifiers` es el bitmask de CDP, no un string: Alt=1, Ctrl=2, Meta/Cmd=4, Shift=8;
+  combina con OR (ej. Ctrl+Shift = 10).
+- No se emite evento `char` aparte: el par `rawKeyDown`+`keyUp` con el
+  `windowsVirtualKeyCode` correcto (Enter=13) basta para disparar el envio en WhatsApp
+  (validado via `press_key` del MCP del navegador).
+- Requiere un Chrome lanzado con `--remote-debugging-port=9222` (o el puerto que pases).
+  Sin remote debugging, `GET /json` falla y devuelve `ok=False`.
+- Nunca lanza: errores de red, conexion WS, transport o tecla no soportada se reportan
+  en el campo `error` con `ok=False`.