Coalescencia de entradas CDP para una interacción hover coherente

Los clientes CDP suelen enviar un comando de movimiento de mouse cada vez. El cliente envía un punto, espera a que termine y después envía el siguiente. La secuencia es controlable, pero un hover automatizado rápido puede llegar a la cola de eventos del navegador de forma distinta a un flujo de movimiento nativo. Una página puede observar diferencias en el tiempo de los eventos y en su entrega.

BotBrowser ofrece una opción por contexto para los flujos que necesitan una ruta hover más coherente: --bot-cdp-coalesce. Está desactivada por defecto. Al activarla en un BrowserContext, BotBrowser acepta una secuencia corta de movimientos de mouse sin botón, conserva su orden y la reenvía como un lote serial pequeño. El motor del navegador sigue decidiendo los eventos finales de la página y cualquier coalescencia nativa.

Empieza con el valor predeterminado

La mayoría de las automatizaciones no necesitan una opción especial. Déjala desactivada cuando el flujo usa clicks, formularios, teclado, desplazamiento, arrastrar y soltar, gestos touch o lápiz. El valor predeterminado conserva el comportamiento normal de finalización de CDP y no cambia un flujo que ya cumple sus requisitos.

Actívala solo para un contexto que envía movimientos hover frecuentes por CDP y necesita que el navegador reciba esos puntos con un pequeño solapamiento. Una revisión de tooltips, un menú que se abre al acercar el puntero, una tarjeta hover o una interfaz de escritorio sensible a la posición son ejemplos adecuados. La opción pertenece al contexto, por lo que otro contexto del mismo navegador puede conservar el valor predeterminado.

La opción no aleatoriza la trayectoria ni crea puntos. El cliente sigue eligiendo coordenadas y orden. BotBrowser solo controla cómo se reenvían los movimientos aceptados durante una ventana breve. La última coordenada sigue siendo la posición final que ve la página.

Configura un BrowserContext

Establece --bot-cdp-coalesce en la superficie de configuración de contexto que ofrece tu lanzador de BotBrowser. Hazlo antes de crear la primera página o worker. Guarda el valor junto con la versión del navegador, el profile y el paquete de automatización para reproducir la misma política en una validación posterior.

El flag sin valor activa el comportamiento. --bot-cdp-coalesce=true también lo activa. Usa --bot-cdp-coalesce=false cuando una plantilla de despliegue pueda añadir el flag y un contexto deba conservar el valor predeterminado. Trátalo como configuración de identidad del contexto y no planifiques cambiarlo mientras el contexto ya atiende páginas.

Cuando un proceso crea varios contextos, asigna un valor deliberado a cada uno. Un contexto activado no activa la opción para sus hermanos y un contexto nuevo necesita su propio valor. Así puedes comparar el mismo flujo con y sin la opción sin iniciar procesos de navegador ajenos.

Haz visible el ajuste en el lanzador, cerca del profile y de la declaración del contexto. Regístralo en los metadatos de la ejecución. Los scripts de página no pueden controlar cuándo termina un comando CDP ni cómo la cola recibe el evento, por lo que no sustituyen la opción.

Qué movimientos se agrupan

Solo entra en el lote el movimiento hover de mouse sin botón. El puntero no tiene un botón presionado, no está en modo de movimiento relativo y el evento es un movimiento normal. Esto cubre el acercamiento a un objetivo, la inspección de un estado hover y el recorrido por una interfaz de escritorio.

Quedan fuera del lote:

• Pulsaciones y liberaciones de botones.
• Movimiento durante un arrastre activo y sus transiciones.
• Rueda.
• Teclado y entrada de texto.
• Touch.
• Lápiz.
• Movimiento relativo del mouse.

Estos límites conservan el significado de las acciones discretas y de otros dispositivos. Un click mantiene su estado y su finalización normales. Un arrastre mantiene el orden de sus transiciones. La rueda mantiene sus deltas y su tiempo. La opción no cambia esas rutas.

Los modificadores y el estado del botón también importan. Un movimiento con un botón presionado forma parte de un arrastre u otra acción de puntero y sigue la ruta normal. De esta forma el lote hover no cruza el límite entre apuntar a un control y actuar sobre él.

Cómo se entrega el lote

El contexto acepta una secuencia corta de movimientos elegibles y reenvía los puntos en su orden original. El lote está acotado, así que una página bloqueada o una secuencia inusualmente larga no crea una cola ilimitada. También dura poco tiempo y se limita al movimiento de alta frecuencia, no es un buffer general de entrada.

Cada comando CDP conserva un único resultado de finalización. Un comando hover aceptado puede terminar cuando el contexto lo acepta para reenvío. La página recibe el movimiento por la ruta de entrada del navegador. Las entradas no hover siguen usando la confirmación normal del browser. Si otra entrada necesita cruzar esa ruta, el movimiento hover pendiente se deja avanzar primero para conservar el orden visible.

El motor decide cómo los puntos se convierten en eventos de página. Puede exponer un evento principal y eventos hijos coalescidos cuando su planificación combina movimientos cercanos. BotBrowser no inventa hijos, no reescribe marcas de tiempo ni sustituye la coordenada final. El resultado sigue ligado al manejo del navegador, mientras el contexto aporta el solapamiento que las llamadas CDP seriales no consiguen por sí solas.

El número exacto de eventos puede variar por planificación del navegador, trabajo de la página, carga del host y flujo del cliente. No pruebes un número fijo. Comprueba el resultado visible, el orden, la finalización de los comandos y la posición final.

Llamadas CDP seriales y comportamiento de página

Las integraciones con Puppeteer y Playwright suelen esperar cada llamada antes de iniciar la siguiente. Es un contrato útil para clicks y acciones discretas. En una trayectoria hover larga, esperar cada punto impide que varios movimientos estén a la vez en la cola del navegador.

Con la opción activada, el cliente puede conservar su estilo serial. El contexto acepta un grupo corto de movimientos hover y lo reenvía en orden. No hace falta generar otra trayectoria, añadir esperas aleatorias ni inyectar eventos pointer desde la página. Las coordenadas y el control existentes siguen siendo la fuente de la interacción.

El cambio afecta a la entrega, no a la calidad de la trayectoria. Un recorrido escaso sigue siendo escaso y un salto brusco sigue presente. Si la página necesita una secuencia concreta, ajusta coordenadas y tiempos del cliente por separado y valida con la política real del despliegue.

La lógica de la aplicación también permanece igual. Un tooltip que requiere permanencia sigue requiriéndola. Un menú que exige atravesar una región sigue necesitando esa región. La coalescencia ayuda a entregar un flujo denso en una cola parecida a la del navegador, pero no reemplaza las reglas de la aplicación.

Separa acciones y movimiento

Usa un paso hover para llegar a un control y después un click normal para activarlo. No dependas del agrupamiento hover para transportar una transición de botón. En arrastrar y soltar, conserva toda la secuencia en la ruta normal y valida el resultado de soltar por separado.

La separación facilita leer los problemas. Si no aparece el tooltip, revisa la trayectoria, la geometría del objetivo y el estado de página. Si el click no activa el control, revisa foco, hit testing y secuencia. Si el arrastre no termina, revisa origen, destino y aceptación de la aplicación. Un ajuste no debe explicar todos los problemas de puntero.

Aislamiento y ciclo de vida

La opción pertenece al BrowserContext. Contexto A puede tenerla activada y contexto B desactivada aunque compartan proceso. No se filtra a otro target, página, worker o contexto nuevo.

Cierra el contexto cuando termine su trabajo. Si una página o target se sustituye durante el movimiento, el movimiento viejo no debe continuar hacia el target nuevo. Empieza un flujo nuevo con el estado de página nuevo y conserva la política solo cuando el flujo lo exige.

La navegación es otro límite útil. No supongas que un hover iniciado en un documento explica el puntero en el documento reemplazado. Espera a que la nueva página esté lista y ejecuta el movimiento que exige su interfaz. La opción conserva el orden dentro de su ruta, no el estado de aplicación entre navegaciones.

Al recrear un contexto, aplica de nuevo la opción. Una plantilla de proceso puede facilitar la repetición, pero sigue siendo una decisión por contexto. Esto importa al reutilizar un proceso para cuentas, tenants o sesiones de prueba autorizadas distintas.

Validación práctica

Usa una página controlada o una ruta de prueba aprobada con tooltip, menú hover o tarjeta hover. Debe mostrar un cambio visible cuando el puntero llega al objetivo. No hace falta instrumentación privada ni una receta de detección.

Ejecuta el mismo flujo dos veces: crea un contexto con la opción desactivada, recorre la misma ruta, registra el estado hover y la posición final; después crea otro contexto con la opción activada y repite exactamente la ruta. Conserva constantes la versión del navegador, profile, viewport, estado de página, paquete cliente y lista de coordenadas. Cambia una sola variable.

En un flujo de producción, añade un click después del estado hover y verifica la página resultante. Incluye un control que no dependa de hover, como un campo de formulario o un botón normal, para confirmar que el resto sigue su ruta estándar. Añade comprobaciones de arrastre, rueda, touch o lápiz solo si el flujo las usa.

El éxito significa que el estado hover es alcanzable, el orden es correcto, cada comando tiene un resultado de finalización y la coordenada final no se pierde. No significa que cada ejecución produzca la misma lista coalescida ni el mismo número de eventos.

Compatibilidad y resolución de problemas

La opción afecta a movimientos hover de mouse entregados por CDP. No cambia identidad del navegador, red, cookies, almacenamiento, permisos, viewport ni datos del profile. Los flujos móviles deben probar touch con un viewport móvil, los de lápiz deben usar lápiz y los de movimiento relativo deben conservar su ruta normal.

Si no ves efecto, confirma que el contexto recibió el flag antes de su primera página, que el movimiento es hover de mouse normal y que la página usa realmente ese estado. Click, arrastre, rueda, touch, lápiz y movimiento relativo están fuera del alcance.

Si cambia el número de eventos entre ejecuciones, compara estado hover, orden, finalizaciones y coordenada final. Si dos contextos difieren, revisa valor explícito, profile, versión del navegador, viewport, estado de página y lista de coordenadas. La finalización CDP y la preparación visible de la aplicación son condiciones distintas, así que espera la señal de página que el flujo necesita.

--bot-cdp-coalesce ofrece una elección clara para una sola clase de interacción. Está desactivado por defecto. Actívalo en un contexto que envía movimiento hover denso y se beneficia de un batching serial breve; deja las demás entradas en sus rutas normales y registra el valor junto con la configuración del contexto.