# Migración a WebExtensions (Versión 3.0)

## Resumen de cambios

La extensión Classic Add-ons Archive ha sido modernizada desde el sistema legacy XUL/XPCOM a WebExtensions para ser compatible con navegadores modernos Firefox (57+) y Chrome.

## Cambios principales

### 1. Sistema de manifiesto

**ANTES (Legacy):**
- `install.rdf` - Manifiesto XML
- `chrome.manifest` - Registro de recursos chrome://
- `bootstrap.js` - Script de arranque con XPCOM

**AHORA (WebExtensions):**
- `manifest.json` - Manifiesto estándar WebExtensions (Manifest V2)
- `background.js` - Script de fondo con APIs modernas

### 2. Protocolo de navegación

**ANTES:**
```
caa:list
caa:addon/some-addon
caa:about
```

**AHORA:**
```
chrome-extension://.../content/ca-archive.html#list
chrome-extension://.../content/ca-archive.html#addon/some-addon
chrome-extension://.../content/ca-archive.html#about
```

La navegación ahora usa hash (#) en lugar de un protocolo personalizado.

### 3. Acceso a recursos

**ANTES:**
```html
<link href="chrome://ca-archive/skin/ca-archive.css">
<script src="chrome://ca-archive/content/ca-archive.js">
```

**AHORA:**
```html
<link href="../skin/ca-archive.css">
<script src="ca-archive.js">
```

Todos los recursos usan rutas relativas.

### 4. Base de datos SQLite

**ANTES:**
- Acceso directo a SQLite usando `mozIStorageService`
- Almacenamiento en perfil del usuario

**AHORA:**
- Usa `sql.js` (SQLite compilado a JavaScript/WebAssembly)
- Base de datos almacenada en `browser.storage.local`
- Primera carga descarga y cachea la DB

### 5. APIs reemplazadas

| Legacy API | WebExtensions API |
|------------|-------------------|
| `Components.utils` | Scripts estándar ES6 |
| `Services.prefs` | `browser.storage.local` |
| `Services.wm` | `browser.tabs` y `browser.windows` |
| `mozIStorageService` | `sql.js` |
| `XPCOMUtils` | APIs nativas del navegador |
| `Cu.import()` | `import` / carga dinámica de scripts |

### 6. Interfaz de usuario

**ANTES:**
- Botón insertado directamente en la barra de herramientas
- Menú en Tools

**AHORA:**
- `browser.browserAction` - Botón estándar en la barra
- Sin menú en Tools (no disponible en WebExtensions)

## Estructura de archivos

### Archivos nuevos
- `manifest.json` - Manifiesto WebExtensions
- `background.js` - Script de fondo
- `content/db-webext.js` - Wrapper de base de datos moderno

### Archivos modificados
- `content/ca-archive.html` - Rutas relativas, navegación por hash
- `content/ca-archive.js` - Sin Components, carga dinámica de módulos

### Archivos obsoletos (ya no se usan)
- `install.rdf` - Reemplazado por manifest.json
- `chrome.manifest` - Ya no necesario
- `bootstrap.js` - Reemplazado por background.js
- `update.xml` - Actualizaciones ahora vía Firefox/Chrome stores

## Compatibilidad

### Navegadores soportados

| Navegador | Versión mínima | Notas |
|-----------|----------------|-------|
| Firefox | 57+ (Quantum) | Soporte completo |
| Chrome | 80+ | Requiere manifest V2 |
| Edge (Chromium) | 80+ | Compatible con Chrome |
| Brave | 1.20+ | Compatible con Chrome |
| Vivaldi | 3.0+ | Compatible con Chrome |

### Navegadores NO soportados

Los siguientes navegadores que usaban la versión legacy ya no son compatibles con la versión WebExtensions:

- Firefox ESR 45-52
- Firefox 45-56
- Pale Moon
- Basilisk
- Waterfox Classic (pre-Current)
- SeaMonkey

**Nota:** Para estos navegadores, seguir usando la versión 2.x legacy.

## Instalación

### Firefox

1. **Desde archivo local:**
   ```bash
   # Empaquetar la extensión
   cd /home/ale/projects/firefox/ca-archive
   zip -r ca-archive-3.0.zip * -x ".*" -x "*.md" -x "update.xml" -x "install.rdf" -x "chrome.manifest" -x "bootstrap.js"
   ```
   
2. En Firefox, ir a `about:debugging` > Este Firefox > Cargar extensión temporal
3. Seleccionar el archivo `manifest.json` o el archivo `.zip`

### Chrome/Edge/Brave

1. Ir a `chrome://extensions/`
2. Activar "Modo de desarrollador"
3. Click en "Cargar extensión sin empaquetar"
4. Seleccionar la carpeta del proyecto

## Desarrollo

### Dependencias

La extensión requiere `sql.js` para el acceso a la base de datos SQLite:

```html
<!-- Cargado automáticamente desde CDN en db-webext.js -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/sql.js/1.8.0/sql-wasm.js"></script>
```

**Para producción:** Descargar sql.js localmente y actualizar las rutas en `db-webext.js`.

### Debugging

**Firefox:**
- `about:debugging` > Inspeccionar
- Console del navegador: `Ctrl+Shift+J`

**Chrome:**
- `chrome://extensions/` > Detalles > Inspeccionar vistas: background page
- DevTools: `F12`

### Testing

1. Abrir la extensión
2. Verificar que la base de datos se carga correctamente
3. Probar navegación: listados, búsquedas, detalles de addons
4. Verificar que las descargas funcionan

## Limitaciones conocidas

### WebExtensions vs Legacy

1. **Multi-proceso (e10s):** Ahora sólo funciona con e10s activado
2. **Protocolo personalizado:** Ya no disponible, usa rutas de extensión
3. **Modificación de AMO pages:** No puede inyectar hints en addons.mozilla.org
4. **Barra de herramientas:** Botón en ubicación fija, no personalizable
5. **Storage:** Base de datos limitada por cuota de storage del navegador

### Tamaño de base de datos

Chrome/Firefox tienen límites de storage:
- Chrome: ~10MB en `storage.local` (puede ampliarse con `unlimitedStorage`)
- Firefox: Sin límite práctico en `storage.local`

Si la base de datos es muy grande (>10MB), considerar:
1. Agregar permiso `unlimitedStorage` en manifest.json
2. Usar chunks/compresión
3. Almacenar en IndexedDB

## Migración de datos de usuario

La nueva versión NO migra automáticamente datos de la versión legacy porque:

1. Las APIs de storage son completamente diferentes
2. La base de datos se descarga nueva en cada instalación
3. No hay configuraciones de usuario persistentes

## Próximos pasos

### Para publicar en stores

1. **Firefox Add-ons (AMO):**
   - Crear cuenta en addons.mozilla.org
   - Subir archivo .zip
   - Esperar revisión

2. **Chrome Web Store:**
   - Crear cuenta de desarrollador ($5 USD único)
   - Subir archivo .zip
   - Completar listing

### Mejoras futuras

- [ ] Migrar a Manifest V3 (cuando Firefox tenga mejor soporte)
- [ ] Offline-first: cachear más contenido
- [ ] Sincronización de favoritos/bookmarks
- [ ] Dark mode
- [ ] Búsqueda mejorada con índices

## Soporte

- GitHub: https://github.com/JustOff/ca-archive/
- Issues: https://github.com/JustOff/ca-archive/issues

## Licencia

La extensión continúa bajo Mozilla Public License 2.0 (MPL-2.0).