wavi-lib 0.2.0__tar.gz

wavi_lib-0.2.0/.githooks/pre-commit

@@ -0,0 +1,17 @@
+#!/bin/sh
+# Lint before every commit. Bypass with: git commit --no-verify
+set -e
+
+cd "$(git rev-parse --show-toplevel)"
+
+if [ -x .venv/bin/ruff ]; then
+    RUFF=.venv/bin/ruff
+elif command -v ruff >/dev/null 2>&1; then
+    RUFF=ruff
+else
+    echo "[pre-commit] ruff not found — skipping lint (run: make install-dev)" >&2
+    exit 0
+fi
+
+echo "[pre-commit] ruff check..."
+$RUFF check wavi/ tests/ scripts/

wavi_lib-0.2.0/.githooks/pre-push

@@ -0,0 +1,21 @@
+#!/bin/sh
+# Lint + full offline test suite before every push (~1s).
+# WAVI_NO_REPORT=1 keeps conftest from rewriting boarding.html/test_results.js.
+# Bypass with: git push --no-verify
+set -e
+
+cd "$(git rev-parse --show-toplevel)"
+
+if [ -x .venv/bin/python ]; then
+    PY=.venv/bin/python
+else
+    PY=python3
+fi
+
+if [ -x .venv/bin/ruff ]; then
+    echo "[pre-push] ruff check..."
+    .venv/bin/ruff check wavi/ tests/ scripts/
+fi
+
+echo "[pre-push] pytest..."
+WAVI_NO_REPORT=1 $PY -m pytest -q

wavi_lib-0.2.0/.github/workflows/test.yml

@@ -0,0 +1,24 @@
+name: test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    # Unit tests are fully offline (mocked browser, synthetic images) and
+    # platform-independent. The vision corpus (real Apple Vision OCR) is
+    # gated by WAVI_CORPUS=1 and runs only locally — see tests/corpus/README.md.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install
+        run: pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check wavi/ tests/ scripts/
+      - name: Test
+        run: pytest -v

wavi_lib-0.2.0/.gitignore

@@ -0,0 +1,42 @@
+__pycache__/
+*.pyc
+*.pyo
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.DS_Store
+
+# Chrome profiles and generated data (contain WA session — never commit)
+data/
+
+# Generated assets
+assets/*.png
+assets/*.json
+assets/*.ogg
+assets/current.png
+output/
+
+# Secrets
+.env
+
+# Local agent config
+.agent.json
+
+# Playwright CLI logs
+.playwright-cli/
+docs/.playwright-cli/
+
+# Session files (local state)
+session/
+
+# Compiled OCR binary (make ocr)
+bin/
+
+# Vision eval corpus — real WA screenshots, never commit (privacy).
+# The harness (tests/test_corpus.py) and docs stay tracked.
+tests/corpus/cases/
+
+# Claude Code local config + worktrees
+.claude/

wavi_lib-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 José Tabuyo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

wavi_lib-0.2.0/Makefile

@@ -0,0 +1,47 @@
+.PHONY: install install-dev uninstall test report boarding lint ocr corpus-baseline hooks
+
+# Enable versioned git hooks: lint on commit, lint+tests on push.
+# Bypass per-invocation with --no-verify.
+hooks:
+	chmod +x .githooks/pre-commit .githooks/pre-push
+	git config core.hooksPath .githooks
+	@echo "OK → pre-commit (ruff) + pre-push (ruff + pytest)"
+
+# Global install — isolated venv via pipx, wavi available everywhere
+install:
+	@command -v pipx >/dev/null 2>&1 || { echo "pipx not found. Run: brew install pipx && pipx ensurepath"; exit 1; }
+	pipx install --editable .
+
+# Compile the Apple Vision OCR helper to a native arm64 binary.
+# ~6x less startup overhead than interpreting the script, and Vision runs
+# natively instead of under Rosetta. vision.py picks it up automatically and
+# falls back to `swift swift/ocr_vision.swift` if bin/ is missing or stale.
+ocr:
+	mkdir -p bin
+	arch -arm64 swiftc -O swift/ocr_vision.swift -o bin/ocr_vision
+	@echo "OK → bin/ocr_vision"
+
+# Dev install — editable inside the project venv (changes take effect immediately)
+install-dev:
+	pip install -e ".[dev]"
+
+uninstall:
+	pipx uninstall wavi
+
+# Run tests (conftest.py writes docs/reports/test_results.js automatically)
+test:
+	pytest
+
+# Vision eval on the golden corpus (real OCR, macOS only, ~5-10s per case)
+corpus: ocr
+	WAVI_CORPUS=1 pytest tests/test_corpus.py -v
+
+# Run tests and open boarding page to inspect results
+report:
+	pytest && wavi boarding
+
+boarding:
+	wavi boarding
+
+lint:
+	ruff check wavi/ tests/ scripts/

wavi_lib-0.2.0/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: wavi-lib
+Version: 0.2.0
+Summary: WhatsApp automation via vision: screenshot → OCR → click
+Project-URL: Homepage, https://github.com/josetabuyo/wavi
+Project-URL: Source, https://github.com/josetabuyo/wavi
+Project-URL: Issues, https://github.com/josetabuyo/wavi/issues
+Author-email: José Tabuyo <josetabuyo@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: automation,cli,ocr,vision,whatsapp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: groq>=0.11
+Requires-Dist: numpy>=1.24
+Requires-Dist: pillow>=10.0
+Requires-Dist: playwright>=1.40
+Requires-Dist: python-dotenv>=1.2.2
+Requires-Dist: scipy>=1.11
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: pytest-asyncio>=1.4.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Provides-Extra: server
+Requires-Dist: fastapi>=0.111; extra == 'server'
+Requires-Dist: uvicorn[standard]>=0.29; extra == 'server'
+Description-Content-Type: text/markdown
+
+# wavi — WhatsApp Web Automation via Vision
+
+CLI tool for WhatsApp Web automation. Extracts message history using a vision pipeline (screenshot → OCR → bubbles), and handles navigation and sidebar state via DOM scraping.
+
+## Commands
+
+| Command | What it does | Approach |
+|---|---|---|
+| `wavi connect [session]` | Start Chrome daemon, authenticate via QR | — |
+| `wavi status [session]` | Check if daemon is alive and authenticated | DOM |
+| `wavi get <contact>` | Extract full message history from a chat (`--grow` to page through in chunks) | **Vision** |
+| `wavi send <contact> <message>` | Send a message | DOM + keyboard |
+| `wavi check-updates [session]` | Detect new inbound messages in sidebar | DOM |
+| `wavi list-contacts [session]` | List all contacts in the "New chat" panel | DOM |
+| `wavi queue [session]` | Show operation queue status | — |
+| `wavi stop [session]` | Gracefully shut down the Chrome daemon | — |
+
+## Architecture
+
+### Vision pipeline (`wavi get`)
+
+```
+Screenshot → Crop chat panel → Color-mask detection → Bbox extraction
+    ↓
+    OCR (tiled) → Timestamp extraction → Message classification → Bubble list
+```
+
+Used for message content because WhatsApp Web obfuscates the message DOM in ways that make direct scraping unreliable.
+
+Key files: `element_detector.py`, `vision.py`, `runner.py`
+
+### DOM scraping
+
+Navigation and sidebar state use JavaScript evaluated directly on the page. Each JS constant in `session.py` has a comment documenting its key selector and the vision-based fallback to implement if the selector breaks after a WA update. When a DOM-scraped feature stops working, check `session.py` → "DOM scraping inventory" block at the top.
+
+### Chrome daemon
+
+Chrome runs as a long-lived background process (started by `wavi connect`). Playwright connects and disconnects for each operation without ever killing Chrome. Killing Chrome mid-session corrupts WA's IndexedDB and invalidates the session. Shutdown is done only via `wavi stop`, which navigates to `about:blank` first so WA can flush state.
+
+## Setup
+
+```bash
+# Install uv if needed
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+git clone <repo> && cd wavi
+uv sync
+```
+
+## Quick start
+
+```bash
+# 1. Start daemon and scan QR
+wavi connect
+
+# 2. Extract message history
+wavi get "Contact Name"
+
+# 2b. Long chat — page through in blocks of 10 iterations
+wavi get "Contact Name" --grow --max-iter 10   # block 1
+wavi get "Contact Name" --grow --max-iter 10   # block 2 (continues where block 1 stopped)
+# repeat until "history is now complete" or no more messages
+
+# 3. Poll for new messages
+wavi check-updates           # first run: saves baseline
+wavi check-updates           # subsequent: no_updates or updates + contact list
+```
+
+## wavi get flags
+
+| Flag | Behavior |
+|---|---|
+| `--max-iter N` | Stop after N scroll iterations (default 300). In `--grow` mode, N counts only **new-content** iterations per run. |
+| `--from YYYY-MM-DD` | Stop scrolling when the oldest visible day pill is before this date. Drop bubbles older than the date. |
+| `--newest` | Load existing `history_bubbles.json` and stop the moment a known message is found. Prepends new messages. Goes toward the **present**. |
+| `--grow` | Load existing history, fast-forward past known content, then capture N more iterations toward the **past**. Saves a `grow_checkpoint.json` so each run continues where the last one stopped. Incompatible with `--newest`. |
+| `--assets DIR` | Override the output directory (default `output/<session>/<contact>/`). |
+| `--json-out` | Print the bubble list as JSON to stdout instead of the summary table. |
+
+### `--grow` workflow for long chats
+
+```bash
+wavi get "Contact" --grow --max-iter 10   # run 1: captures first 10 new-content iterations
+wavi get "Contact" --grow --max-iter 10   # run 2: fast-forwards to boundary, captures next 10
+# repeat — prints "history is now complete" when scrollTop reaches 0
+```
+
+State is stored in `output/<session>/<contact>/grow_checkpoint.json`. Delete it to restart from scratch (also delete `history_bubbles.json`).
+
+## check-updates behavior
+
+Compares the sidebar snapshot (last message + timestamp per chat) against the previous saved state. Reports a contact as updated only when:
+- its `last_message` changed, **and**
+- `direction == "inbound"` (outbound messages and re-reads are ignored)
+
+Direction is inferred from tick icons (`msg-check`, `msg-dbl-check`, etc.) — present → outbound; absent → inbound.
+
+**Limitation**: only the last visible message per chat is tracked. If multiple messages arrive between two checks, only the most recent is reported per contact. Use `wavi get <contact>` to retrieve the full history after detection.
+
+## Development
+
+```bash
+make ocr                  # compile the OCR helper to bin/ocr_vision (arm64, ~4x faster pipeline)
+make hooks                # git hooks: ruff on commit, ruff+pytest on push (bypass: --no-verify)
+uv run pytest tests/ -v   # unit tests (offline, mocked browser)
+make corpus               # vision eval on golden screenshots (real OCR, see tests/corpus/README.md)
+```
+
+`WAVI_TIMING=1` prints a per-stage timing breakdown of each `analyze()` run.
+Roadmap and audit: `docs/plan-mejoras.md`, `docs/audit-checklist.md`.
+
+Key files:
+- `session.py` — Chrome CDP connection + all DOM scraping JS (see inventory block)
+- `runner.py` — Orchestration: vision pipeline, `check_updates`, `list_contacts`
+- `element_detector.py` — Color-mask morphology for bubble detection
+- `vision.py` — OCR, classification, timestamp extraction
+
+## Debugging
+
+```bash
+wavi bubbles /path/to/screenshot.png --debug
+```
+
+Produces `screenshot_debug.png` with annotated boxes:
+- Green: sent messages
+- Blue: received messages
+- Red crosses: audio play button targets

wavi_lib-0.2.0/README.md

@@ -0,0 +1,127 @@
+# wavi — WhatsApp Web Automation via Vision
+
+CLI tool for WhatsApp Web automation. Extracts message history using a vision pipeline (screenshot → OCR → bubbles), and handles navigation and sidebar state via DOM scraping.
+
+## Commands
+
+| Command | What it does | Approach |
+|---|---|---|
+| `wavi connect [session]` | Start Chrome daemon, authenticate via QR | — |
+| `wavi status [session]` | Check if daemon is alive and authenticated | DOM |
+| `wavi get <contact>` | Extract full message history from a chat (`--grow` to page through in chunks) | **Vision** |
+| `wavi send <contact> <message>` | Send a message | DOM + keyboard |
+| `wavi check-updates [session]` | Detect new inbound messages in sidebar | DOM |
+| `wavi list-contacts [session]` | List all contacts in the "New chat" panel | DOM |
+| `wavi queue [session]` | Show operation queue status | — |
+| `wavi stop [session]` | Gracefully shut down the Chrome daemon | — |
+
+## Architecture
+
+### Vision pipeline (`wavi get`)
+
+```
+Screenshot → Crop chat panel → Color-mask detection → Bbox extraction
+    ↓
+    OCR (tiled) → Timestamp extraction → Message classification → Bubble list
+```
+
+Used for message content because WhatsApp Web obfuscates the message DOM in ways that make direct scraping unreliable.
+
+Key files: `element_detector.py`, `vision.py`, `runner.py`
+
+### DOM scraping
+
+Navigation and sidebar state use JavaScript evaluated directly on the page. Each JS constant in `session.py` has a comment documenting its key selector and the vision-based fallback to implement if the selector breaks after a WA update. When a DOM-scraped feature stops working, check `session.py` → "DOM scraping inventory" block at the top.
+
+### Chrome daemon
+
+Chrome runs as a long-lived background process (started by `wavi connect`). Playwright connects and disconnects for each operation without ever killing Chrome. Killing Chrome mid-session corrupts WA's IndexedDB and invalidates the session. Shutdown is done only via `wavi stop`, which navigates to `about:blank` first so WA can flush state.
+
+## Setup
+
+```bash
+# Install uv if needed
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+git clone <repo> && cd wavi
+uv sync
+```
+
+## Quick start
+
+```bash
+# 1. Start daemon and scan QR
+wavi connect
+
+# 2. Extract message history
+wavi get "Contact Name"
+
+# 2b. Long chat — page through in blocks of 10 iterations
+wavi get "Contact Name" --grow --max-iter 10   # block 1
+wavi get "Contact Name" --grow --max-iter 10   # block 2 (continues where block 1 stopped)
+# repeat until "history is now complete" or no more messages
+
+# 3. Poll for new messages
+wavi check-updates           # first run: saves baseline
+wavi check-updates           # subsequent: no_updates or updates + contact list
+```
+
+## wavi get flags
+
+| Flag | Behavior |
+|---|---|
+| `--max-iter N` | Stop after N scroll iterations (default 300). In `--grow` mode, N counts only **new-content** iterations per run. |
+| `--from YYYY-MM-DD` | Stop scrolling when the oldest visible day pill is before this date. Drop bubbles older than the date. |
+| `--newest` | Load existing `history_bubbles.json` and stop the moment a known message is found. Prepends new messages. Goes toward the **present**. |
+| `--grow` | Load existing history, fast-forward past known content, then capture N more iterations toward the **past**. Saves a `grow_checkpoint.json` so each run continues where the last one stopped. Incompatible with `--newest`. |
+| `--assets DIR` | Override the output directory (default `output/<session>/<contact>/`). |
+| `--json-out` | Print the bubble list as JSON to stdout instead of the summary table. |
+
+### `--grow` workflow for long chats
+
+```bash
+wavi get "Contact" --grow --max-iter 10   # run 1: captures first 10 new-content iterations
+wavi get "Contact" --grow --max-iter 10   # run 2: fast-forwards to boundary, captures next 10
+# repeat — prints "history is now complete" when scrollTop reaches 0
+```
+
+State is stored in `output/<session>/<contact>/grow_checkpoint.json`. Delete it to restart from scratch (also delete `history_bubbles.json`).
+
+## check-updates behavior
+
+Compares the sidebar snapshot (last message + timestamp per chat) against the previous saved state. Reports a contact as updated only when:
+- its `last_message` changed, **and**
+- `direction == "inbound"` (outbound messages and re-reads are ignored)
+
+Direction is inferred from tick icons (`msg-check`, `msg-dbl-check`, etc.) — present → outbound; absent → inbound.
+
+**Limitation**: only the last visible message per chat is tracked. If multiple messages arrive between two checks, only the most recent is reported per contact. Use `wavi get <contact>` to retrieve the full history after detection.
+
+## Development
+
+```bash
+make ocr                  # compile the OCR helper to bin/ocr_vision (arm64, ~4x faster pipeline)
+make hooks                # git hooks: ruff on commit, ruff+pytest on push (bypass: --no-verify)
+uv run pytest tests/ -v   # unit tests (offline, mocked browser)
+make corpus               # vision eval on golden screenshots (real OCR, see tests/corpus/README.md)
+```
+
+`WAVI_TIMING=1` prints a per-stage timing breakdown of each `analyze()` run.
+Roadmap and audit: `docs/plan-mejoras.md`, `docs/audit-checklist.md`.
+
+Key files:
+- `session.py` — Chrome CDP connection + all DOM scraping JS (see inventory block)
+- `runner.py` — Orchestration: vision pipeline, `check_updates`, `list_contacts`
+- `element_detector.py` — Color-mask morphology for bubble detection
+- `vision.py` — OCR, classification, timestamp extraction
+
+## Debugging
+
+```bash
+wavi bubbles /path/to/screenshot.png --debug
+```
+
+Produces `screenshot_debug.png` with annotated boxes:
+- Green: sent messages
+- Blue: received messages
+- Red crosses: audio play button targets

wavi_lib-0.2.0/docs/adr/ADR-001-vision-over-dom.md

@@ -0,0 +1,29 @@
+# ADR-001: Visión sobre DOM para extracción de contenido
+
+**Estado:** Aceptado
+**Fecha:** 2026-05 (formalizado como archivo 2026-06-11)
+
+## Contexto
+
+El DOM de WhatsApp Web está minificado y ofuscado, y cambia con cada deploy. Los
+selectores CSS y APIs JS que funcionan hoy se rompen silenciosamente mañana. El
+rendering visual, en cambio, está anclado a la percepción humana: las burbujas se
+ven como burbujas, los timestamps como timestamps — eso casi no cambia entre
+versiones de WA.
+
+## Decisión
+
+Extraer el contenido de mensajes vía screenshots + OCR (pipeline de visión), no
+vía selectores DOM. La interacción usa coordenadas físicas y eventos de teclado,
+no `page.locator()`.
+
+El DOM se usa solo como **acelerador** donde no hay alternativa razonable hoy:
+coordenadas de elementos dinámicos (compose box), estado de scroll, `data-id`
+para dedup, y captura de blobs de audio vía JS. Cada señal DOM tiene su fallback
+visual documentado en el inventario de `session.py`.
+
+## Consecuencias
+
+- Más lento que parsear DOM, pero resiliente a cualquier cambio no-visual de WA.
+- Requiere calibración de geometría/colores (ver ADR-002 y plan-mejoras Fase 2).
+- La captura de audio (bytes .ogg) es la única capacidad sin camino visual posible.

wavi_lib-0.2.0/docs/adr/ADR-002-viewport-1280x1920.md

@@ -0,0 +1,57 @@
+# ADR-002: Viewport 1280×1920 con DPR=1 forzado
+
+**Estado:** Aceptado  
+**Fecha:** 2026-05-30  
+**Relacionado:** ADR-001 (navigate_to_contact sin locators)
+
+## Contexto
+
+El pipeline de visión captura screenshots de WhatsApp Web y los analiza para detectar
+burbujas. Cuantos más mensajes quepan en un screenshot, menos iteraciones de scroll
+necesita `full-sync-enhanced` para capturar el historial completo. La resolución del
+screenshot determina directamente la cantidad de mensajes capturados por pantalla.
+
+En macOS con pantalla Retina (DPR=2), Chrome headless sin configuración explícita
+produce screenshots de ~876px de alto (limitado por la altura física de la pantalla
+dividida por DPR), en lugar de los 1920px que necesitamos.
+
+## Decisión
+
+1. **WINDOW_W = 1280, WINDOW_H = 1920** — constantes en `session.py`, fuente de verdad
+   para todo el sistema.
+
+2. **`--force-device-scale-factor=1`** en los args de Chrome (tanto `wavi connect`
+   como el fallback en `WASession.connect()`). Fuerza DPR=1 para que
+   `--window-size=1280,1920` mapee directamente a 1280×1920 píxeles CSS. Sin este
+   flag, en Mac Retina el viewport efectivo es ~640×960 CSS (DPR=2 divide el window-size).
+
+3. **`set_viewport_size(WINDOW_W, WINDOW_H)` solo antes de la primera carga de WA**
+   (cuando la página está en `about:blank`). NO se llama en reconexiones porque
+   provoca pantalla blanca en WA Web ya cargado (confirmado, commit a092e41).
+   Con `--force-device-scale-factor=1`, el viewport de Chrome es el correcto
+   sin necesitar emulación de Playwright en reconexiones.
+
+4. **WINDOW_W = 1280 es la base calibrada de la fórmula del sidebar** en `vision.py`:
+   `sidebar_x = screenshot_w * (SIDEBAR_PX / WINDOW_W)`. Esta fórmula escala
+   correctamente con DPR (screenshot_w = WINDOW_W * DPR). No cambiar WINDOW_W
+   sin recalibrar SIDEBAR_PX.
+
+## Consecuencias
+
+- Screenshots de 1280×1920 px consistentes entre ejecuciones y reconexiones.
+- ~10–12 burbujas visibles por screenshot (vs ~4 con viewport pequeño).
+- El sidebar cropping formula en vision.py sigue siendo válida para DPR=1 y DPR=2.
+- `--force-device-scale-factor=1` debe estar en TODOS los puntos de lanzamiento
+  de Chrome (CLI `connect` y fallback de `WASession.connect()`). Un punto que lo
+  omita produce imágenes "enanas" sin error visible — regresión silenciosa.
+
+## Tests de regresión
+
+`tests/test_session.py::TestViewportRegression` cubre:
+- WINDOW_W == 1280, WINDOW_H == 1920
+- `--force-device-scale-factor=1` presente en args de launch (CLI y fallback)
+- `--window-size=1280,1920` presente en args de launch
+- Screenshot dimensions verificados contra WINDOW_W × WINDOW_H
+
+Si alguno de estos tests falla, la imagen de debug tendrá menos mensajes de lo
+esperado y la captura de historial necesitará más iteraciones de scroll.

wavi_lib-0.2.0/docs/adr/ADR-003-chrome-daemon.md

@@ -0,0 +1,26 @@
+# ADR-003: Chrome como daemon de larga vida
+
+**Estado:** Aceptado
+**Fecha:** 2026-05 (formalizado como archivo 2026-06-11)
+
+## Contexto
+
+WhatsApp guarda su estado de autenticación en IndexedDB dentro del user-data-dir
+de Chrome. Matar Chrome en medio de una sesión corrompe IndexedDB y fuerza
+re-autenticación por QR.
+
+## Decisión
+
+`wavi connect` inicia Chrome una sola vez como proceso background. Todos los
+demás comandos se conectan/desconectan vía CDP sin matar Chrome nunca. El
+shutdown se hace solo con `wavi stop`, que navega a `about:blank` primero para
+que WA haga flush de IndexedDB, y recién entonces envía SIGTERM (SIGKILL solo
+tras 10s de espera).
+
+## Consecuencias
+
+- Conectar/desconectar Playwright es barato; reiniciar Chrome es caro y con
+  riesgo de pérdida de sesión.
+- Nunca usar `kill -9` directamente sobre un Chrome con sesión WA.
+- Los comandos lazy (`_lazy_session`) auto-inician y auto-detienen Chrome solo
+  si no había daemon previo.

wavi_lib-0.2.0/docs/adr/ADR-004-dom-anchor-dedup.md

@@ -0,0 +1,22 @@
+# ADR-004: Dedup por ancla DOM con fallback OCR
+
+**Estado:** Aceptado
+**Fecha:** 2026-05 (formalizado como archivo 2026-06-11)
+
+## Contexto
+
+Las regiones de scroll se solapan ~15%: un mensaje visible al fondo del frame N
+reaparece arriba del frame N+1. El texto OCR del mismo mensaje puede variar entre
+capturas (ruido, puntuación), así que una clave de contenido sola no alcanza.
+
+## Decisión
+
+Clave primaria de dedup = `dom_id` (atributo `data-id` de WA, inmutable por
+mensaje). Fallback cuando no se pudo asignar dom_id (elemento fuera de pantalla):
+clave OCR = `(sender, msg_type, text[:80], timestamp)`.
+
+## Consecuencias
+
+- Cero duplicados aun con OCR imperfecto.
+- Dependencia residual del DOM para corrección — el plan (Fase 3) agrega una
+  tercera clave por hash perceptual (dhash) del crop para eliminar esa dependencia.

wavi_lib-0.2.0/docs/adr/ADR-005-arm64-chrome.md

@@ -0,0 +1,23 @@
+# ADR-005: Chrome ARM64 nativo en macOS
+
+**Estado:** Aceptado
+**Fecha:** 2026-05 (formalizado como archivo 2026-06-11)
+
+## Contexto
+
+En Apple Silicon, Chrome lanzado sin arch explícito puede correr bajo Rosetta
+(emulación x86). El service worker y el IndexedDB de WA Web se comportan de forma
+inconsistente bajo Rosetta: la sesión aparece autenticada pero la lista de chats
+nunca carga (congelada).
+
+## Decisión
+
+Lanzar Chrome siempre con `arch -arm64` (en `wavi connect` y en el fallback de
+`WASession.connect()`).
+
+## Consecuencias
+
+- Sesiones estables; sin cuelgues de chat-list.
+- El mismo principio aplica a otros binarios: el OCR Swift también se compila
+  arm64 nativo (`make ocr`) — bajo Rosetta, Apple Vision rinde peor y devuelve
+  resultados ligeramente distintos.

wavi_lib-0.2.0/docs/adr/ADR-006-optimistic-headless-connect.md

@@ -0,0 +1,24 @@
+# ADR-006: Connect headless optimista
+
+**Estado:** Aceptado
+**Fecha:** 2026-05 (formalizado como archivo 2026-06-11)
+
+## Contexto
+
+Una vez autenticada, la sesión vive en el user-data-dir de Chrome y headless la
+restaura silenciosamente. Abrir una ventana visible sin necesidad es disruptivo
+y más lento.
+
+## Decisión
+
+`wavi connect` siempre intenta headless primero. Solo si hace falta QR, lo
+captura igualmente en headless y escribe `data/qr.html` (QR en base64 + countdown
+de 60s) para escanear desde el browser del usuario — nunca se abre una ventana
+de Chrome visible. La expiración del QR se detecta por cambio del atributo
+`data-ref` (fallback: timer de 65s).
+
+## Consecuencias
+
+- Cero ventanas visibles en el flujo completo.
+- Tras el escaneo, la carpeta de sesión se renombra al número de teléfono
+  detectado y el alias `.default` apunta a ella.