Contributing es

Contribuir

English | 中文 | 日本語 | 한국어 | Español | Português | Русский

Comandos

npm test                        # full test suite (Node built-in runner, no build needed)
node --test test/foo.test.mjs   # single file
npm run package                 # build the versioned zip (browsa-vX.Y.Z.zip)
npm run build                   # esbuild vendor bundle (only needed after build.mjs changes)
bash check-compat.sh            # static compatibility check

La restricción de la caja de 4GB: la suite son 103 archivos (~36 con jsdom pesado) en un VPS de 2CPU/4GB; el script limita la concurrencia a 2, preferir --test-concurrency=1 en 4GB. Nunca asignar blobs de decenas de MB en los tests (un único mock de 44MB agotó la memoria de la caja una vez — recurrencia real); preferir tests de funciones puras (sin DOM, sin buffers grandes).

Filosofía de testing

• Los tests hacen mock del global chrome antes de importar los módulos reales; los tests jsdom usan los bundles REALES vendoreados de marked/DOMPurify/katex/highlight.js, no sustitutos.
• sidepanel.js no tiene ninguna exportación — sus tests cargan todo sidepanel.html en jsdom y lo manejan como caja negra (clics/teclas/mensajes de puerto simulados).
• Los clientes de worker conservan singletons a nivel de módulo → los escenarios que necesiten un singleton fresco DEBEN ser archivos de test SEPARADOS (el runner aísla por archivo/proceso).
• Disciplina de lockstep: los hechos reflejados en varios lugares (regexes, nombres de campos, pares CSS/hint, orden de pestañas) o colapsan en una única fuente o quedan fijados por source-regex con una nota en AGENTS.md de «cambiar ambos en lockstep». Ejemplo: subchat.test.mjs fija con regex la línea fuente exacta pushSubChatChunk(… SUBCHAT_DONE …).
• Los tests de hilo de detalle / streaming DEBEN terminar el turno (DONE / ■ / cerrar), o el intervalo SW_PING de 20s del puerto del turno queda filtrado y cuelga el runner.
• WASM es la excepción a «sin ejecución real»: WebAssembly.instantiate corre en Node, así que los tests de pdf-inspector ejecutan el binario real vendoreado.

Principios de refactorización (ganados a través de incidentes; de AGENTS.md)

• N casos de switch que solo difieren en literales → una tabla de búsqueda; dos implementaciones escritas a mano del mismo protocolo de red → una función compartida con hooks (la deriva del DONE-handler fue una familia real de bugs).
• Tras cada extracción ejecutar la suite COMPLETA Y check-compat.sh — una comprobación de sintaxis no prueba nada.
• Grep en todo el repositorio (incluido test/) antes de declarar muerta una exportación; una exportación de uso exclusivo en tests no está automáticamente muerta — leer los comentarios de alrededor.

dev-preview (vista previa de la UI de la extensión en entornos headless)

node dev-preview/gen.mjs        # regenerate preview pages from real sidepanel.html (rerun after HTML changes)
python3 -m http.server 8931     # from the repo root
# http://127.0.0.1:8931/dev-preview/sidepanel.preview.html

Un chrome-shim proporciona la superficie mínima de chrome.*; seed.js inyecta un historial rico. Las capturas de pantalla pasan por CDP Page.captureScreenshot (plano, sin clip/scale; page.screenshot() tiene artefactos en modo oscuro). Una vista previa en verde ≠ una extensión real en verde: los sobres sendMessage del shim deben reflejar el contrato real byte a byte, y la verificación de tipo CSP siempre exige una carga real de la extensión.

Flujo de release

1. Subir la versión en manifest.json Y en package.json.
2. PR → CI en verde → squash-merge a main → rellenar dev hacia atrás: git reset --hard origin/main && git push --force-with-lease origin dev (un back-fill por merge contamina main..dev; el botón Delete branch de la página del PR borraría dev).
3. Los PRs de subida de versión fluyen por los workflows de release reutilizables (xiaohuzai/release-flow@v1) con tests exonerados (modo PAT).
4. El texto del listing de la store se genera con la skill .agents/skills/cws-listing (el tag es la fuente de verdad de la versión); el historial de rechazos queda registrado.
5. Disciplina de sincronización de docs (cualquier cambio visible para el usuario, mismo PR): README en ambos idiomas (espejos alineados por secciones) → el sitio de docs (ambos idiomas) → capturas/banners/GIF demo/vídeo promocional, cada uno CONSIDERADO (la legibilidad se juzga a la resolución propia del asset; un GIF cambiado debe cambiar de nombre de archivo para vencer las cachés) → los hechos a nivel de arquitectura se registran en AGENTS.md.

Líneas rojas (lista rápida)

Sin auto-commit/empaquetado (esperar instrucción explícita) · sin ejecución completa de tests antes de empaquetar (verde dirigido basta) · usar la versión actual, nunca subir la versión por cuenta propia · la clave privada de la extensión nunca sale de /root/workspace/browsa-keys/ · los textos orientados al usuario evitan la jerga (el zh no lleva jerga en inglés) · los píxeles de imagen almacenados nunca se destruyen · thinking por defecto omit.

---

Versiones autoritativas: Contributing (inglés) / Contributing-zh (chino) — instantánea de primera traducción por IA, sincronizada el 2026-10-01.