🚀 WebVirt Engine + Nexus: La dupla perfecta para SPAs en Android que sí respeta tu arquitectura

Sirve tu SPA desde assets como un servidor web profesional + puente nativo JavaScript sin fricción. La arquitectura que Capacitor no puede ofrecerte.

🤔 El problema que todos enfrentamos

Tienes una SPA hermosa en React, Vue o Svelte. Corre perfecto en localhost:3000. Ahora necesitas llevarla a Android.

Tus opciones tradicionales:

Solución Resultado
Capacitor / Cordova +30MB de runtime, configuración compleja, WebView propio
file:// protocol CORS roto, rutas SPA no funcionan, APIs bloqueadas
WebView + servidor embebido Overkill, hilos, puertos, problemas de red
Script casero de 50 líneas Funciona... hasta que agregas video, PDF, o edge cases

Lo que realmente quieres: Que tu SPA crea que está en https://app.local, pero todo venga de assets/. Sin servidor. Sin permisos. Sin overhead.

✨ La solución: WebVirt Engine + Nexus

Dos librerías diseñadas para coexistir sin conocerse. Como hermanos que comparten cuarto sin pelearse.

┌─────────────────────────────────────────────────────┐
│                    WebView                          │
│                                                     │
│  ┌───────────────────────────────────────────────┐ │
│  │         WebVirt Engine (dueño del cliente)    │ │
│  │  shouldInterceptRequest() → assets/           │ │
│  │  "app.local/index.html" → index.html real     │ │
│  │  CSP, ETags, Range Requests, Caché LRU       │ │
│  └───────────────────────────────────────────────┘ │
│                    ▲                                │
│                    │ Decora (no sobrescribe)         │
│  ┌───────────────────────────────────────────────┐ │
│  │         Nexus WebViewLifecycleObserver        │ │
│  │  Observa onPageFinished, onPageStarted        │ │
│  │  Delega todo lo demás a WebVirt               │ │
│  └───────────────────────────────────────────────┘ │
│                                                     │
│  ┌───────────────────────────────────────────────┐ │
│  │         Nexus JSInterface (canal paralelo)    │ │
│  │  window.__nexus.call("export", data)          │ │
│  │  NO pasa por shouldInterceptRequest           │ │
│  └───────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────┘

🎯 5 líneas y tu SPA está viva

// 1. WebVirt: Sirve tu SPA desde assets
WebVirt.with(this)
    .host("app.local")
    .bind(webView);

// 2. Nexus: Puente nativo
Nexus.installOn(webView)
    .registerHandler("export", new ExportAdapter())
    .registerHandler("import", new ImportAdapter())
    .initialize()
    .withFilePicker(this);

// 3. Nexus observa sin romper
nexus.attachToWebViewLifecycle();

// 4. Tu SPA carga como si estuviera en un servidor real
webView.loadUrl("https://app.local/");

Eso es todo. Tu React app funcionando, rutas SPA intactas, APIs nativas disponibles. Sin configuración extraña.

🏗️ Arquitectura: El secreto está en el desacoplamiento

A diferencia de frameworks monolíticos, WebVirt Engine y Nexus usan capas que no compiten:

Capa 1: Red Virtual → WebVirt Engine

WebViewClient.shouldInterceptRequest()
  ├── ¿Es app.local? → Sirve desde assets/
  ├── ¿Ruta SPA? → index.html (fallback)
  ├── ¿API virtual? → RouteHandler (respuesta JSON falsa)
  └── ¿Externo permitido? → Deja pasar

Patrones: Builder, Chain of Responsibility, Strategy (PathHandlers)

Capa 2: Puente Nativo → Nexus

WebView.addJavascriptInterface(nexusInterface, "__nexus")
  └── window.__nexus.call("export", params, callbackId)
        ├── Thread pool para handlers
        ├── Timeout automático
        ├── Serialización JSON
        └── Callback al WebView vía evaluateJavascript()

Patrones: Observer, Command, Mediator, Callback

Capa 3: Ciclo de Vida → Nexus (Decorator)

WebViewLifecycleObserver envuelve al cliente de WebVirt
  ├── shouldInterceptRequest() → delega a WebVirt ✅
  ├── onPageFinished() → WebVirt + notifica a Nexus ✅
  └── Todos los demás métodos → delega a WebVirt ✅

Patrón: Decorator — El más elegante del sistema

¿Por qué funciona tan bien?

WebVirt NO sabe Nexus NO sabe
Que Nexus existe Que WebVirt existe
Que hay un bridge JS Cómo se sirven los assets
Qué handlers hay registrados Qué host virtual se usa

Esto es desacoplamiento real. No es marketing.

🔒 Seguridad de grado producción

WebVirt Engine hereda el enfoque de WebVirt original pero lo lleva a nivel empresarial:

Defensa en profundidad

Capa 1: Path Traversal Protection
  ├── Normalización de rutas
  ├── Bloqueo de ".."
  └── Validación de esquema

Capa 2: Content Security Policy
  ├── CSP configurable por el desarrollador
  ├── Default restrictivo
  └── Headers de seguridad automáticos

Capa 3: Offline Mode
  ├── Bloquea TODAS las peticiones externas
  └── Whitelist de dominios explícita

Capa 4: Extensiones permitidas
  └── Solo sirve archivos con extensiones seguras

Headers de seguridad automáticos

Cada respuesta de WebVirt Engine incluye:

Content-Security-Policy: default-src 'self'; script-src 'self'...
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block
Access-Control-Allow-Origin: *

Y tú puedes personalizar el CSP:

WebVirt.with(this)
    .host("app.local")
    .cspPolicy("default-src 'self'; script-src 'self' https://api.externa.com")
    .bind(webView);

🎬 Streaming de video sin cargar en RAM

¿Tu SPA tiene videos? WebVirt Engine soporta Range Requests reales:

Cliente: GET /video.mp4
         Range: bytes=1048576-2097151

Servidor: 206 Partial Content
          Content-Range: bytes 1048576-2097151/52428800
          [solo envía los bytes solicitados]

El archivo nunca se carga completo en memoria. Streaming real desde InputStream.

⚡ Rendimiento: Caché que aprende

Primera carga:
  index.html → leído → ETag generado → cacheado (LRU)

Segunda carga:
  index.html → ETag coincide → 304 Not Modified → 0 bytes transferidos

· LruCache con control de memoria real
· ETags SHA-1 para validación
· If-Modified-Since para archivos
· Se limpia automáticamente con onTrimMemory()

🧩 ¿Juntos o separados?

Solo WebVirt Engine

Perfecto para SPAs que no necesitan APIs nativas:

WebVirt.with(this)
    .host("app.local")
    .route("/api/config", req -> json("{...}"))  // API falsa
    .bind(webView);

Solo Nexus

Perfecto para WebViews tradicionales que necesitan bridge nativo:

Nexus.installOn(webView)
    .registerHandler("camera", new CameraHandler())
    .initialize();

WebVirt Engine + Nexus

La combinación completa. SPA servida profesionalmente + APIs nativas:

WebVirt.with(this).host("app.local").bind(webView);
Nexus.installOn(webView)
    .registerHandler("export", exportAdapter)
    .registerHandler("import", importAdapter)
    .registerHandler("camera", cameraAdapter)
    .initialize()
    .withFilePicker(this);
nexus.attachToWebViewLifecycle();

📊 Comparación honesta

Característica WebVirt Engine Capacitor Cordova WebView puro
Tamaño runtime 0KB (solo tu código) ~25MB ~15MB 0KB
Caché inteligente ✅ LRU + ETags ❌ ❌ ❌
Range Requests ✅ Streaming real ✅ ✅ ❌
CSP personalizable ✅ ❌ ✅ ❌
Rutas SPA ✅ Automático ✅ ✅ ❌
Offline mode ✅ Built-in ✅ ✅ ✅
Hot reload ❌ ✅ ✅ ❌
JS Bridge nativo Con Nexus ✅ ✅ Manual
Sin permisos ✅ ✅ ✅ ✅
Curva aprendizaje 5 minutos 2 horas 3 horas Variable
Desacoplamiento ✅ Total ❌ ❌ N/A

🚀 Producción probada

No es teoría. WebVirt (versión lite) + Nexus ya funcionan en producción en una app financiera real:

· ⚛️ React + TypeScript + TailwindCSS
· 📦 5MB de assets servidos sin conexión
· 📤 Export JSON nativo
· 📥 Import JSON con FilePicker (sin permisos)
· 📄 Export PDF nativo
· 🔒 CSP restrictivo
· ⚡ Carga instantánea

📦 Próximamente

WebVirt Engine v3.1.1

· Repositorio: github.com/fouzstack/webvirt-engine
· JitPack: implementation 'com.github.fouzstack:webvirt-engine:3.1.1'
· Documentación completa
· Módulo Kotlin -ktx

Nexus v2.0.0

· Repositorio: github.com/fouzstack/nexus
· JitPack: implementation 'com.github.fouzstack:nexus:2.0.0'
· Documentación completa
· Templates de proyecto

🎯 ¿Quién debería usar esto?

✅ Desarrolladores React/Vue/Svelte que necesitan Android sin Capacitor

✅ Equipos pequeños que quieren control total sin dependencias pesadas

✅ Apps offline-first que necesitan rendimiento máximo

✅ Cualquiera que valore arquitecturas limpias y desacoplamiento real

❌ Si necesitas hot reload en desarrollo (por ahora)

❌ Si tu empresa ya está comprometida con Capacitor/Cordova

💬 Lo que dicen los patrones de diseño

"Programa contra interfaces, no implementaciones" — GoF

WebVirt Engine y Nexus no se conocen. Se respetan. Colaboran sin acoplarse.

"Separa lo que cambia de lo que permanece" — Clean Architecture

WebVirt cambia (assets, CSP, rutas). Nexus cambia (handlers, timeouts).
Ninguno rompe al otro.

"Una clase debería tener solo una razón para cambiar" — SRP

WebVirt: servir assets. Nexus: bridge nativo. Una responsabilidad cada uno.

🔗 Enlaces

· WebVirt (lite): github.com/fouzstack/fouzstack-webvirt
· WebVirt Engine: Próximamente en github.com/fouzstack/webvirt-engine
· Nexus: Próximamente en github.com/fouzstack/nexus

🙏 Agradecimientos

A la comunidad de Android que sigue buscando formas más limpias de integrar WebViews.
A los patrones de diseño del GoF que 30 años después siguen vigentes.
Y a ti, por leer hasta aquí.

¿Preguntas? ¿Ideas? ¿Quieres contribuir? Los repositorios estarán abiertos para issues y PRs.

Comenta abajo: ¿Qué handler nativo te gustaría ver implementado con Nexus?