chocolatito-code 1.0.0 → 1.2.0

package/extension/background.js

@@ -13,18 +13,120 @@
 // todas pueden trabajar.
 const WS_PORTS = [8787, 8788, 8789, 8790];
 const GROUP_TITLE = "Chocolatito Code";
+const VERSION = "1.2.0";
 
-/** puerto -> { socket, delay, timer } */
+/**
+ * Tope de un comando dentro de la extension.
+ *
+ * La CLI ya tiene el suyo, pero el suyo solo hace que ella deje de esperar: la
+ * accion se queda corriendo aqui y puede llegar tarde, cuando el modelo ya ha
+ * pedido otra cosa. Cortando de este lado, lo que la CLI recibe es un error
+ * explicable en vez de un silencio.
+ */
+const TIMEOUT_COMANDO_MS = 45000;
+
+/** puerto -> { socket, delay, timer, state, sessionId, reconectando } */
 const links = new Map();
 
-/** ref -> { tabId, frameId }, para resolver despues los clics. */
-const refIndex = new Map();
-let workingTabId = null;
-let groupId = null;
+/** Paginas donde Chrome no deja entrar a ninguna extension. */
+const ESQUEMAS_VETADOS = /^(chrome|edge|about|devtools|view-source|chrome-untrusted|chrome-search|chrome-error):/i;
+const TIENDAS_VETADAS = /^https:\/\/(chromewebstore\.google\.com|chrome\.google\.com\/webstore)/i;
+
+/**
+ * Estado de UNA sesion de la CLI.
+ *
+ * Antes esto eran tres variables de modulo. Como la extension se conecta a los
+ * cuatro puertos desde el MISMO service worker, dos sesiones compartian indice
+ * de refs, pestana de trabajo y grupo: el snapshot de la sesion B borraba el
+ * indice de A, y el clic de A caia sobre la pestana de B. Un estado por sesion
+ * es lo que hace cierto lo que promete la CLI: que varias convivan.
+ *
+ *   refIndex: ref -> { tabId, frameId }, para resolver despues los clics.
+ *   propias:  pestanas que ESTA sesion abrio o adopto con select. Es lo unico
+ *             que puede cerrar; ver close_tab.
+ */
+function nuevoEstado() {
+  return { refIndex: new Map(), workingTabId: null, groupId: null, propias: new Set() };
+}
+
+// ======================================================= estado persistente
+
+/**
+ * En Manifest V3 el service worker se apaga cuando le parece. Cuando eso pasa,
+ * el estado en memoria —indice de refs, pestana de trabajo, grupo— desaparece
+ * entero y sin avisar: el siguiente clic responde "el ref 3 no existe" y el
+ * siguiente close_tab dice que no hay pestana de trabajo, aunque en pantalla
+ * siga todo donde estaba. La extension ya pedia el permiso `storage` en el
+ * manifiesto y no lo usaba para nada.
+ *
+ * Se guarda en `storage.session`, que vive en memoria y se borra al cerrar
+ * Chrome: es un apunte para sobrevivir a un reinicio del worker, no un
+ * historial de navegacion en el disco del usuario.
+ */
+const almacen = (() => {
+  try {
+    return chrome.storage && chrome.storage.session ? chrome.storage.session : null;
+  } catch (_) {
+    return null;
+  }
+})();
+
+const claveDe = (sessionId) => "sesion:" + sessionId;
+
+function serializar(st) {
+  return {
+    workingTabId: st.workingTabId,
+    groupId: st.groupId,
+    propias: [...st.propias],
+    refIndex: [...st.refIndex.entries()],
+  };
+}
+
+function deserializar(plano) {
+  const st = nuevoEstado();
+  if (!plano) return st;
+  st.workingTabId = plano.workingTabId ?? null;
+  st.groupId = plano.groupId ?? null;
+  st.propias = new Set(plano.propias || []);
+  st.refIndex = new Map(plano.refIndex || []);
+  return st;
+}
+
+async function guardarEstado(link) {
+  if (!almacen || !link || !link.sessionId) return;
+  try {
+    await almacen.set({ [claveDe(link.sessionId)]: serializar(link.state) });
+  } catch (_) {}
+}
+
+async function restaurarEstado(link, sessionId) {
+  link.sessionId = sessionId;
+  if (!almacen) return;
+  try {
+    const guardado = await almacen.get(claveDe(sessionId));
+    const plano = guardado && guardado[claveDe(sessionId)];
+    if (!plano) return;
+    link.state = deserializar(plano);
+    // La pestana pudo cerrarse mientras el worker estaba dormido.
+    if (link.state.workingTabId) {
+      try {
+        await chrome.tabs.get(link.state.workingTabId);
+      } catch (_) {
+        link.state.workingTabId = null;
+      }
+    }
+  } catch (_) {}
+}
 
 // ============================================================ conexion
 
 function connect(port) {
+  const existente = links.get(port);
+  // Sin esta guarda, dos reintentos solapados dejaban dos sockets vivos contra
+  // el mismo puerto: la CLI se quedaba con el ultimo y el otro seguia
+  // consumiendo un keepalive para siempre.
+  if (existente && existente.socket && existente.socket.readyState === WebSocket.OPEN) return;
+
   let ws;
   try {
     ws = new WebSocket("ws://127.0.0.1:" + port);
@@ -33,16 +135,29 @@ function connect(port) {
     return;
   }
 
-  const link = links.get(port) || { delay: 1000 };
+  const link = existente || { delay: 1000, state: nuevoEstado() };
+  if (!link.state) link.state = nuevoEstado();
   link.socket = ws;
+  link.reconectando = false;
   links.set(port, link);
 
   ws.onopen = () => {
     link.delay = 1000;
-    sendTo(ws, { type: "hello", agent: "chocolatito-extension", version: "1.1.0", port });
+    // Que este puerto vuelva a aceptar conexion puede significar dos cosas muy
+    // distintas: otra sesion de la CLI (hay que empezar en limpio, heredar su
+    // pestana de trabajo es como acaban los comandos sin tabId actuando sobre
+    // una pestana ajena) o el mismo proceso de siempre despues de que Chrome
+    // apagara este worker (hay que RECUPERAR el estado, o el usuario ve como
+    // el agente se olvida de donde estaba trabajando a mitad de tarea).
+    //
+    // No se puede distinguir sin preguntar, asi que se arranca en limpio y se
+    // recupera solo si la CLI se identifica con el mismo sessionId de antes.
+    link.state = nuevoEstado();
+    link.sessionId = null;
+    sendTo(ws, { type: "hello", agent: "chocolatito-extension", version: VERSION, port, resumable: !!almacen });
     refreshBadge();
-    // El service worker de MV3 se duerme al quedar inactivo. Un ping periodico
-    // mantiene viva la conexion y con ella el indice de referencias.
+    // Un ping periodico mantiene viva la conexion y, con ella, el worker: la
+    // actividad de WebSocket reinicia el temporizador de inactividad de MV3.
     clearInterval(link.timer);
     link.timer = setInterval(() => sendTo(ws, { type: "keepalive" }), 20000);
   };
@@ -52,13 +167,27 @@ function connect(port) {
     try {
       msg = JSON.parse(ev.data);
     } catch (_) {
+      return; // sin id no hay a quien contestarle
+    }
+    if (!msg) return;
+
+    // La CLI se identifica al conectar. Si es la misma sesion que ya conocia
+    // este worker, se recupera su estado; si es otra, se queda el limpio.
+    if (msg.type === "session" && typeof msg.sessionId === "string") {
+      await restaurarEstado(link, msg.sessionId);
       return;
     }
-    if (!msg || typeof msg.id !== "number") return;
+
+    if (typeof msg.id !== "number") return;
+
+    // Un comando sin nombre antes se caia por el `throw` de handle y se
+    // contestaba igual; se deja explicito para que el error diga que pasa.
     try {
-      const data = await handle(msg);
+      const data = await conTimeout(handle(msg, link.state), TIMEOUT_COMANDO_MS, msg.cmd);
+      await guardarEstado(link);
       sendTo(ws, { type: "result", id: msg.id, ok: true, data });
     } catch (err) {
+      await guardarEstado(link);
       sendTo(ws, { type: "result", id: msg.id, ok: false, error: String((err && err.message) || err) });
     }
   };
@@ -66,6 +195,9 @@ function connect(port) {
   ws.onclose = () => {
     clearInterval(link.timer);
     if (link.socket === ws) link.socket = null;
+    const oldTab = link.state && link.state.workingTabId;
+    if (link.state) link.state.workingTabId = null;
+    if (oldTab) setTabOverlay(oldTab, false);
     refreshBadge();
     scheduleReconnect(port);
   };
@@ -78,7 +210,14 @@ function connect(port) {
 function scheduleReconnect(port) {
   const link = links.get(port) || { delay: 1000 };
   links.set(port, link);
-  setTimeout(() => connect(port), link.delay);
+  // onerror cierra el socket y onclose vuelve a llamar aqui: sin esta marca se
+  // encadenaban dos temporizadores por cada caida.
+  if (link.reconectando) return;
+  link.reconectando = true;
+  setTimeout(() => {
+    link.reconectando = false;
+    connect(port);
+  }, link.delay);
   // Tope bajo a proposito: el servidor es local y reintentar cuesta nada.
   link.delay = Math.min((link.delay || 1000) * 1.5, 3000);
 }
@@ -109,13 +248,66 @@ function setBadge(text) {
 
 // ============================================================ utilidades
 
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+/** Corta una operacion que no vuelve, con un error que dice cual era. */
+function conTimeout(promesa, ms, etiqueta) {
+  return new Promise((resolve, reject) => {
+    const t = setTimeout(() => {
+      reject(new Error(`"${etiqueta || "el comando"}" no respondio en ${Math.round(ms / 1000)} s. ` +
+        "La pagina puede estar bloqueada o pidiendo algo en un dialogo del navegador."));
+    }, ms);
+    promesa.then(
+      (v) => { clearTimeout(t); resolve(v); },
+      (e) => { clearTimeout(t); reject(e); }
+    );
+  });
+}
+
+/**
+ * Por que no se puede trabajar en esta URL, o null si si se puede.
+ *
+ * Chrome prohibe inyectar scripts en sus propias paginas y en la tienda. Antes
+ * el intento fallaba en `chrome.scripting.executeScript` con un error de
+ * Chrome ("Cannot access contents of the page"), que no le dice al agente ni
+ * que es culpa de la URL ni que no lo reintente.
+ */
+function motivoUrlVetada(url) {
+  const u = String(url || "");
+  if (ESQUEMAS_VETADOS.test(u)) {
+    return `Chrome no deja que ninguna extension actue en "${u.slice(0, 60)}". ` +
+      "Es una pagina interna del navegador: abre una pestana normal (https://...) para trabajar.";
+  }
+  if (TIENDAS_VETADAS.test(u)) {
+    return "Chrome bloquea las extensiones en la Chrome Web Store. No se puede leer ni pulsar ahi.";
+  }
+  return null;
+}
+
+async function comprobarUrl(tabId) {
+  let url;
+  try {
+    url = (await chrome.tabs.get(tabId)).url;
+  } catch (_) {
+    return; // la pestana ya no esta; el error de quien llama lo explica mejor
+  }
+  const motivo = motivoUrlVetada(url);
+  if (motivo) throw new Error(motivo);
+}
+
 /** Manda un mensaje al content script, inyectandolo si aun no estaba. */
 async function tell(tabId, frameId, msg) {
   const opts = frameId === undefined || frameId === null ? {} : { frameId };
   try {
     return await chrome.tabs.sendMessage(tabId, msg, opts);
   } catch (_) {
-    // Pagina cargada antes de instalar la extension: se inyecta al vuelo.
+    // Pagina cargada antes de instalar la extension: se inyecta al vuelo. Si la
+    // URL es de las que Chrome veta, se dice claramente en vez de devolver el
+    // "Cannot access contents of the page" de Chrome, que no explica ni que es
+    // culpa de la URL ni que no hay que reintentarlo.
+    await comprobarUrl(tabId);
     await chrome.scripting.executeScript({
       target: frameId ? { tabId, frameIds: [frameId] } : { tabId, allFrames: true },
       files: ["content.js"],
@@ -133,44 +325,186 @@ async function framesOf(tabId) {
   }
 }
 
-async function resolveTab(tabId) {
+/** Pestana explicita, o la de trabajo de ESTA sesion. null si no hay ninguna. */
+async function ownTab(tabId, st) {
   if (tabId) return tabId;
-  if (workingTabId) {
+  if (st.workingTabId) {
     try {
-      await chrome.tabs.get(workingTabId);
-      return workingTabId;
+      await chrome.tabs.get(st.workingTabId);
+      return st.workingTabId;
     } catch (_) {
-      workingTabId = null;
+      st.workingTabId = null;
+    }
+  }
+  return null;
+}
+
+/**
+ * Pestana para los comandos que ACTUAN (navigate, close_tab, eval, teclas).
+ *
+ * Aqui NO se cae a la pestana activa. Esa es la que el usuario tiene delante, y
+ * cuando no habia pestana de trabajo -arranque en frio, o despues de un
+ * `done`/`ungroup`- close_tab se la cerraba con el formulario a medio rellenar y
+ * navigate se la llevaba a otra URL. El dialogo de permiso solo dice la accion
+ * ("close_tab"), asi que el usuario ni siquiera podia ver cual moria. Fallar es
+ * lo correcto: que el agente abra o seleccione una pestana suya.
+ */
+async function actTab(tabId, st) {
+  const id = await ownTab(tabId, st);
+  if (id) return id;
+  throw new Error(
+    "no hay pestana de trabajo: abrela con open, elige una con select, o pasa tabId. " +
+      "No se actua sobre la pestana que el usuario tiene delante."
+  );
+}
+
+/**
+ * La pestana que el usuario tiene delante, con varios planes B.
+ *
+ * `lastFocusedWindow` era el unico criterio, y es justo el que falla en el caso
+ * de uso que la extension anuncia: si el usuario esta en un juego a pantalla
+ * completa, Chrome no tiene ninguna ventana enfocada y la consulta vuelve
+ * vacia. El agente recibia entonces "no hay ninguna pestana disponible" con
+ * doce pestanas abiertas delante.
+ */
+async function pestanaVisible() {
+  const intentos = [
+    { active: true, lastFocusedWindow: true },
+    { active: true, currentWindow: true },
+    { active: true },
+  ];
+  for (const q of intentos) {
+    try {
+      const [t] = await chrome.tabs.query(q);
+      if (t) return t;
+    } catch (_) {}
+  }
+  try {
+    const [t] = await chrome.tabs.query({});
+    if (t) return t;
+  } catch (_) {}
+  return null;
+}
+
+/**
+ * Pestana para los comandos de solo lectura (snapshot, getText, screenshot,
+ * waitFor, banner): mirar lo que el usuario tiene delante es aceptable.
+ *
+ * Devuelve own=false cuando es prestada, para que el que lee NO la adopte como
+ * pestana de trabajo: adoptarla convertiria el siguiente close_tab sin tabId en
+ * el cierre de la pestana del usuario, por la puerta de atras.
+ */
+async function readTab(tabId, st) {
+  const id = await ownTab(tabId, st);
+  if (id) return { tabId: id, own: true };
+  const activa = await pestanaVisible();
+  if (!activa) throw new Error("no hay ninguna pestana disponible");
+  return { tabId: activa.id, own: false };
+}
+
+/**
+ * Comprueba si alguna sesión activa está usando la pestaña como pestaña de trabajo (B4).
+ * Permite que dos sesiones convivan sin que el cierre de una apague el borde
+ * de la pestaña si la otra aún la está utilizando.
+ */
+function tabEnUso(tabId) {
+  if (!tabId) return false;
+  for (const link of links.values()) {
+    if (link.state && link.state.workingTabId === tabId) return true;
+  }
+  return false;
+}
+
+/**
+ * Pide al content script encender o apagar el borde naranja y la insignia (B1-B4).
+ * Si se pide apagar pero otra sesión aún usa la pestaña, se mantiene encendido.
+ * Si el content script no está inyectado todavía (páginas internas, cargando),
+ * se captura el error silenciosamente para no impedir la acción.
+ */
+async function setTabOverlay(tabId, activo) {
+  if (!tabId) return;
+  if (!activo && tabEnUso(tabId)) return;
+  try {
+    await chrome.tabs.sendMessage(tabId, { cmd: "overlay", tipo: "overlay", activo: Boolean(activo) });
+  } catch (_) {
+    // Si la página aún no tiene content script o es una URL vetada, se ignora
+  }
+}
+
+// D8: Detección y reporte de descargas disparadas por acciones del agente
+const descargasRecientes = [];
+try {
+  if (typeof chrome !== "undefined" && chrome.downloads && chrome.downloads.onCreated) {
+    chrome.downloads.onCreated.addListener((item) => {
+      descargasRecientes.push({
+        id: item.id,
+        url: item.url,
+        filename: item.filename || "",
+        state: item.state || "in_progress",
+        timestamp: Date.now(),
+      });
+      if (descargasRecientes.length > 20) descargasRecientes.shift();
+    });
+  }
+  if (typeof chrome !== "undefined" && chrome.downloads && chrome.downloads.onChanged) {
+    chrome.downloads.onChanged.addListener((delta) => {
+      const item = descargasRecientes.find((d) => d.id === delta.id);
+      if (item) {
+        if (delta.filename && delta.filename.current) item.filename = delta.filename.current;
+        if (delta.state && delta.state.current) item.state = delta.state.current;
+      }
+    });
+  }
+} catch (_) {}
+
+async function detectarDescarga(tiempoInicio) {
+  try {
+    if (typeof chrome !== "undefined" && chrome.downloads && typeof chrome.downloads.search === "function") {
+      const items = await chrome.downloads.search({
+        startedAfter: new Date(tiempoInicio).toISOString(),
+        limit: 1,
+      });
+      if (items && items.length > 0) {
+        return {
+          id: items[0].id,
+          filename: items[0].filename || "",
+          state: items[0].state || "in_progress",
+          url: items[0].url,
+        };
+      }
+    }
+  } catch (_) {}
+  for (let i = descargasRecientes.length - 1; i >= 0; i--) {
+    if (descargasRecientes[i].timestamp >= tiempoInicio) {
+      return descargasRecientes[i];
     }
   }
-  const [active] = await chrome.tabs.query({ active: true, lastFocusedWindow: true });
-  if (!active) throw new Error("no hay ninguna pestana disponible");
-  return active.id;
+  return null;
 }
 
 /**
  * Mete la pestana en un grupo visible llamado "Chocolatito Code", para que el
  * usuario vea de un vistazo donde esta trabajando el agente.
  */
-async function groupTab(tabId) {
+async function groupTab(tabId, st) {
   try {
-    if (groupId !== null) {
+    if (st.groupId !== null) {
       try {
-        await chrome.tabGroups.get(groupId);
+        await chrome.tabGroups.get(st.groupId);
       } catch (_) {
-        groupId = null;
+        st.groupId = null;
       }
     }
     const newGroupId = await chrome.tabs.group(
-      groupId === null ? { tabIds: [tabId] } : { tabIds: [tabId], groupId }
+      st.groupId === null ? { tabIds: [tabId] } : { tabIds: [tabId], groupId: st.groupId }
     );
-    groupId = newGroupId;
-    await chrome.tabGroups.update(groupId, {
+    st.groupId = newGroupId;
+    await chrome.tabGroups.update(st.groupId, {
       title: GROUP_TITLE,
       color: "orange",
       collapsed: false,
     });
-    return groupId;
+    return st.groupId;
   } catch (err) {
     return null;
   }
@@ -182,33 +516,142 @@ async function banner(tabId, text) {
   } catch (_) {}
 }
 
+/**
+ * Espera a que la pestana termine de cargar DE VERDAD.
+ *
+ * La version anterior solo miraba `status === "complete"`, y lo miraba justo
+ * despues de pedir la navegacion: la pestana todavia informaba del estado de la
+ * pagina ANTERIOR, asi que la espera volvia al instante y el snapshot siguiente
+ * leia la pagina vieja. Un fallo de los que no dan error: el agente cree que ya
+ * esta en la pagina nueva y describe la anterior.
+ *
+ * Ahora hay que ver primero la transicion (estado "loading" o cambio de URL) y
+ * solo despues aceptar el "complete". El evento onUpdated resuelve rapido; el
+ * sondeo esta de red por si la extension no puede suscribirse.
+ */
+function esperarCarga(tabId, timeout, urlAnterior) {
+  return new Promise((resolve) => {
+    const deadline = Date.now() + (timeout || 30000);
+    let vioTransicion = urlAnterior === undefined || urlAnterior === null;
+    let terminado = false;
+    let oyente = null;
+
+    const acabar = (valor) => {
+      if (terminado) return;
+      terminado = true;
+      if (oyente) {
+        try { chrome.tabs.onUpdated.removeListener(oyente); } catch (_) {}
+      }
+      resolve(valor);
+    };
 
+    try {
+      if (chrome.tabs.onUpdated && chrome.tabs.onUpdated.addListener) {
+        oyente = (id, info) => {
+          if (id !== tabId) return;
+          if (info.status === "loading" || (info.url && info.url !== urlAnterior)) vioTransicion = true;
+          if (vioTransicion && info.status === "complete") acabar(true);
+        };
+        chrome.tabs.onUpdated.addListener(oyente);
+      }
+    } catch (_) {}
 
-/** Activa la pestana, ejecuta la accion por CDP y lo deja todo como estaba. */
-async function withTrustedTab(tabId, fn) {
-  const target = { tabId };
-  let previaId = null;
-  let attached = false;
-  try {
-    const tab = await chrome.tabs.get(tabId);
-    const [activa] = await chrome.tabs.query({ active: true, windowId: tab.windowId });
-    if (activa && activa.id !== tabId) previaId = activa.id;
-    if (!tab.active) await chrome.tabs.update(tabId, { active: true });
-    await sleep(250);
-  } catch (_) {}
+    const sondeo = async () => {
+      if (terminado) return;
+      try {
+        const t = await chrome.tabs.get(tabId);
+        if (!vioTransicion && (t.status === "loading" || (t.url && t.url !== urlAnterior))) {
+          vioTransicion = true;
+        }
+        if (vioTransicion && t.status === "complete") return acabar(true);
+      } catch (_) {
+        return acabar(false); // la pestana se fue
+      }
+      if (Date.now() > deadline) return acabar(false);
+      setTimeout(sondeo, 150);
+    };
+    sondeo();
+  });
+}
 
-  try {
-    await chrome.debugger.attach(target, "1.3");
-    attached = true;
-    return await fn(target);
-  } finally {
-    if (attached) {
-      try { await chrome.debugger.detach(target); } catch (_) {}
-    }
-    if (previaId !== null) {
-      try { await chrome.tabs.update(previaId, { active: true }); } catch (_) {}
+// ==================================================== acciones de confianza
+
+/**
+ * Cola de adjuntos del depurador POR PESTANA.
+ *
+ * chrome.debugger.attach falla si ya hay otro depurador adjunto a esa pestana,
+ * y con cuatro sesiones hablando por el mismo worker eso pasa en cuanto dos
+ * escriben a la vez. Antes cada una lo intentaba a lo bruto y la segunda caia
+ * al camino del DOM sin que nadie supiera por que.
+ */
+const colaPorPestana = new Map();
+
+function enCola(tabId, fn) {
+  const anterior = colaPorPestana.get(tabId) || Promise.resolve();
+  const turno = anterior.then(fn, fn);
+  const marca = turno.catch(() => {});
+  colaPorPestana.set(tabId, marca);
+  marca.then(() => {
+    if (colaPorPestana.get(tabId) === marca) colaPorPestana.delete(tabId);
+  });
+  return turno;
+}
+
+function cdp(target, method, params) {
+  return chrome.debugger.sendCommand(target, method, params || {});
+}
+
+/**
+ * Activa la pestana, ejecuta la accion por CDP y lo deja todo como estaba.
+ *
+ * El renderizador de una pestana que no esta activa descarta los eventos de
+ * entrada: por eso escribir en segundo plano dejaba el campo vacio. Se activa
+ * solo lo que dura la accion y despues se devuelve la que estaba.
+ *
+ * Importante: esto NO toca el foco del sistema operativo. Solo cambia que
+ * pestana se ve dentro de Chrome. Si el usuario esta en un juego a pantalla
+ * completa o en otra aplicacion, no nota nada.
+ */
+function withTrustedTab(tabId, fn, preparar) {
+  return enCola(tabId, async () => {
+    const target = { tabId };
+    let previaId = null;
+    let attached = false;
+    try {
+      const tab = await chrome.tabs.get(tabId);
+      const [activa] = await chrome.tabs.query({ active: true, windowId: tab.windowId });
+      if (activa && activa.id !== tabId) previaId = activa.id;
+      if (!tab.active) await chrome.tabs.update(tabId, { active: true });
+      await sleep(250);
+    } catch (_) {}
+
+    // `preparar` corre DENTRO de la cola y con la pestana ya activa. Ahi es
+    // donde se piden las coordenadas del elemento: pedirlas fuera —como se
+    // hacia— significa medirlas antes de que le toque el turno, y para entonces
+    // la accion anterior puede haber movido la pagina. El clic salia entonces
+    // sobre lo que hubiera quedado en ese punto, no sobre el elemento pedido.
+    const preparado = preparar ? await preparar() : undefined;
+
+    try {
+      await chrome.debugger.attach(target, "1.3");
+      attached = true;
+      return await fn(target, preparado);
+    } finally {
+      if (attached) {
+        try { await chrome.debugger.detach(target); } catch (_) {}
+      }
+      if (previaId !== null) {
+        try { await chrome.tabs.update(previaId, { active: true }); } catch (_) {}
+      }
     }
-  }
+  });
+}
+
+/** Pide al content script donde esta el elemento, en coordenadas del viewport. */
+async function situar(tabId, frameId, ref, queEs) {
+  const pos = await tell(tabId, frameId, { cmd: "rect", ref });
+  if (!pos || !pos.ok) throw new Error((pos && pos.error) || `no se pudo situar ${queEs}`);
+  return pos;
 }
 
 /**
@@ -219,26 +662,20 @@ async function withTrustedTab(tabId, fn) {
  * En Flow, el boton de enviar recibia el clic sintetico y no pasaba nada.
  */
 async function clickTrusted(tabId, frameId, ref) {
-  const pos = await tell(tabId, frameId, { cmd: "rect", ref });
-  if (!pos || !pos.ok) throw new Error((pos && pos.error) || "no se pudo situar el elemento");
-
-  await withTrustedTab(tabId, async (target) => {
-    const base = { x: pos.x, y: pos.y, button: "left", clickCount: 1 };
-    await cdp(target, "Input.dispatchMouseEvent", { type: "mouseMoved", x: pos.x, y: pos.y });
-    await sleep(60);
-    await cdp(target, "Input.dispatchMouseEvent", { ...base, type: "mousePressed", buttons: 1 });
-    await sleep(60);
-    await cdp(target, "Input.dispatchMouseEvent", { ...base, type: "mouseReleased", buttons: 0 });
-    await sleep(300);
-  });
-
-  return { label: pos.label };
-}
-
-// ==================================================== escritura de confianza
-
-function cdp(target, method, params) {
-  return chrome.debugger.sendCommand(target, method, params || {});
+  return await withTrustedTab(
+    tabId,
+    async (target, pos) => {
+      const base = { x: pos.x, y: pos.y, button: "left", clickCount: 1 };
+      await cdp(target, "Input.dispatchMouseEvent", { type: "mouseMoved", x: pos.x, y: pos.y });
+      await sleep(60);
+      await cdp(target, "Input.dispatchMouseEvent", { ...base, type: "mousePressed", buttons: 1 });
+      await sleep(60);
+      await cdp(target, "Input.dispatchMouseEvent", { ...base, type: "mouseReleased", buttons: 0 });
+      await sleep(300);
+      return { label: pos.label };
+    },
+    () => situar(tabId, frameId, ref, "el elemento")
+  );
 }
 
 /**
@@ -250,36 +687,10 @@ function cdp(target, method, params) {
  * proporcionar una instruccion". Es exactamente lo que pasaba.
  *
  * Input.insertText y Input.dispatchKeyEvent los procesa el renderizador igual que
- * si los hubiera tecleado una persona, y funcionan con la pestana en segundo
- * plano: no hace falta foco ni traer la ventana al frente.
+ * si los hubiera tecleado una persona.
  */
 async function typeTrusted(tabId, frameId, ref, text, submit, replace) {
-  const pos = await tell(tabId, frameId, { cmd: "rect", ref });
-  if (!pos || !pos.ok) throw new Error((pos && pos.error) || "no se pudo situar el campo");
-
-  const target = { tabId };
-  let attached = false;
-
-  // El renderizador de una pestana que no esta activa descarta los eventos de
-  // texto: por eso escribir en segundo plano dejaba el campo vacio. Se activa la
-  // pestana solo lo que dura la escritura y despues se devuelve la que estaba.
-  //
-  // Importante: esto NO toca el foco del sistema operativo. Solo cambia que
-  // pestana se ve dentro de Chrome, y se deja como estaba. Si el usuario esta en
-  // un juego a pantalla completa o en otra aplicacion, no nota nada.
-  let previaId = null;
-  try {
-    const tab = await chrome.tabs.get(tabId);
-    const [activa] = await chrome.tabs.query({ active: true, windowId: tab.windowId });
-    if (activa && activa.id !== tabId) previaId = activa.id;
-    if (!tab.active) await chrome.tabs.update(tabId, { active: true });
-    await sleep(250);
-  } catch (_) {}
-
-  try {
-    await chrome.debugger.attach(target, "1.3");
-    attached = true;
-
+  const etiqueta = await withTrustedTab(tabId, async (target, pos) => {
     // Clic real para que el editor tome el foco de verdad.
     const click = { x: pos.x, y: pos.y, button: "left", clickCount: 1, buttons: 1 };
     await cdp(target, "Input.dispatchMouseEvent", { type: "mouseMoved", x: pos.x, y: pos.y });
@@ -316,51 +727,95 @@ async function typeTrusted(tabId, frameId, ref, text, submit, replace) {
       await cdp(target, "Input.dispatchKeyEvent", { ...enter, type: "keyUp" });
       await sleep(400);
     }
-  } finally {
-    if (attached) {
-      try { await chrome.debugger.detach(target); } catch (_) {}
-    }
-    // Se devuelve la pestana que el usuario tenia delante.
-    if (previaId !== null) {
-      try { await chrome.tabs.update(previaId, { active: true }); } catch (_) {}
-    }
-  }
+    return pos.label;
+  }, () => situar(tabId, frameId, ref, "el campo"));
 
   const after = await tell(tabId, frameId, { cmd: "value", ref });
-  return { label: pos.label, value: after && after.ok ? after.value : "" };
+  return { label: etiqueta, value: after && after.ok ? after.value : "" };
+}
+
+/**
+ * Captura la pestana.
+ *
+ * Se prefiere Page.captureScreenshot del protocolo DevTools porque funciona con
+ * la pestana en segundo plano. Pero si hay otro depurador adjunto —lo mas
+ * comun: el usuario tiene DevTools abierto— el adjunto falla, y antes eso
+ * dejaba el comando sin captura y sin explicacion, mientras que escribir y
+ * pulsar si tenian camino alternativo. Ahora tambien lo tiene: se activa la
+ * pestana un instante y se usa la captura normal de Chrome.
+ */
+async function capturar(tabId) {
+  try {
+    return await withTrustedTab(tabId, async (target) => {
+      const res = await cdp(target, "Page.captureScreenshot", { format: "png", captureBeyondViewport: false });
+      return { data: res.data, via: "cdp" };
+    });
+  } catch (err) {
+    if (!chrome.tabs.captureVisibleTab) throw err;
+    return await enCola(tabId, async () => {
+      let previaId = null;
+      let windowId;
+      try {
+        const tab = await chrome.tabs.get(tabId);
+        windowId = tab.windowId;
+        const [activa] = await chrome.tabs.query({ active: true, windowId });
+        if (activa && activa.id !== tabId) previaId = activa.id;
+        if (!tab.active) await chrome.tabs.update(tabId, { active: true });
+        await sleep(250);
+        const dataUrl = await chrome.tabs.captureVisibleTab(windowId, { format: "png" });
+        return {
+          data: String(dataUrl).replace(/^data:image\/png;base64,/, ""),
+          via: "tabs",
+          warning: "el depurador no estaba disponible (¿DevTools abierto?): captura por la via normal",
+        };
+      } finally {
+        if (previaId !== null) {
+          try { await chrome.tabs.update(previaId, { active: true }); } catch (_) {}
+        }
+      }
+    });
+  }
 }
 
 // ============================================================ comandos
 
-async function handle(msg) {
+async function handle(msg, st) {
   const cmd = msg.cmd;
+  if (typeof cmd !== "string" || !cmd) {
+    throw new Error("mensaje sin comando");
+  }
 
   if (cmd === "ping") {
-    return { pong: true, version: "1.0.0" };
+    return { pong: true, version: VERSION };
   }
 
   if (cmd === "tabs") {
     const tabs = await chrome.tabs.query({});
     return {
-      working: workingTabId,
+      working: st.workingTabId,
       tabs: tabs.map((t) => ({
         id: t.id,
         title: t.title || "",
         url: t.url || "",
         active: !!t.active,
-        grouped: t.groupId !== undefined && t.groupId === groupId,
+        grouped: t.groupId !== undefined && t.groupId === st.groupId,
+        propia: st.propias.has(t.id),
       })),
     };
   }
 
   if (cmd === "open") {
+    const vetada = motivoUrlVetada(msg.url);
+    if (vetada) throw new Error(vetada);
     // active:false es la clave: la pestana se crea SIN robar el foco ni cambiar
     // lo que el usuario esta viendo.
     const tab = await chrome.tabs.create({ url: msg.url, active: false });
-    workingTabId = tab.id;
-    await waitForLoad(tab.id, msg.timeout || 30000);
-    await groupTab(tab.id);
+    st.workingTabId = tab.id;
+    st.propias.add(tab.id);
+    await esperarCarga(tab.id, msg.timeout || 30000);
+    await groupTab(tab.id, st);
     await banner(tab.id, msg.note || "pestana abierta");
+    await setTabOverlay(tab.id, true);
     const info = await chrome.tabs.get(tab.id);
     return { tabId: tab.id, title: info.title || "", url: info.url || "" };
   }
@@ -372,42 +827,78 @@ async function handle(msg) {
       (t) => (t.url || "").toLowerCase().includes(needle) || (t.title || "").toLowerCase().includes(needle)
     );
     if (!hit) throw new Error('ninguna pestana contiene "' + msg.match + '"');
-    workingTabId = hit.id;
-    await groupTab(hit.id);
+    if (st.workingTabId && st.workingTabId !== hit.id) {
+      const vieja = st.workingTabId;
+      st.workingTabId = null;
+      await setTabOverlay(vieja, false);
+    }
+    st.workingTabId = hit.id;
+    // Elegirla es un acto explicito del agente: a partir de aqui es suya y la
+    // puede cerrar. Mirarla (readTab) nunca da ese derecho.
+    st.propias.add(hit.id);
+    await groupTab(hit.id, st);
     await banner(hit.id, "pestana seleccionada");
+    await setTabOverlay(hit.id, true);
     return { tabId: hit.id, title: hit.title || "", url: hit.url || "" };
   }
 
   if (cmd === "navigate") {
-    const tabId = await resolveTab(msg.tabId);
+    const vetada = motivoUrlVetada(msg.url);
+    if (vetada) throw new Error(vetada);
+    const tabId = await actTab(msg.tabId, st);
+    let urlAnterior;
+    try {
+      urlAnterior = (await chrome.tabs.get(tabId)).url;
+    } catch (_) {}
+    // La espera se arma ANTES de pedir la navegacion: al reves se pierde el
+    // evento de las paginas que cargan rapido.
+    const cargando = esperarCarga(tabId, msg.timeout || 30000, urlAnterior);
     await chrome.tabs.update(tabId, { url: msg.url });
-    await waitForLoad(tabId, msg.timeout || 30000);
-    workingTabId = tabId;
-    await groupTab(tabId);
+    await cargando;
+    st.workingTabId = tabId;
+    st.propias.add(tabId);
+    await groupTab(tabId, st);
     const info = await chrome.tabs.get(tabId);
     await banner(tabId, "navegando a " + (info.url || "").slice(0, 60));
+    await setTabOverlay(tabId, true);
     return { tabId, title: info.title || "", url: info.url || "" };
   }
 
   if (cmd === "snapshot") {
-    const tabId = await resolveTab(msg.tabId);
-    workingTabId = tabId;
+    const { tabId, own } = await readTab(msg.tabId, st);
+    // Solo se adopta como pestana de trabajo si ya era nuestra o vino con tabId.
+    if (own) {
+      st.workingTabId = tabId;
+      await setTabOverlay(tabId, true);
+    }
     await banner(tabId, "leyendo la pagina");
-    refIndex.clear();
+    st.refIndex.clear();
 
     const frames = await framesOf(tabId);
     const rows = [];
     let counter = 0;
+    let fallos = 0;
     for (const frameId of frames) {
       let res;
       try {
-        res = await tell(tabId, frameId, { cmd: "snapshot", startIndex: counter, filter: msg.filter || "" });
+        // `nuevo` va a TODOS los frames, no solo al primero: cada frame tiene su
+        // propio content script con su propia tabla de identidades, y antes solo
+        // se limpiaba la del frame con startIndex 0. Los subframes acumulaban
+        // identidades de snapshots viejos y resolvian un ref a un boton que ya
+        // no era ese.
+        res = await tell(tabId, frameId, {
+          cmd: "snapshot",
+          startIndex: counter,
+          filter: msg.filter || "",
+          nuevo: true,
+        });
       } catch (_) {
+        fallos++;
         continue;
       }
       if (!res || !res.ok) continue;
       for (const item of res.items) {
-        refIndex.set(item.ref, { tabId, frameId });
+        st.refIndex.set(item.ref, { tabId, frameId });
         rows.push(item);
       }
       counter += res.items.length;
@@ -415,23 +906,36 @@ async function handle(msg) {
 
     const info = await chrome.tabs.get(tabId);
     const max = msg.max || 60;
+    if (rows.length === 0) {
+      // Cero elementos y todos los frames fallando casi siempre es una pagina
+      // donde Chrome no deja entrar. Decirlo aqui ahorra el viaje de intentar
+      // pulsar algo y recibir un error distinto.
+      const vetada = motivoUrlVetada(info.url);
+      if (vetada) throw new Error(vetada);
+    }
     return {
       tabId,
       title: info.title || "",
       url: info.url || "",
       truncated: rows.length > max,
+      framesSinRespuesta: fallos || undefined,
       elements: rows.slice(0, max),
     };
   }
 
   if (cmd === "click" || cmd === "type" || cmd === "press") {
-    const loc = refIndex.get(msg.ref);
+    const loc = st.refIndex.get(msg.ref);
     if (msg.ref !== undefined && msg.ref !== null && !loc) {
       throw new Error("el ref " + msg.ref + " no existe; vuelve a hacer snapshot");
     }
-    const tabId = loc ? loc.tabId : await resolveTab(msg.tabId);
+    // Sin ref (press suele venir asi) esto escribe teclas en la pagina: es
+    // actuacion, nunca sobre la pestana que el usuario esta mirando.
+    const tabId = loc ? loc.tabId : await actTab(msg.tabId, st);
     const frameId = loc ? loc.frameId : 0;
-    workingTabId = tabId;
+    st.workingTabId = tabId;
+    await setTabOverlay(tabId, true);
+
+    const tiempoInicioAccion = Date.now() - 50;
 
     if (cmd === "click") await banner(tabId, "pulsando un elemento");
     if (cmd === "type") await banner(tabId, "escribiendo");
@@ -473,28 +977,63 @@ async function handle(msg) {
     if (!res || !res.ok) throw new Error((res && res.error) || "el content script no respondio");
 
     // Se deja respirar a la pagina para que reaccione antes del siguiente paso.
-    await sleep(msg.settle || 600);
+    await sleep(msg.settle === undefined ? 600 : msg.settle);
     const info = await chrome.tabs.get(tabId);
-    return { tabId, title: info.title || "", url: info.url || "", label: res.label, value: res.value, via: res.via, warning: res.warning };
+
+    // D8: Detectar si esta acción inició o completó alguna descarga de archivo
+    const descarga = await detectarDescarga(tiempoInicioAccion);
+    if (descarga) {
+      res.download = descarga;
+      res.label = (res.label ? res.label + " " : "") + `[Descarga: ${descarga.filename || descarga.url}]`;
+    }
+
+    return {
+      tabId,
+      title: info.title || "",
+      url: info.url || "",
+      label: res.label,
+      value: res.value,
+      via: res.via,
+      warning: res.warning,
+      download: res.download,
+    };
   }
 
   if (cmd === "getText") {
-    const tabId = await resolveTab(msg.tabId);
+    const { tabId } = await readTab(msg.tabId, st);
     const res = await tell(tabId, 0, { cmd: "getText" });
     if (!res || !res.ok) throw new Error("no se pudo leer el texto");
     return res;
   }
 
   if (cmd === "eval") {
-    const tabId = await resolveTab(msg.tabId);
+    // eval ejecuta JavaScript arbitrario en la pagina: puede pulsar, enviar
+    // formularios y leerlo todo. Es actuacion, no lectura.
+    const tabId = await actTab(msg.tabId, st);
     const res = await tell(tabId, 0, { cmd: "eval", script: msg.script });
-    if (!res || !res.ok) throw new Error("no se pudo evaluar");
+    if (!res || !res.ok) throw new Error((res && res.error) || "no se pudo evaluar");
     return res;
   }
 
   if (cmd === "waitFor") {
-    const tabId = await resolveTab(msg.tabId);
-    const deadline = Date.now() + (msg.timeout || 20000);
+    const { tabId } = await readTab(msg.tabId, st);
+    const timeout = msg.timeout || 20000;
+    const deadline = Date.now() + timeout;
+
+    // D3: Espera hasta que aparezca un selector CSS en el DOM
+    if (msg.selector || msg.css) {
+      const sel = msg.selector || msg.css;
+      while (Date.now() < deadline) {
+        const res = await tell(tabId, 0, { cmd: "waitForCondition", selector: sel });
+        if (res && res.ok && res.conditionMet) {
+          return { ok: true, found: true, selector: sel };
+        }
+        await sleep(300);
+      }
+      return { ok: false, found: false, error: `Tiempo agotado esperando el selector "${sel}"` };
+    }
+
+    // D3: Espera hasta que aparezca un texto concreto
     if (msg.text) {
       while (Date.now() < deadline) {
         const res = await tell(tabId, 0, { cmd: "getText" });
@@ -503,73 +1042,125 @@ async function handle(msg) {
       }
       return { found: false };
     }
-    await sleep(msg.ms || 2000);
-    return { waited: msg.ms || 2000 };
+
+    // D3: Espera hasta que la pantalla "esté quieta" (sin mutaciones de DOM durante quietMs)
+    if (msg.stable || msg.quiet || msg.condition === "stable") {
+      while (Date.now() < deadline) {
+        const res = await tell(tabId, 0, { cmd: "waitForCondition", stable: true, quietMs: msg.quietMs || 400 });
+        if (res && res.ok && res.conditionMet) {
+          return { ok: true, stable: true };
+        }
+        await sleep(250);
+      }
+      return { ok: true, stable: true, warning: "Tiempo límite alcanzado esperando quietud" };
+    }
+
+    const ms = msg.ms || 2000;
+    await sleep(ms);
+    return { waited: ms };
   }
 
   if (cmd === "screenshot") {
-    // Page.captureScreenshot por el protocolo DevTools funciona sobre pestanas
-    // en segundo plano; chrome.tabs.captureVisibleTab exigiria que la pestana
-    // estuviera activa y la ventana enfocada.
-    const tabId = await resolveTab(msg.tabId);
-    const target = { tabId };
-    await chrome.debugger.attach(target, "1.3");
-    try {
-      const res = await chrome.debugger.sendCommand(target, "Page.captureScreenshot", {
-        format: "png",
-        captureBeyondViewport: false,
-      });
-      return { data: res.data };
-    } finally {
-      try { await chrome.debugger.detach(target); } catch (_) {}
-    }
+    const { tabId } = await readTab(msg.tabId, st);
+    return await capturar(tabId);
   }
 
   if (cmd === "banner") {
-    const tabId = await resolveTab(msg.tabId);
+    const { tabId } = await readTab(msg.tabId, st);
     await banner(tabId, msg.text);
     return { ok: true };
   }
 
   if (cmd === "close_tab") {
     // Cerrar lo que se abre es parte de dejar el navegador como se encontro.
-    const ids = Array.isArray(msg.tabIds) ? msg.tabIds : [await resolveTab(msg.tabId)];
+    // Lo que NO puede pasar es cerrar lo que no se abrio.
+    //
+    // Sin tabId y sin pestana de trabajo, actTab falla en vez de llevarse la del
+    // usuario. Y con una lista explicita de tabIds -por donde antes se colaba
+    // cualquier pestana, incluida la del usuario, sin comprobacion ninguna- se
+    // exige que cada una sea de esta sesion.
+    let ids;
+    if (Array.isArray(msg.tabIds)) {
+      const ajenas = msg.tabIds.filter((id) => !st.propias.has(id) && id !== st.workingTabId);
+      if (ajenas.length > 0) {
+        throw new Error(
+          "esta sesion no abrio las pestanas " + ajenas.join(", ") + ", asi que no las cierra. " +
+            "Solo se cierran las que abrio con open o eligio con select."
+        );
+      }
+      ids = msg.tabIds;
+    } else {
+      ids = [await actTab(msg.tabId, st)];
+    }
+
+    if (ids.length === 0) return { closed: 0 };
+    if (ids.includes(st.workingTabId)) st.workingTabId = null;
+    for (const id of ids) st.propias.delete(id);
     await chrome.tabs.remove(ids);
-    if (ids.includes(workingTabId)) workingTabId = null;
+    for (const id of ids) {
+      await setTabOverlay(id, false);
+    }
     return { closed: ids.length };
   }
 
   if (cmd === "ungroup") {
-    if (workingTabId) {
-      try { await chrome.tabs.ungroup(workingTabId); } catch (_) {}
-      await banner(workingTabId, null);
+    // Antes solo se sacaba del grupo la pestana de trabajo: si la sesion habia
+    // abierto tres, las otras dos se quedaban dentro de un grupo naranja que ya
+    // no era de nadie, y el usuario tenia que deshacerlo a mano.
+    const aSoltar = new Set(st.propias);
+    if (st.workingTabId) aSoltar.add(st.workingTabId);
+    st.groupId = null;
+    st.workingTabId = null;
+    st.propias.clear();
+    st.refIndex.clear();
+    for (const id of aSoltar) {
+      try {
+        await chrome.tabs.ungroup(id);
+      } catch (_) {}
+      await banner(id, null);
+      await setTabOverlay(id, false);
     }
-    groupId = null;
-    workingTabId = null;
-    return { ok: true };
+    return { ok: true, soltadas: aSoltar.size };
   }
 
   throw new Error("comando desconocido: " + cmd);
 }
 
-function sleep(ms) {
-  return new Promise((r) => setTimeout(r, ms));
-}
+// Una pestana cerrada por el usuario no puede seguir siendo la de trabajo de
+// nadie: sin esto, el siguiente comando fallaba con el error de Chrome ("No tab
+// with id") en vez de decir que ya no hay donde trabajar.
+try {
+  chrome.tabs.onRemoved.addListener((tabId) => {
+    setTabOverlay(tabId, false);
+    for (const link of links.values()) {
+      if (!link.state) continue;
+      link.state.propias.delete(tabId);
+      if (link.state.workingTabId === tabId) link.state.workingTabId = null;
+      guardarEstado(link);
+    }
+  });
+} catch (_) {}
+
+// Al navegar o recargar la página, se reinyecta el content script y el overlay
+// se apaga. Si la pestaña sigue siendo de trabajo para alguna sesión, se vuelve a activar (B4).
+try {
+  if (typeof chrome !== "undefined" && chrome.webNavigation && chrome.webNavigation.onCompleted && typeof chrome.webNavigation.onCompleted.addListener === "function") {
+    chrome.webNavigation.onCompleted.addListener((details) => {
+      if (details && details.frameId === 0 && tabEnUso(details.tabId)) {
+        setTabOverlay(details.tabId, true);
+      }
+    });
+  }
+} catch (_) {}
 
-function waitForLoad(tabId, timeout) {
-  return new Promise((resolve) => {
-    const deadline = Date.now() + timeout;
-    const check = async () => {
-      try {
-        const t = await chrome.tabs.get(tabId);
-        if (t.status === "complete" || Date.now() > deadline) return resolve();
-      } catch (_) {
-        return resolve();
+try {
+  if (typeof chrome !== "undefined" && chrome.tabs && chrome.tabs.onUpdated && typeof chrome.tabs.onUpdated.addListener === "function") {
+    chrome.tabs.onUpdated.addListener((tabId, changeInfo) => {
+      if (changeInfo && changeInfo.status === "complete" && tabEnUso(tabId)) {
+        setTabOverlay(tabId, true);
       }
-      setTimeout(check, 250);
-    };
-    check();
-  });
-}
+    });
+  }
+} catch (_) {}
 
 for (const p of WS_PORTS) connect(p);