# Guía de Instalación Rápida - Classic Add-ons Archive v3.0

## Para Desarrolladores / Testing Local

### Firefox

**Opción 1: Carga temporal (recomendado para desarrollo)**

1. Abre Firefox
2. Escribe en la barra de direcciones: `about:debugging#/runtime/this-firefox`
3. Click en "Cargar complemento temporal..."
4. Navega a la carpeta del proyecto y selecciona el archivo `manifest.json`

La extensión se instalará hasta que cierres Firefox.

**Opción 2: Instalación sin firma (Firefox Developer/Nightly)**

Firefox normal NO permite instalar extensiones sin firma. Usa una de estas versiones:

1. **Firefox Developer Edition** o **Firefox Nightly**:
   - Descarga: https://www.mozilla.org/firefox/developer/
   - Descarga: https://www.mozilla.org/firefox/nightly/

2. **Deshabilitar verificación de firma:**
   - Escribe en la barra: `about:config`
   - Acepta el riesgo
   - Busca: `xpinstall.signatures.required`
   - Cambia a `false` (doble click)

3. **Instalar la extensión:**
   ```bash
   # Empaquetar
   cd /home/ale/projects/firefox/ca-archive
   ./build.sh
   
   # O manualmente:
   zip -r ca-archive-3.0.xpi manifest.json background.js content/ skin/ -x "*.git*" -x "*~"
   ```
   
4. Arrastra el archivo `.xpi` a Firefox

**⚠️ IMPORTANTE:** Firefox normal (Release) NO acepta `xpinstall.signatures.required=false`. Solo funciona en Developer/Nightly/Unbranded.

**Opción 3: Instalación permanente con firma AMO (distribución)**

1. Obtener credenciales AMO: https://addons.mozilla.org/developers/addon/api/key/
2. Configurar en `private-keys/firefox-amo-credentials.json`
3. Firmar: `./build.sh --sign`
4. Instalar el `.xpi` firmado resultante

### Chrome / Edge / Brave

**⚠️ PROBLEMA CONOCIDO: Manifest v2 deprecado en Chrome**

Chrome está migrando a Manifest v3. Esta extensión usa Manifest v2 y puede:
- ✅ Funcionar en Edge/Brave (soporte extendido hasta ~2024-2025)
- ⚠️ Mostrar advertencias en Chrome
- ❌ Dejar de funcionar en Chrome 127+ (junio 2024)

**Si Chrome rechaza el manifest:**

1. Verifica la versión de Chrome: `chrome://settings/help`
2. Si es Chrome 127+, necesitas Manifest v3 (aún no implementado)
3. **Alternativa temporal:** Usa Microsoft Edge o Brave (soportan v2 más tiempo)

**Modo desarrollador (sin empaquetar) - Solo Chrome <127:**

1. Abre el navegador
2. Ve a: `chrome://extensions/` (o `edge://extensions/`)
3. Activa el interruptor "Modo de desarrollador" (esquina superior derecha)
4. Click en "Cargar extensión sin empaquetar"
5. Selecciona la carpeta: `/home/ale/projects/firefox/ca-archive`

La extensión quedará instalada permanentemente en modo desarrollo.

**Errores comunes en Chrome:**

- **"Manifest version 2 is deprecated":**
  - ⚠️ Solo advertencia (aún funciona)
  - Chrome mostrará recordatorio hasta que migres a v3

- **"Manifest version 2 is not supported":**
  - ❌ Chrome 127+ bloquea v2 completamente
  - **Solución:** Usa Firefox, Edge o Brave
  - **O espera:** Implementación de Manifest v3 (pendiente)

**Empaquetar para distribución:**

```bash
cd /home/ale/projects/firefox/ca-archive

# Construir paquetes sin firmar
./build.sh

# O con firma (requiere configurar claves primero)
./scripts/generate-keys.sh  # Primera vez
./build.sh --sign           # Construir firmado
```

**Para distribución con firma**, ver [SIGNING.md](SIGNING.md).

## Verificación de Instalación

Después de instalar, deberías ver:

1. ✅ Icono de la extensión en la barra de herramientas
2. ✅ Click en el icono abre la página del catálogo
3. ✅ Mensaje de carga de base de datos (primera vez)
4. ✅ Navegación funcionando (categorías, búsqueda, etc.)

## Troubleshooting

### La base de datos no carga

**Error:** "Loading database for the first time. Please wait..."

**Solución:**
1. Asegúrate de tener la carpeta `content/db/` con el archivo SQLite
2. Verifica que el archivo `ca-archive-19030501.sqlite` exista y no esté corrupto
3. Revisa la consola del navegador (`F12` > Console) para errores específicos

### El icono no aparece

**Solución:**
1. Refresca la página `about:debugging` o `chrome://extensions/`
2. Verifica que `manifest.json` tiene el campo `browser_action` correctamente
3. Revisa que las imágenes en `skin/button.png` existan

### Errores de carga de scripts

**Error:** "Failed to load script: ..."

**Solución:**
1. Verifica que todos los archivos JS estén en `content/`
2. Revisa la política CSP en `manifest.json`
3. Asegúrate de que `db-webext.js` se carga antes de `ca-archive.js`

### sql.js no carga

**Error:** "Could not load SQL engine"

**Solución:**
1. Verifica conexión a internet (se descarga desde CDN)
2. O descarga sql.js localmente:
   ```bash
   cd content/
   wget https://cdnjs.cloudflare.com/ajax/libs/sql.js/1.8.0/sql-wasm.js
   wget https://cdnjs.cloudflare.com/ajax/libs/sql.js/1.8.0/sql-wasm.wasm
   ```
3. Actualiza las rutas en `content/db-webext.js`

### web-ext no disponible (para firma)

**Solución:**
```bash
# Instalar dependencias locales (recomendado)
npm install

# O instalación global (alternativa)
npm install -g web-ext
```

El script `build.sh` detecta automáticamente web-ext en `node_modules/.bin/`

## Para Usuarios Finales

### Instalar desde archivo .xpi/.zip

**Firefox:**
1. Descarga el archivo `.xpi`
2. Arrastra y suelta en Firefox
3. Autoriza la instalación

**Chrome:**
1. Descarga el archivo `.zip`
2. Descomprime en una carpeta
3. Sigue los pasos de "Modo desarrollador" arriba

### Instalar desde stores (cuando esté publicado)

**Firefox Add-ons (AMO):**
- Visita: https://addons.mozilla.org/firefox/addon/ca-archive/
- Click en "Añadir a Firefox"

**Chrome Web Store:**
- Visita: [URL de Chrome Web Store]
- Click en "Añadir a Chrome"

## Desinstalación

### Firefox
1. `about:addons` > Extensiones
2. Busca "Classic Add-ons Archive"
3. Click en "..." > Eliminar

### Chrome
1. `chrome://extensions/`
2. Busca la extensión
3. Click en "Eliminar"

## Archivos Necesarios

Archivos mínimos para que funcione la extensión:

```
ca-archive/
├── manifest.json          ← REQUERIDO
├── background.js          ← REQUERIDO
├── content/
│   ├── ca-archive.html    ← REQUERIDO
│   ├── ca-archive.js      ← REQUERIDO
│   ├── db-webext.js       ← REQUERIDO
│   ├── db/
│   │   └── ca-archive-19030501.sqlite  ← REQUERIDO
│   ├── addon.js
│   ├── list.js
│   ├── versions.js
│   ├── tcloud.js
│   ├── about.js
│   └── epl.js
└── skin/
    ├── logo.png           ← REQUERIDO
    ├── button.png         ← REQUERIDO
    ├── ca-archive.css     ← REQUERIDO
    └── ...
```

## Siguientes Pasos

Una vez instalada y funcionando:

1. 📖 Lee [MIGRATION.md](MIGRATION.md) para entender los cambios
2. 🔧 Si eres desarrollador, revisa la arquitectura modernizada
3. 🐛 Reporta bugs en GitHub Issues
4. 🌟 Si te gusta, deja una valoración

## Soporte

- 📝 Documentación completa: [MIGRATION.md](MIGRATION.md)
- 🐛 Reportar problemas: https://github.com/JustOff/ca-archive/issues
- 💬 Discusiones: https://github.com/JustOff/ca-archive/discussions