docs: add developer context file for architecture and future AI coding sessions

docs/developer_context.md

@@ -0,0 +1,63 @@
+# Contexto de Desarrollo y Arquitectura - Almeira Web
+
+Este archivo sirve como memoria técnica e histórica para los desarrolladores y agentes de IA (como Antigravity) que continúen trabajando en este proyecto.
+
+---
+
+## 🛠️ Stack Tecnológico
+* **Core**: Next.js 16 (App Router, con Server Actions habilitados).
+* **Base de Datos y Backend**: Appwrite (Autenticación, Base de datos y Almacenamiento).
+* **Editor de Contenido**: Tiptap Editor (Rich Text con soporte para imágenes, videos y embeds).
+* **Estilos**: TailwindCSS.
+* **Empaquetado**: Node standalone.
+
+---
+
+## 📂 Configuración del Entorno (`.env.local`)
+Para levantar el proyecto en desarrollo local (`npm run dev`), se requiere un archivo `.env.local` en la raíz con el siguiente formato:
+
+```env
+NEXT_PUBLIC_APPWRITE_ENDPOINT=https://appwrite.almeira.com.co/v1
+NEXT_PUBLIC_APPWRITE_PROJECT_ID=69b84df5003bd8957c5c
+APPWRITE_API_KEY=standard_cce3cd... (Ver Gitea o Consola Appwrite)
+APPWRITE_DATABASE_ID=almeira
+NEXT_PUBLIC_APPWRITE_MEDIA_BUCKET_ID=media_bucket
+
+# Evolution API (WhatsApp)
+EVOLUTION_API_URL=https://evolution.almeira.com.co
+EVOLUTION_API_KEY=mgXxu2eA...
+EVOLUTION_INSTANCE_NAME=AutomataAlmeira
+
+# Server Config
+SERVER_ACTIONS_BODY_SIZE_LIMIT=100mb
+```
+
+---
+
+## 🎬 Solución del Reproductor de Video (Hito Clave)
+Durante el desarrollo, se resolvió un problema crítico donde los videos subidos a las publicaciones no se reproducían en producción:
+
+### 1. El Origen del Problema
+Appwrite utiliza el endpoint `/preview` para imágenes y miniaturas. Sin embargo, para archivos de video, el navegador requiere soporte de reproducción por rangos (Range Requests) y streaming. El endpoint `/preview` limita la reproducción y bloquea el video en Safari y Chrome. La solución es usar el endpoint `/view`.
+
+### 2. Implementación de la Corrección
+* **En el Editor (`RichTextEditor.tsx` / `MediaGridSelector.tsx`)**: Se configuró la biblioteca de medios y el nodo de video de Tiptap para reemplazar automáticamente `/preview?` por `/view?` en las URLs de origen de los videos.
+* **En el Servidor (`entities.ts`)**: Se actualizó el validador `safeHtmlSchema` que limpia el código HTML con `DOMPurify` para permitir las etiquetas `<video>` y `<source>`, junto a los atributos `controls`, `src`, `muted`, `loop`, `autoplay`, `preload` y `poster`. Además, normaliza cualquier URL de video errónea antes de guardarla en la base de datos.
+* **En la Publicación (`[slug]/page.tsx`)**: Se implementó una mejora dinámica que extrae el primer video del contenido y lo coloca como **Hero Media** en la cabecera (usando la imagen destacada como `poster` de portada), eliminando el video redundante del cuerpo del texto. También normaliza URLs antiguas al vuelo.
+
+---
+
+## 🔄 Scripts de Despliegue y Compilación
+* **`package-hostinger.sh`**: Script Bash que compila el proyecto en modo `standalone`, copia los assets estáticos de `.next/static` y `public/`, inyecta la configuración para PM2 (`ecosystem.config.js`), configura el `package.json` para que Hostinger corra directamente `server.js` y comprime todo en un archivo zip listo para subir: **`almeira-web-deploy.zip`**.
+
+### Comando para empaquetar:
+```bash
+PATH="/home/carlos/.nvm/versions/node/v22.14.0/bin:$PATH" bash package-hostinger.sh
+```
+
+---
+
+## 💡 Instrucciones para Agentes de IA (Continuar Trabajo)
+Si eres un asistente de codificación de IA (como Antigravity), ten en cuenta lo siguiente al iniciar:
+1. Este proyecto utiliza Next.js standalone. Cualquier cambio en las rutas o componentes debe comprobarse compilando el proyecto localmente.
+2. La sanitización de HTML es muy estricta. Si necesitas añadir nuevos tags interactivos a las publicaciones, debes agregarlos al whitelist de `safeHtmlSchema` en `src/app/actions/entities.ts` y al sanitizador en `src/app/[slug]/page.tsx`.