Guía del Componente Web <oim-player>

El <oim-player> es un elemento personalizado (Custom Element) ligero e independiente de frameworks que decodifica y reproduce imágenes interactivas .oim directamente en cualquier navegador web. Encapsulado en un Shadow DOM abierto, garantiza cero colisiones CSS con la aplicación anfitriona.

---

1. Instalación Rápida y Uso vía CDN

Puedes cargar <oim-player> desde gestores de paquetes modernos o directamente mediante etiqueta de script CDN:

<!-- Importar bundle independiente mediante CDN -->
<script type="module" src="https://cdn.oim.media/player/v1/oim-player.js"></script>

<!-- O instalar mediante npm/pnpm -->
<!-- pnpm add @oim-media/player-oim -->

Uso en marcado HTML estándar:

<oim-player
  src="https://cdn.oim.media/demo/imagen-muestra.oim.png"
  lang="es"
  fit="contain"
  allow-dynamic-colors="true">
</oim-player>

---

2. Atributos Observados del DOM

<oim-player> observa sus atributos y actualiza el árbol de renderizado dinámicamente:

Atributo	Tipo	Por Defecto	Descripción
src	string (URL o Blob)	""	Ruta de origen del archivo .oim.png o .oim
lang	string	"es"	Código de idioma activo ("es", "en", etc.)
fit	"contain" | "cover"	"contain"	Modo de ajuste al contenedor padre
align	"center" | "top" | "bottom"	"center"	Alineación y posicionamiento vertical
placeholder	string	""	Imagen estática mostrada durante la carga
allow-dynamic-colors	"true" | "false"	"true"	Habilita tokens de color semántico CSS
palette	string	(ninguna)	Paleta con nombre de palettes del .oim que aplicar; sin ella el player sigue prefers-color-scheme si el archivo trae dark y light, si no defaultPalette
allow-zoom	"true" | "false"	"false"	Habilita controles de zoom interactivo
disable-animations	"true" | "false"	"false"	Detiene bucles (respeta movimiento reducido)
auto-rotate-lang	number | "false"	"false"	Intervalo en ms para alternar idiomas

---

3. API Pública y Métodos JavaScript

La instancia del elemento personalizado expone métodos imperativos en el nodo del DOM:

const player = document.querySelector('oim-player');

// Obtener el objeto de metadatos validado extraído del PNG
const metadata = await player.getMetadata();
console.log('ID del documento:', metadata.oim_id);

// Cambiar de idioma programáticamente en tiempo real
player.setLang('en');

// Comprobar el estado de verificación de la firma criptográfica
const security = player.getSecurityStatus(); // "verified" | "unsigned" | "invalid"

// Controlar zoom interactivo (1.0x a 4.0x)
player.setZoom(1.5);

// Destruir observers y limpiar memoria
player.destroy();

---

4. Eventos Personalizados y Gestión de Disparadores

El reproductor emite Eventos Personalizados estándar que ascienden por el árbol DOM:

Nombre del Evento	Detalle (detail)	Descripción
oim:loaded	{ type: string, metadata: object }	Emitido al completar la extracción y validación
oim:langchange	{ lang: string }	Emitido al cambiar el idioma activo
oim:action	{ slot, name, trigger, targets }	Emitido al interactuar con un slot con acción
oim:incomplete	{ missing_capabilities: string[] }	Emitido si el archivo exige funciones no soportadas
error	{ message: string, code: string }	Emitido ante fallos de red o descompresión

Intercepción de Acciones con preventDefault()

Al hacer clic en un slot con acción declarada, la aplicación anfitriona puede interceptar el evento:

player.addEventListener('oim:action', (event) => {
  const { slot, name } = event.detail;
  if (name === 'buy_button') {
    event.preventDefault(); // Detiene la navegación por defecto
    abrirModalDeCompraPersonalizado(slot.id);
  }
});

---

5. Aislamiento con Shadow DOM y Seguridad

La estructura interna del reproductor está totalmente protegida:

• Shadow DOM: Opera en mode: 'open' con inyección de estilos internos que evitan fugas hacia el CSS global.
• Saneado de Colores Dinámicos: Los valores de color pasan por la función pura isSafeCssColor antes de asignarse a variables CSS (var(--oim-color-*)).
• Verificación Criptográfica: Valida la firma ECDSA P-256 frente a claves públicas incrustadas en el player al compilarlo, así que mostrar un archivo no contacta con ningún servidor ni revela quién lo está viendo. Solo un archivo firmado con una clave que esta versión no conoce hace que el player la pida, por defecto a https://api.oim.media/v1/media/keys; una copia autoalojada puede apuntar a otro sitio con window.OIM_PLAYER_CONFIG = { keysUrl: "..." } antes de cargar el player.

---

6. Carga, Zoom y Estilo desde la Página Anfitriona

El player viene limpio: hace solo lo que el formato necesita y no trae decoración propia. Cómo se ve alrededor de la obra es cosa de la página que lo inserta, mediante propiedades personalizadas de CSS. Se heredan dentro del Shadow DOM, así que se ponen en <oim-player> o en cualquier antecesor.

Primera carga: una sola aparición, sin construcción a la vista

La obra queda tras un velo (desenfocada y transparente) mientras se construye. Cada capa se coloca debajo a su tamaño y opacidad finales, y el velo se levanta cuando las fuentes, las imágenes incrustadas de las capas y las animaciones Lottie están listas, y dos fotogramas después, para que la maquetación y la escala ya estén aplicadas. El visitante nunca ve las formas aparecer una a una ni los textos crecer hasta su tamaño. La espera tiene un tope de 1,2 s, para que un recurso roto nunca deje la obra oculta.

Un redibujado posterior (por ejemplo, un cambio de idioma) nunca vuelve a bajar el velo: el cambio de idioma usa su propio desenfoque breve, o un fundido simple si el visitante pidió menos movimiento.

Propiedades personalizadas de CSS

Propiedad	Por defecto	Efecto
--oim-reveal-blur	14px	Desenfoque del velo en la primera carga. 0px para un fundido simple.
--oim-reveal-duration	0.32s	Cuánto tarda en levantarse el velo.
--oim-color-<rol>	el color del autor	Recolorea un rol semántico (primary, on-primary, secondary, on-secondary, surface, on-surface, outline, accent). Ver Colores dinámicos.

oim-player {
  --oim-reveal-blur: 6px;
  --oim-reveal-duration: 0.2s;
  --oim-color-primary: #2563eb;
}

Un rol que no definas cae al color que el autor guardó en cada capa. Usa allow-dynamic-colors="false" para eximir una obra concreta de tu paleta.

El atributo palette elige una de las paletas con nombre que trae la obra (por ejemplo palette="light"). Cambiarlo actualiza el player sin recargar. Tus variables --oim-color-* siguen ganando a la paleta.

Zoom

Con allow-zoom="true", la rueda y el trackpad hacen zoom en proporción a lo que se mueven (un clic de rueda es alrededor de un 5 %), entre 1x y 4x. El pellizco (ctrl + rueda) responde más rápido que el desplazamiento. Los pequeños vaivenes al final de un gesto del trackpad apenas mueven el zoom, así que la obra no tiembla.