docs(v3): close V3 technical phase

docs/MODULAQ_V3_CONTEXT.md

@@ -0,0 +1,354 @@
+# Modulaq V3 - Contexto formal de cierre
+
+## 1. Portada / estado del documento
+
+| Campo | Valor |
+|---|---|
+| Proyecto | Modulaq |
+| Version cerrada | V3.0 + V3.1 |
+| Fecha | 2026-06-01 |
+| Estado | V3 cerrada como fase tecnica; no abrir V3.2 todavia |
+| Uso recomendado | Documento de contexto inicial para futuros chats, auditorias, planificacion Post-V3 y decisiones antes de npm/backend/API |
+
+Este documento consolida el estado final de Modulaq V3. Debe usarse como punto de partida antes de proponer cambios nuevos. Si un futuro chat necesita trabajar sobre Modulaq, primero debe asumir que V3 ya cumplio su objetivo tecnico y que la siguiente fase recomendada es Post-V3 SEO/Growth organico.
+
+---
+
+## 2. Resumen ejecutivo
+
+V3 fue la fase de separacion tecnica de Modulaq: la logica reutilizable de las herramientas paso a vivir en un SDK local llamado `@modulaq/core`, consumido por la app mediante adapters delgados.
+
+El problema que resolvio fue el acoplamiento entre herramientas React y logica de dominio. En V2, las herramientas ya tenian services separados, pero la logica todavia vivia dentro de la app. En V3, esa logica se consolido como paquete interno, browser-first y reusable.
+
+Respecto a V2, V3 cambio principalmente esto:
+
+- Creo `packages/core` como SDK local.
+- Definio subpath exports claros.
+- Migro las herramientas relevantes para consumir el SDK.
+- Agrego tests automatizados.
+- Integro test + build en GitHub Actions.
+- Cerro la fase con auditoria final en `docs/V3_FINAL_AUDIT.md`.
+
+Lo que no se hizo en V3:
+
+- No se publico en npm.
+- No se agrego backend.
+- No se creo API publica.
+- No se agrego login.
+- No se agrego monetizacion.
+- No se abrio V3.2.
+- No se tocaron SEO/SSG como linea de trabajo nueva.
+- No se prometio OCR ni compresion real de PDF.
+
+---
+
+## 3. Estado final de V3
+
+Estado final consolidado:
+
+- SDK local: `@modulaq/core` existe en `packages/core`.
+- Tests: `npm run test:run` pasa con 110 tests verdes.
+- Build: `npm run build` pasa.
+- CI: GitHub Actions ejecuta `npm ci`, `npm run test:run` y `npm run build`.
+- Branch protection: branch ruleset/protection configurado con check requerido `Test + Build`.
+- Herramientas migradas: 9 herramientas consumen el SDK mediante adapters.
+- Herramienta excluida: `Comprimir PDF` queda fuera del SDK por decision deliberada.
+
+Conclusion: V3 puede considerarse cerrada como fase tecnica. La deuda pendiente no bloquea el cierre; si bloquea publicar npm, abrir backend/API o prometer soporte publico.
+
+---
+
+## 4. Arquitectura del SDK
+
+El SDK local se llama `@modulaq/core`.
+
+Ubicacion:
+
+```text
+packages/core
+```
+
+Caracteristicas:
+
+- Local/private dentro del monorepo.
+- `private: true`.
+- Version interna `0.1.0`.
+- Browser-first.
+- ESM.
+- Sin React.
+- Sin UI.
+- Sin npm publish.
+- Consumido por la app via workspace local.
+
+Subpaths:
+
+| Subpath | Responsabilidad |
+|---|---|
+| `@modulaq/core/text` | Limpieza de texto y estadisticas |
+| `@modulaq/core/qr` | Validacion, armado y generacion de QR |
+| `@modulaq/core/pdf` | Operaciones PDF basadas en `pdf-lib` |
+| `@modulaq/core/pdf-render` | Extraccion/render PDF con `pdfjs-dist`, worker y canvas |
+| `@modulaq/core/files` | Helpers de nombres de archivo y extensiones |
+| `@modulaq/core/ranges` | Parseo de rangos/selecciones de paginas |
+
+Decision importante: `pdf-render` esta separado de `pdf` para que las funciones ligeras de `pdf-lib` no arrastren por accidente el peso y complejidad de `pdfjs-dist`.
+
+---
+
+## 5. Herramientas migradas al SDK
+
+Herramientas migradas:
+
+- Limpiador de texto
+- Generador QR
+- Contador de paginas PDF
+- Unir PDFs
+- Reordenar paginas PDF
+- Dividir PDF
+- Imagen a PDF
+- Extraer texto de PDF
+- PDF a imagenes
+
+Modelo de migracion:
+
+- La UI React permanece en `src/tools`.
+- Los `*.service.ts` funcionan como adapters delgados.
+- El SDK devuelve primitivas y estructuras reutilizables.
+- La app conserva mensajes, nombres de descarga, empaquetado ZIP, limites UX y detalles de presentacion.
+
+---
+
+## 6. Herramienta excluida deliberadamente
+
+### Comprimir PDF
+
+`Comprimir PDF` sigue fuera del SDK.
+
+Motivo: la herramienta actual no garantiza compresion real de imagenes ni reduccion profunda de estructura interna del PDF. Publicar una funcion de SDK con ese nombre podria inducir a error y crear una promesa tecnica falsa.
+
+Estado correcto:
+
+- Puede seguir existiendo como herramienta de la app.
+- No debe promoverse como API reusable de compresion real.
+- No debe bloquear el cierre de V3.
+- Cualquier mejora futura debe tratarse como trabajo separado, no como deuda de V3.
+
+---
+
+## 7. Testing
+
+Stack de testing:
+
+- Vitest.
+- happy-dom.
+- Fixtures PDF e imagenes en `packages/core/test-fixtures`.
+
+Resultado actual:
+
+- 18 archivos de test.
+- 110 tests automatizados.
+- `npm run test:run` verde.
+
+Cobertura funcional observada:
+
+- `text`: limpieza y estadisticas.
+- `qr`: validacion, valores, tamanos y data URL.
+- `files`: sanitizacion, extensiones y nombres base.
+- `ranges`: parseo de seleccion de paginas.
+- `pdf`: count, merge, reorder, split range, extract pages e images to PDF.
+- Utils compartidos usados por adapters.
+
+Fixtures:
+
+- PDFs simples y multipagina.
+- Imagenes pequenas PNG/JPG.
+- Fixtures generables/documentadas dentro de `packages/core/test-fixtures`.
+
+Queda fuera o parcialmente cubierto:
+
+- Browser tests reales para `pdf-render`.
+- Canvas real en navegador para flujos PDF a imagenes.
+- Worker real de `pdfjs-dist` bajo automatizacion browser.
+- Coverage formal con `@vitest/coverage-v8`.
+- Typecheck especifico de tests como contrato separado.
+
+La suite actual es suficiente para cerrar V3. No es suficiente por si sola para publicar npm con promesa publica fuerte.
+
+---
+
+## 8. CI y proteccion de rama
+
+CI actual:
+
+- GitHub Actions.
+- Workflow: `.github/workflows/ci.yml`.
+- Job: `Test + Build`.
+- Runner: Ubuntu.
+- Node: 20.
+- Instalacion: `npm ci`.
+- Tests: `npm run test:run`.
+- Build: `npm run build`.
+
+Proteccion de rama:
+
+- Branch protection/ruleset configurado.
+- Check requerido: `Test + Build`.
+- El objetivo es evitar merges a `main` sin tests/build verdes.
+
+Nota: la configuracion exacta del ruleset vive en GitHub, no en archivos del repo. Antes de releases grandes conviene revisarla desde la UI de GitHub.
+
+---
+
+## 9. Decisiones tecnicas importantes
+
+Decisiones cerradas en V3:
+
+- SDK-first para separar logica reusable de UI.
+- Adapters delgados en las herramientas.
+- No React dentro del SDK.
+- No backend.
+- No API publica.
+- No login.
+- No monetizacion.
+- `pdf-render` separado de `pdf`.
+- Worker de `pdfjs-dist` configurado por el consumidor.
+- No npm publico todavia.
+- Browser-first como target inicial.
+- `Comprimir PDF` excluido del SDK.
+
+Estas decisiones deben preservarse hasta que una fase Post-V3 las reevalua con datos reales y un objetivo claro.
+
+---
+
+## 10. Deuda tecnica pendiente
+
+Deuda tecnica conocida:
+
+- Cobertura de `pdf-render` con browser tests reales.
+- Posible coverage con `@vitest/coverage-v8`.
+- Typecheck especifico de tests.
+- README del SDK mas publico y completo.
+- Licencia pendiente de revisar/formalizar para publicacion.
+- Scope `@modulaq` pendiente de reservar o confirmar.
+- npm publish pendiente.
+- Politica de soporte y semver pendiente.
+- Documentacion externa para worker/canvas pendiente de endurecer.
+
+Esta deuda es normal y aceptable para un SDK local privado. Debe resolverse antes de publicacion publica o soporte externo.
+
+---
+
+## 11. Riesgos pendientes
+
+Riesgos abiertos:
+
+- `pdfjs-dist` worker/canvas puede fallar por configuracion, version o entorno.
+- Semver se vuelve una obligacion si se publica en npm.
+- Soporte publico puede consumir tiempo antes de validar demanda.
+- Bundle size puede crecer si se re-exporta mal o se mezcla `pdf-render` con `pdf`.
+- Falta de datos reales de uso para decidir prioridades.
+- OCR y PDFs escaneados pueden generar expectativas si no se documentan bien.
+- `Comprimir PDF` puede ser malinterpretado como compresion real si se comunica mal.
+
+Mitigacion general: mantener local-first, medir antes de construir infraestructura y separar claramente SDK interno, herramientas publicas y futuras APIs.
+
+---
+
+## 12. Condiciones antes de npm publish
+
+No preparar npm publish todavia.
+
+Condiciones minimas:
+
+- Licencia definida y compatible con publicacion.
+- README mas solido para consumidores externos.
+- Tests mas completos, especialmente errores y pdf-render.
+- Coverage formal.
+- Scope `@modulaq` reservado o confirmado.
+- Politica de soporte documentada.
+- Semver y manejo de breaking changes definidos.
+- Mas uso real desde la app.
+- Validacion de bundle y subpath imports.
+- Revision de archivos incluidos en el paquete.
+- Dry-run de publish antes de publicar.
+
+Mientras estas condiciones no se cumplan, `@modulaq/core` debe seguir privado.
+
+---
+
+## 13. Condiciones antes de backend/API/monetizacion
+
+No abrir backend/API/monetizacion como continuacion automatica de V3.
+
+Condiciones necesarias:
+
+- Demanda real observada.
+- Caso imposible o claramente peor en navegador.
+- Costo justificado.
+- Privacidad clara.
+- Modelo sostenible.
+- Politica de datos y retencion.
+- Rate limits y proteccion contra abuso.
+- Separacion entre herramientas locales y flujos server-side.
+- Seguridad revisada antes de procesar archivos fuera del navegador.
+
+Principio: si una herramienta puede funcionar localmente en el navegador, ese debe seguir siendo el default.
+
+---
+
+## 14. Metricas actuales / observaciones
+
+Observaciones actuales:
+
+- Tests locales verdes.
+- Build local verde.
+- CI verde segun estado del proyecto.
+- Branch protection/ruleset configurado.
+- Rendimiento observado del build en auditoria final:
+  - Tests: 18 archivos, 110 tests, aproximadamente 13.53s reportados por Vitest.
+  - Build client: aproximadamente 12.98s.
+  - Build server: aproximadamente 524ms.
+  - SSG: 16 paginas renderizadas.
+  - Sitemap: 14 URLs generadas.
+- Trafico inicial: bajo/medio segun contexto operativo; todavia insuficiente para optimizaciones fuertes.
+- Necesidad principal: mas datos antes de optimizar producto, contenido o infraestructura.
+
+No conviene sobre-optimizar antes de revisar Search Console, Cloudflare Analytics y comportamiento organico real.
+
+---
+
+## 15. Proximo paso recomendado
+
+Siguiente fase recomendada: Post-V3 SEO/Growth organico.
+
+No abrir V3.2 todavia.
+
+Orden recomendado:
+
+1. Dejar correr el sitio.
+2. Analizar Search Console.
+3. Analizar Cloudflare Analytics.
+4. Identificar paginas/herramientas con impresiones, CTR y posicion mejorables.
+5. Mejorar descubrimiento organico sin romper local-first.
+6. Crear contenido educativo y util para PDF, QR y texto.
+7. Recién despues decidir si hace falta nueva fase tecnica.
+
+Post-V3 debe enfocarse en crecimiento organico, claridad publica, documentacion y medicion, no en agregar features por inercia.
+
+---
+
+## 16. Prompt corto para nuevo chat
+
+Usar este prompt para iniciar un nuevo chat:
+
+```text
+Estamos en el repo Modulaq. Lee primero docs/MODULAQ_V3_CONTEXT.md y toma ese documento como contexto oficial de cierre V3. V3.0 y V3.1 ya estan implementadas: @modulaq/core existe como SDK local, las herramientas relevantes consumen el SDK mediante adapters delgados, hay 110 tests verdes, npm run build y GitHub Actions estan verdes, y branch protection/ruleset ya fue configurado. No abras V3.2 todavia, no prepares npm publish, no agregues backend/API/monetizacion, no toques SEO/SSG/herramientas salvo que se pida explicitamente. El siguiente paso recomendado es planificar Post-V3 SEO/Growth organico con privacidad/local-first como principio.
+```
+
+---
+
+## 17. Cierre
+
+V3 queda cerrada como fase tecnica.
+
+La recomendacion final es no seguir agregando alcance tecnico bajo V3. El proyecto debe pasar a una fase Post-V3 separada, orientada a observacion, SEO/Growth organico y mejor documentacion publica, manteniendo privacidad y procesamiento local como principios centrales.