svelte-kit-vice/src/uix/sema/engine.ts

/**
 * EngineSemantic — registry de canales perceptivos + dispatch.
 *
 * El engine no conoce DOM, ni atributos, ni hold. Su trabajo es:
 * - mantener un registro de canales que implementan `Channel`
 * - generar el `id` de cada ocurrencia
 * - despachar cada signal a todos los canales registrados
 * - bloquear al caller solo el tiempo que el canal visual necesite
 *   (los demás canales son fire-and-forget)
 *
 * El comportamiento que antes ejecutaba `emit()` directamente (escribir
 * `data-event*` al DOM, esperar hold, retirar) vive ahora en `VisualChannel`
 * y el engine lo invoca como uno más entre canales registrados.
 */

import type { Channel } from './chans/types'
import { SoundChannel, type SoundChannelOptions } from './chans/sound'
import { VisualChannel, type VisualChannelOptions } from './chans/visual'
import { resolveSignature } from './resolver'
import type { SemanticSignal } from './signal'

export interface EngineSemanticOptions {
	/**
	 * Configuración del canal visual built-in.
	 *
	 * - omitido o `undefined` → VisualChannel built-in con defaults
	 * - `false` → no se inicializa el canal visual (caso edge: app
	 *   audio-only, tests sin DOM, server-side rendering puro)
	 * - objeto con opciones → VisualChannel built-in con esas opciones
	 * - instancia de Channel → reemplaza al VisualChannel built-in
	 *   (caso muy raro)
	 */
	visual?: false | VisualChannelOptions | Channel

	/**
	 * Configuración del canal de sonido built-in.
	 *
	 * - omitido, `undefined` o `false` → no se registra (default)
	 * - `true` → SoundChannel built-in con defaults
	 * - objeto con opciones → SoundChannel built-in con esas opciones
	 * - instancia de Channel → canal a medida bajo el id `'sound'`
	 *
	 * Sound es opt-in porque tiene side effects perceptivos para el
	 * usuario (audio audible). El integrador decide cuándo activarlo.
	 */
	sound?: true | false | SoundChannelOptions | Channel
}

export class EngineSemantic {
	private readonly channels = new Map<string, Channel>()
	private nextSignalId = 0

	constructor(opts: EngineSemanticOptions = {}) {
		// VisualChannel built-in automático salvo desactivación explícita.
		if (opts.visual !== false) {
			const visualChannel: Channel = isChannel(opts.visual)
				? opts.visual
				: new VisualChannel(opts.visual ?? {})
			this.register(visualChannel)
		}

		// SoundChannel opt-in: solo si el integrador lo pide explícitamente.
		if (opts.sound !== undefined && opts.sound !== false) {
			const soundChannel: Channel = isChannel(opts.sound)
				? opts.sound
				: new SoundChannel(opts.sound === true ? {} : opts.sound)
			this.register(soundChannel)
		}
	}

	/**
	 * Registra un canal. Los canales no built-in (sound, vibra, futuros)
	 * se registran explícitamente desde el bootstrap de la app.
	 *
	 * Lanza si ya hay un canal con el mismo `id`.
	 */
	register(channel: Channel): void {
		if (this.channels.has(channel.id)) {
			throw new Error(
				`[semantic] channel with id "${channel.id}" already registered`
			)
		}
		this.channels.set(channel.id, channel)
	}

	/**
	 * Despacha una señal a todos los canales registrados.
	 *
	 * Genera el `id` de la ocurrencia si la señal no lo trae — la identidad
	 * de la ocurrencia debe ser consistente entre canales (un futuro tooling
	 * que cruce eventos del DOM con eventos del SoundEngine espera ids
	 * coincidentes; generar en cada canal por separado rompería esto).
	 *
	 * Devuelve una Promise que resuelve cuando el canal visual ha completado
	 * su materialización (semántica secuencial estricta: la Promise resuelve
	 * tras escribir + hold + retirar). Los demás canales son fire-and-forget
	 * y no afectan al timing — solo el visual comparte plano DOM con el
	 * commit estructural posterior.
	 *
	 * Si el canal visual no está registrado, la Promise resuelve inmediatamente.
	 *
	 * Sema es ornamental: errores en canales no-visuales se loguean pero no
	 * propagan, así un fallo en audio context o vibration API no aborta la
	 * operación del provider.
	 */
	async emit(signal: SemanticSignal): Promise<void> {
		const enriched: SemanticSignal = {
			...signal,
			id: signal.id ?? `sig-${this.nextSignalId++}`
		}

		// Resolve once per emit. Each channel reads its slice from the
		// effective signature (or ignores it if the channel doesn't use
		// signatures).
		const effective = resolveSignature(enriched)

		const visualChannel = this.channels.get('visual')
		const otherChannels: Channel[] = []
		for (const channel of this.channels.values()) {
			if (channel.id !== 'visual') otherChannels.push(channel)
		}

		// Fire-and-forget para canales no-visuales.
		for (const channel of otherChannels) {
			channel.handle(enriched, effective).catch((err) => {
				console.error(`[semantic] channel "${channel.id}" failed:`, err)
			})
		}

		// El canal visual sí afecta al timing del caller.
		if (visualChannel) {
			await visualChannel.handle(enriched, effective)
		}
	}

	/**
	 * Devuelve un canal registrado por id, o `undefined`.
	 * Para introspección y testing.
	 */
	getChannel(id: string): Channel | undefined {
		return this.channels.get(id)
	}

	/**
	 * Libera recursos de todos los canales y limpia el registry.
	 * Llamar al desmontar la aplicación si los canales tienen estado externo
	 * (un `AudioContext`, listeners, timers).
	 */
	dispose(): void {
		for (const channel of this.channels.values()) {
			channel.dispose?.()
		}
		this.channels.clear()
	}
}

function isChannel(value: unknown): value is Channel {
	return (
		value !== null &&
		typeof value === 'object' &&
		typeof (value as Channel).id === 'string' &&
		typeof (value as Channel).handle === 'function'
	)
}