ca-archive/MIGRATION.md

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:

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

AHORA:

<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:

   # 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:

<!-- 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).