Arquitectura

Esta página ofrece una visión general del código para orientarse antes de contribuir. La referencia detallada (convenciones, agentes de Claude, convenciones de tests E2E) vive en el archivo CLAUDE.md del repositorio.

Entry points

Archivo	Función
src/entrypoints/background.ts	Service worker (MV3) o background script (MV2). Delega en src/background/.
src/entrypoints/content.content.ts	Content script inyectado en todas las páginas. Captura los clics centrales y los clics derechos sobre los enlaces.
src/entrypoints/popup.html	Cáscara HTML del popup. La lógica vive en src/popup.tsx.
src/entrypoints/options.html	Cáscara HTML de la página Opciones. La lógica vive en src/options.tsx.

Módulos background

En src/background/:

Módulo	Función
index.ts	Arranque del background: registra los listeners, conecta el distintivo del icono e inicializa los espacios de trabajo.
grouping.ts	Creación de grupos de Chrome a partir de las reglas. Extracción de nombre con regex sobre título / URL.
deduplication.ts	Detección y cierre de duplicados. Gestión del Deshacer mediante deduplicationSkip.
organize.ts	Acción Organizar pestañas: aplica las reglas a las pestañas ya abiertas.
event-handlers.ts	Vincula los listeners tabs.onCreated, tabs.onUpdated, tabs.onRemoved, etc.
messaging.ts	Mensajes background y popup (aviso del nombre de grupo, notificaciones).
migration.ts	Migraciones one-shot: sync a local, alta del campo fallbackLabel, archivo de sesiones.
settings.ts	Lectura de los ajustes con fallback sobre los valores por defecto.
actionBadge.ts	Distintivo G / D / X en el icono, sigue los interruptores globales del espacio activo.

Hooks centrales

En src/hooks/:

Hook	Función
useSettings	Lectura y escritura de los ajustes globales. Usa refs para prevenir condiciones de carrera.
useStorageState	Fachada unificada para browser.storage.local y browser.storage.session.
useSessions	Fachada para los tres compartimentos (pinned, active, archived) con hooks por bucket.
useSessionEditor	Edición de una sesión: drag-and-drop, renombrado, eliminación de pestañas, anti-reentrada.
useStatistics	Contadores aislados por espacio de trabajo.
useDeepLinking	Sincronización del hash de la URL con el estado de UI (por ejemplo #sessions/archived).

Esquemas Zod

En src/schemas/:

Esquema	Cubre
common.ts	Tipos primitivos compartidos.
domainRule.ts	Una regla de dominio.
enums.ts	Enumeraciones (modos de nombrado, estrategias de dedup, acciones de restauración, distintivos).
importExport.ts	Formato de los archivos de import-export, versión relajada para tolerar archivos antiguos.
session.ts	Una sesión con sus pestañas y sus grupos internos.
workspace.ts	Metadatos de un espacio de trabajo.
pack.ts	Manifiesto de un pack (packFileSchema).
category.ts	Una categoría (emoji, etiqueta, builtIn).

Componentes

En src/components/:

• Core/: componentes ligados a un concepto de negocio. DomainRule/, Session/, Statistics/, TabTree/.
• UI/: componentes de interfaz transversales. Header/, PopupHeader/, PopupToolbar/, Sidebar/, WizardStepper/, ImportExportWizards/, SessionWizards/, SettingsPage/, etc.
• Form/: campos de formulario reutilizables (FormFields/).

El reparto se documenta en CLAUDE.md.

Internacionalización

getMessage() en src/utils/i18n.ts es el único punto de acceso a las cadenas. Los mensajes viven en public/_locales/{en,fr,es}/messages.json. Cualquier cadena de UI (label, aria-label, title, placeholder) pasa por getMessage(). Sin strings codificados a mano.

Tests

Tres pipelines:

• Vitest (tests/): tests unitarios de utils, hooks y módulos background.
• Playwright E2E (tests/e2e/): recorridos funcionales sobre Chrome MV3.
• Playwright doc-scenarios (e2e-doc-scenarios/): capturas narrativas para la documentación. No se ejecuta sobre las PR.

La arquitectura compartida de los tres pipelines (Page Objects, Domain Actions, fixtures-base) vive en e2e-shared/ y se documenta en su README.

Siguiente paso

Stack técnicoLas tecnologías de fondo.

Repositorio GitHubCódigo fuente, issues, pull requests.

CLAUDE.mdConvenciones detalladas del proyecto.