# Barra pública y temas compartidos

> Importar la navegación ZAFIROX y compartir una preferencia visual entre sus sitios públicos.

## Integración

La versión recomendada es **2.1.3**. Corrige la navegación de los accesos
cuando el navegador usa el panel sin Popover. Las versiones publicadas
2.1.0, 2.1.1 y 2.1.2 se conservan inmutables.

La biblioteca canónica es `C:\Users\ASUS\Documents\ZafiroxShared`. Sus paquetes
`@zafirox/shared-core`, `@zafirox/shared-angular` y `@zafirox/shared-browser`
contienen contratos, el componente original y su cargador. sdkSite distribuye
los artefactos generados de la versión CDN 2.1.3.

```js
import { mountZafiroxTopbar } from '@zafirox/shared-browser';
const topbar = await mountZafiroxTopbar(document.querySelector('#navigation'), {
  brand: false,
  mainOrigin: 'https://joyeriazafirox.com',
  slots: {
    left: { route: '/', label: 'Volver a ZAFIROX', icon: 'arrow_back', policy: 'public-home' },
    search: { kind: 'public-catalog' },
  },
});
// Al desmontar la vista:
// topbar.destroy();
```

El mismo export se distribuye mediante la ruta versionada
`/cdn/2.1.3/zafirox-topbar.js`. `brand: false` omite la marca cuando la tarjeta
ya muestra el logo. `setInputs` actualiza `items`, `menuOpen`, `contextLabel`,
`accessState` y `slots`. El contrato expone eventos de apertura, cierre,
activación, reintento, navegación y tema. La búsqueda conserva sugerencias,
imagen, categoría, estados y reintento; carga el índice al recibir foco y busca
localmente. Los resultados completos enlazan a `/search?q=...`.

## Una implementación y adaptadores de entorno

El módulo `zafirox.desktop-topbar` monta la misma clase `DesktopTopbarComponent`,
plantilla y CSS del paquete Angular neutral. `provideZafiroxModules()` registra
el adaptador nativo de Angular, que reutiliza el inyector, router y políticas
reales del consumidor. Ese adaptador tiene prioridad sobre el montaje genérico.
Los puertos de aplicación conservan la autoridad de identidad y permisos.

El SDK consulta el registro de capacidades
`Symbol.for('zafirox.modules.adapters.v1')`. Otros frameworks pueden registrar
un adaptador tipado con prioridad; sin adaptador, el cargador utiliza el bundle
AOT del mismo componente. Un documento Angular sin provider recibe una
indicación para instalarlo. Se identifica el entorno del navegador; el lenguaje
del servidor que entregó el HTML no determina el montaje.

`components-provenance.json` registra las fuentes y la entrada compilada que
comparten ambos montajes. Su SHA-256 verificado es
`7c6a68c543132ebec27844f91ed7897ea40580238c568c03ff9ea768c97248cc`. La herramienta
`tools/verify-angular-consumer.mjs --consumer-root <rutaAngular>` comprueba la
identidad del paquete instalado, el tarball, la entrada genérica y las dependencias.

## Preferencia visual

El contrato `zafirox.presentation.theme.v1` conserva versión 1, preferencia
`light`, `dark`, `system` o `classic` y fecha `savedAt`. Gana el registro
válido más reciente; la sincronización conserva su fecha. La cookie segura
comparte únicamente esta preferencia entre los dominios autorizados.
Los servicios y tokens oficiales gobiernan el componente y el host; el evento
`zafirox:themechange` permite sincronizar la tarjeta y sus variantes de marca.

## Distribución y estilos

`tools/build-distribution.mjs` en ZafiroxShared genera los paquetes propios, el
CDN compatible y la copia de bienvenida. CSS y tokens globales se sirven desde
`/assets/zafirox-topbar-2.1.3.css`. La fuente original y su licencia están en
los paquetes y en el CDN versionado; bienvenida las carga localmente.
`stylesUrl: false` permite que el consumidor incluya esos estilos previamente.
El consumidor configura los orígenes de scripts, estilos y fuentes admitidos.
La distribución mantiene los canales y versiones ya publicados.

## Atlas público en un host del mismo origen

El montaje genérico admite `catalogAtlasUrl: '/api/catalog/atlas/'` cuando
el consumidor sirve un transporte público del atlas desde su propio origen.
Se exige HTTPS, mismo origen y ausencia de credenciales, query y fragmento;
HTTP sólo se admite en localhost/127.0.0.1/[::1] para desarrollo. Esta opción
sólo cambia la descarga del atlas. Productos, imágenes y resultados de búsqueda
conservan sus URLs oficiales de tienda. Angular nativo configura el mismo
puerto tipado `PUBLIC_STORE_CONFIG` mediante su propio inyector.

Bienvenida ofrece un endpoint PHP fijo que consulta exclusivamente el atlas
público de tienda sin reenviar cookies, autorización u Origin. No es un proxy
de URL arbitraria. El buscador compartido conserva el contrato v1, validación,
single-flight, sugerencias y reintento originales. El adaptador cambia sólo
el transporte: la clase, plantilla y CSS del componente AOT son los mismos.

Sin una preferencia explícita válida, el tema inicial es claro incluso si el
dispositivo usa oscuro. Las elecciones dark, system y classic conservan su
comportamiento y la fecha guardada. La entrada AOT compartida del componente
conserva SHA-256
`7c6a68c543132ebec27844f91ed7897ea40580238c568c03ff9ea768c97248cc`.

La ruta versionada es `/cdn/2.1.3/zafirox-topbar.js`; los canales v1, v2 y
latest conservan sus versiones previas. La versión explícita identifica los
artefactos de esta integración sin promover otros canales.

Bienvenida consume su grafo ESM desde un directorio identificado por versión
y hash del runtime, por ejemplo `shared/zafirox-topbar-2.1.3-<hash>/`.
El HTML revalida el documento y cambia el identificador del entry al actualizar;
no se requiere borrar el caché del navegador para recibir una release nueva.