Widget · Visión general

El widget de Neuroon es un componente embebible que añade búsqueda semántica con IA a cualquier tienda online. Se integra con un único <script> y se aísla del tema del host mediante Shadow DOM en modo open, evitando colisiones de CSS y JavaScript con tu plantilla.

Está pensado para integraciones server-rendered (WordPress, Magento, .NET, plataformas custom). Cualquier página HTML que pueda imprimir un <script> y un <div> puede embeberlo.

Versión actual

0.9.10 — confirmado en widget/package.json. Distribuido vía CDN versionado: https://cdn.neuroon.ai/widget@0.9.10/widget.js.

Qué resuelve

Capacidad	Detalle
Búsqueda semántica	El usuario escribe en lenguaje natural, no por palabras clave. El backend re-rankea con un agente conversacional que consulta el catálogo del shop.
Búsqueda por voz	Web Speech API + endpoint POST /api/widget/search/audio. Fallback graceful si el navegador no soporta voz.
Búsqueda por imagen	Subida de imagen o captura de cámara. Endpoint POST /api/widget/search/visual.
Asistente IA en línea	Respuesta conversacional + guided filters (single-choice, multi-choice) generados por el LLM.
Comparador	Hasta 4 productos con pros/cons, winner y match score. Endpoint GET /api/widget/compare.
Cart-aware	Si el host configura cart, el widget envía un snapshot del carrito con cada POST /api/widget/search para personalizar resultados (cross-sell, recordar destinos de envío, etc.).
Cross-sell	Recomendaciones complementarias sobre el carrito actual (POST /api/widget/cart/cross-sell).
Buyers guide	Guías de compra contextuales generadas por IA cuando la consulta requiere educación previa.
Kit builder	Construcción de bundles con productos relacionados (ahorros calculados por el backend).
Follow-up	Seguimiento conversacional dentro del mismo conversationId.

Stack

Preact 10.19   ─┐
TypeScript      │
Tailwind v4     ├──►  Bundle ~262 KB (gzip ~65 KB)
Vite 5          │
Framer Motion  ─┘

• Preact en lugar de React para reducir el peso del bundle (~3 KB vs ~45 KB).
• Shadow DOM en modo open — el host puede inspeccionar el árbol pero los estilos del tema no entran. Implementado en widget/src/index-preact.tsx (createShadowDOM).
• CSS inline en el bundle vía import widgetStyles from './tailwind.css?inline' — sin red adicional para los estilos.

Cómo funciona

1. El loader del CDN registra window.NeuroonWidget y, si encuentra un <script> con data-token, llama automáticamente a init() (auto-init en widget/src/index-preact.tsx).
2. createShadowDOM() hace container.attachShadow({ mode: 'open' }), inyecta el CSS inline y crea dos sub-contenedores: .neuroon-widget (árbol Preact) y #neuroon-portal-root (modales y overlays).
3. renderWidget() resuelve el tema (auto/light/dark), aplica StyleOverrides, registra el listener de prefers-color-scheme y monta el árbol Preact dentro del shadow root.
4. Cada petición al backend lleva la cabecera X-Widget-Token (validada en WidgetTokenAuthenticationFilter.java).

Multi-instancia

El widget soporta varias instancias en la misma página (un init() por contenedor). Internamente se mantiene un Map<containerId, ShadowDOMState> para gestionar tema, eventos globales y cleanup por instancia:

window.NeuroonWidget.getInstanceIds()           // ['neuroon-widget-1', 'neuroon-widget-2']
window.NeuroonWidget.destroy('#header-search')  // destruye sólo esa instancia
window.NeuroonWidget.destroy()                  // destruye todas

Próximas lecturas

• Instalación — script tag, SRI, política CSP recomendada.
• Configuración — todas las opciones (data-attrs y NeuroonWidgetConfig).
• Theming — variables --nrn-* y StyleOverrides.
• Eventos del widget — qué emite y qué escucha del host.
• Integración de carrito — cómo el host alimenta el snapshot.