---
name: cdp_new_tab_background
kind: function
lang: go
domain: browser
version: 1.0.0
purity: impure
signature: "func CdpNewTabBackground(host string, port int, startURL string) (CdpTab, error)"
description: "Abre una pestaña nueva via CDP Target.createTarget con background:true, sin activarla ni elevar la ventana del navegador (no roba el foco del WM). Drop-in sin-foco de CdpNewTab: misma firma y mismo CdpTab de retorno, pero usando el comando CDP browser-level en lugar del endpoint HTTP /json/new (que SI roba foco)."
tags: [browser, cdp, tabs, spawn, background, no-focus]
uses_functions: [cdp_list_tabs_go_browser]
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports: [fmt]
example: |
  tab, err := browser.CdpNewTabBackground("localhost", 9333, "https://example.com")
  if err == nil {
      fmt.Println("nueva tab en segundo plano id=", tab.ID)
  }
tested: true
tests: ["TestCdpNewTabBackground_closedPort", "TestCdpNewTabBackground_emptyStartURLClosedPort"]
test_file_path: "functions/browser/cdp_new_tab_background_test.go"
file_path: "functions/browser/cdp_new_tab_background.go"
notes: |
  - Usa los helpers privados del paquete: cdpGetWSURL (browser-level WS),
    cdpConnectWS, (*CDPConn).sendCDP y CdpListTabs. No reescribe el transporte CDP.
  - El cierre del WebSocket se hace con CdpDisconnect (solo suelta la sesion, deja
    el navegador vivo).
  - Resuelve el CdpTab completo via CdpListTabs buscando por targetId; si hay
    carrera y aun no aparece, devuelve un CdpTab minimo (id, type, url) como fallback.
documentation: |
  Alternativa a CdpNewTab cuando NO quieres que la ventana del navegador robe el
  foco del window manager — por ejemplo, mientras el usuario escribe en otra
  ventana. El endpoint HTTP /json/new no admite el parametro background, asi que
  CdpNewTab siempre eleva la ventana; esta funcion usa Target.createTarget con
  "background": true para crear la pestaña en segundo plano.
params:
  - name: host
    desc: "Host CDP donde escucha el navegador (vacio = localhost)."
  - name: port
    desc: "Puerto remote-debugging de Chrome/Chromium (ej. 9333)."
  - name: startURL
    desc: "URL inicial de la pestaña. Vacio = about:blank."
output: "CdpTab del target recien creado (id, webSocketDebuggerUrl, title, url, ...). Error si /json/version o el comando CDP fallan."
---

## Ejemplo

```go
// Abrir una pestaña en segundo plano sin robar el foco del usuario.
tab, err := browser.CdpNewTabBackground("localhost", 9333, "https://example.com")
if err != nil {
    log.Fatal(err)
}
fmt.Println("pestaña creada en background:", tab.ID, tab.URL)
```

## Cuando usarla

Cuando abras una pestaña por CDP y NO quieras que la ventana del navegador robe
el foco del WM (el usuario esta escribiendo en otra ventana). Alternativa
sin-foco a `CdpNewTab` / endpoint HTTP `/json/new`, que siempre eleva la ventana.

## Gotchas

- Funcion impura: abre un WebSocket al navegador y manda un comando CDP. Falla si
  el puerto no responde o el comando no devuelve `targetId`.
- El parametro `background` de `Target.createTarget` no aplica en MacOS (alli la
  pestaña se activa igual). Esto esta pensado para Linux/Chromium.
- Requiere conexion **browser-level** (`/json/version`), no page-level: por eso usa
  `cdpGetWSURL` y no la primera tab `page`.
- Si el navegador corre headless, el foco es irrelevante — `CdpNewTab` y esta
  funcion son equivalentes en ese caso.