fn_registry/dev/issues/0070-browser-helpers-global-roadmap.md

id, title, status, priority, created, related_apps, related_issues_app

id	title	status	priority	created	related_apps	related_issues_app
0070	Funciones globales del registry para control de navegador (find by text, click by text, scroll, HAR, jsonld, opengraph, ...)	pending	medium	2026-05-09	navegator_dashboard graph_explorer	navegator/0001 graph_explorer/0038

Contexto

functions/browser/ (Go) tiene hoy 12 primitivas CDP de bajo nivel: cdp_connect, cdp_navigate, cdp_evaluate, cdp_get_html, cdp_screenshot, cdp_click (por selector CSS), cdp_type_text, cdp_wait_load, cdp_wait_element, cdp_set_cookie, cdp_close, chrome_launch. Todas reutilizables, todas testeadas.

Estas primitivas son suficientes para muchos casos pero siguen siendo bajo nivel: el consumidor (cdp-cli, navegator_dashboard, agentes) tiene que componer manualmente patrones que se repiten una y otra vez. Falta una capa intermedia de funciones de mas alto nivel que resuelvan tareas reales sin que cada caller las re-componga.

Objetivo

Ampliar functions/browser/ (Go preferentemente, Python cuando aplique) con primitivas componibles que resuelvan los patrones recurrentes:

1. Localizacion robusta de elementos: por texto visible, por XPath, por aria-label.
2. Acciones combinadas: click por texto, fill form, submit, scroll-to, wait-navigation.
3. Captura estructurada: HAR, jsonld, opengraph, meta tags, schema.org.
4. Navegacion segura: navegacion + wait + retry + screenshot diff.
5. Multi-tab / multi-instance: enumerar tabs de N instancias, copiar cookie entre profiles.

Cualquier app del registry que controle browsers (navegator_dashboard, cdp-cli, graph_explorer, futuras) consume esta capa en vez de reimplementar.

Funciones propuestas (lista inicial)

Todas en functions/browser/. Lenguaje preferido entre parentesis. Pureza siempre impure (todas tocan red/IO).

Localizacion / queries

ID	Que hace
cdp_find_by_text_go_browser	Devuelve selector CSS unico del primer elemento cuyo innerText contiene un texto dado. Filtros: tag, case_sensitive, exact.
cdp_find_all_by_text_go_browser	Como el anterior pero retorna lista de selectores.
cdp_find_by_xpath_go_browser	Equivalente con XPath.
cdp_find_by_aria_go_browser	Por aria-label o role. Util en SPAs accesibles.
cdp_get_attribute_go_browser	<selector>.getAttribute(name).
cdp_count_elements_go_browser	document.querySelectorAll(sel).length.

Acciones

ID	Que hace
cdp_click_text_go_browser	find_by_text + click. Errores claros si no encuentra.
cdp_fill_form_go_browser	Recibe map[selector]value, hace click + type por cada uno.
cdp_submit_form_go_browser	Click en boton submit + wait_navigation.
cdp_scroll_to_go_browser	selector.scrollIntoView({block:'center'}) + verifica que esta en viewport.
cdp_press_key_go_browser	Input.dispatchKeyEvent con tecla nombrada (Enter, Tab, Escape, ArrowDown).
cdp_hover_go_browser	Input.dispatchMouseEvent mouseMoved sobre el elemento.

Esperas robustas

ID	Que hace
cdp_wait_navigation_go_browser	Espera Page.frameNavigated + Page.loadEventFired con timeout.
cdp_wait_text_go_browser	Espera a que aparezca un texto en cualquier sitio del DOM.
cdp_wait_url_go_browser	Espera a que location.href matchee un regex.
cdp_wait_idle_go_browser	Espera a que la red este idle N ms (Network.* events).

Captura estructurada

ID	Que hace
cdp_har_record_go_browser	Subscribe Network.* durante una accion, retorna HAR JSON estandar.
extract_jsonld_py_browser	Parse <script type="application/ld+json"> del HTML.
extract_opengraph_py_browser	Parse <meta property="og:*">.
extract_meta_basic_py_browser	Title, description, canonical, lang, charset.
extract_schema_org_py_browser	Microdata itemtype="https://schema.org/...".
extract_forms_py_browser	Lista forms del HTML con campos, action, method.
cdp_dump_cookies_go_browser	Network.getAllCookies → JSON.
cdp_screenshot_element_go_browser	Screenshot recortado al bounding box del selector.

Multi-tab / multi-instance

ID	Que hace
cdp_list_tabs_go_browser	GET /json → lista parseada de tabs.
cdp_focus_tab_go_browser	POST /json/activate/{id}.
cdp_close_tab_go_browser	POST /json/close/{id}.
cdp_new_tab_go_browser	POST /json/new?url=....
cdp_copy_cookies_go_browser	Lee cookies de un profile, las pone en otro (ambos via CDP).

Composiciones (pipelines)

ID	Que hace
browser_login_form_pipeline	navigate + wait + fill_form + submit + wait_navigation + dump_cookies. Util para pre-logins en perfiles aislados.
browser_screenshot_diff_pipeline	navigate + screenshot + comparar contra golden + reportar.
crawl_seeded_pipeline	navigate seeds + extract links + push a queue + dedup + extract elegido.

Criterios de calidad para añadir una funcion

Antes de delegar a fn-constructor:

• Patron real recurrente, no especulativo. Si solo lo usa un caller hoy, esperar.
• API simple: max 5 parametros con valores por defecto sensatos.
• Tests obligatorios contra Chrome local (env-gated, no CI default — ver cdp_*_test.go actuales).
• Documentacion .md con ejemplo invocacion + caso de uso real (que app/agente la consume).
• Sin estado global: cada llamada recibe *CDPConn, no asume singleton.

Estrategia de adopcion

Por demanda, no anticipado:

1. Cuando una capa del dashboard (navegator/0001) o un enricher de graph_explorer requiera componer un patron, primero buscar si ya existe en el registry.
2. Si no existe y se usa dos veces o aparece en TODO, abrir sub-issue de este 0070 con la firma propuesta.
3. Delegar a fn-constructor con los criterios de arriba.
4. Migrar a la nueva funcion el caller que la pidio + cualquier otro que estuviera reimplementando lo mismo.

No precrear todas a la vez — riesgo de funciones zombies que nadie usa.

Sub-issues iniciales (los que el dashboard v2 va a pedir)

• 0070a — cdp_find_by_text_go_browser + cdp_click_text_go_browser. Bloquea Tab Detail y Recipes.
• 0070b — cdp_har_record_go_browser. Bloquea Network panel.
• 0070c — extract_jsonld_py_browser + extract_opengraph_py_browser. Bloquea /extract/structured.
• 0070d — cdp_list_tabs_go_browser + cdp_new_tab_go_browser. Bloquea Tabs panel del dashboard.

Resto se abren cuando se necesiten.

Relacion con cdp-cli

Cuando una funcion nueva se añade al registry, cdp-cli (projects/osint_graph/apps/graph_explorer/cdp-cli/) gana un subcomando que la envuelve. Asi tanto el dashboard (in-process) como agentes/scripts (subprocess) tienen acceso. Patron ya establecido con las 10 funciones actuales.

Riesgos

Riesgo	Mitigacion
Funciones zombies si las pre-creamos	Solo crear cuando hay 2 callers o demanda real.
Fragmentacion: tener 50 funciones de queries similares	Revision de overlap antes de delegar a fn-constructor. Preferir parametros sobre nuevas funciones.
Tests dependen de Chrome local — flakiness en CI	Tag slow + env-gate. CI nocturno opcional.
Diferencias entre Chrome versions (selectores cambian, eventos rebrandean)	Tests cubren la API CDP estable, no el DOM de sitios externos.

Definicion de hecho

Cuando navegator_dashboard v3 cierre, las funciones invocadas por sus endpoints /extract/*, /crawl, panel Network, panel Tabs y panel Tab Detail viven todas en functions/browser/ o python/functions/browser/ (segun lenguaje), no inline en el dashboard. El dashboard es 100% orquestador.