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

/**
 * EngineSemantic — registry de canales perceptivos + dispatch.
 *
 * El engine no conoce DOM, ni hold, ni atributos de estado. Su trabajo es:
 *
 *   1. Asignar un id estable a cada ocurrencia.
 *   2. Ejecutar `channel.prepare(...)` antes de la cascade para que los
 *      canales publiquen su superficie temporal si la necesitan.
 *   3. Resolver la `EffectiveSignature` con las 6 capas de cascade.
 *   4. Despachar a cada canal registrado.
 *   5. Esperar al canal visual y limpiar los handles de preparación.
 *
 * Override layers (ver `resolver.ts`):
 *   1. family base                  — SEMA_MAP.families
 *   2. intent deltas                — SEMA_MAP.intents (any family with intent)
 *   3. morfo per-event              — signal.overrides + signal.channels
 *   4. runtime path overrides       — engineOpts.overrides.runtime
 *                                     (applied to map at construction)
 *   5. cascade rules                — engineOpts.components (per-component
 *                                     packs prepended) + engineOpts.overrides.cascade
 *                                     (app-level rules appended; win on tie)
 */

import type { Channel, ChannelPreparation } from './chans/types';
import type { DomApplier } from '$libs/dom';
import type { Logger } from '$libs/logger';
import { HapticChannel, type HapticChannelOptions } from './chans/haptic';
import { SoundChannel, type SoundChannelDom, type SoundChannelOptions } from './chans/sound';
import { VisualChannel, type VisualChannelOptions } from './chans/visual';
import { SemaDuplicateChannelError } from './errors';
import { applyMapOverrides, resolveSignature, type SemaCascadeRule } from './resolver';
import { SEMA_MAP, type SemaMap, type Sema } from './sema-map';
import type { DeltaValue } from './channels';
import type { SemanticSignal } from './signal';
import type { SignalProjector } from './projection';

export interface EngineSemanticOverrides {
	/**
	 * Path-based mutations of the SEMA_MAP applied at construction. The
	 * canonical map is not mutated; only the overridden object path is cloned.
	 */
	runtime?: Record<string, DeltaValue>;

	/**
	 * App-level cascade rules (CSS-style). Concatenated AFTER all
	 * per-component packs so app rules win on tie (declaration order).
	 */
	cascade?: readonly SemaCascadeRule[];
}

export interface EngineSemanticOptions {
	/** VisualChannel built-in. `false` to disable; object for opts; Channel to replace. */
	visual?: false | VisualChannelOptions | Channel;
	/** SoundChannel built-in. `true`/object/Channel to enable; `false`/undef to skip. */
	sound?: true | false | SoundChannelOptions | Channel;
	/** HapticChannel built-in. `true`/object/Channel to enable; `false`/undef to skip. */
	haptic?: true | false | HapticChannelOptions | Channel;

	/** Optional diagnostics logger. When omitted, channel failures stay silent. */
	logger?: Logger;

	/**
	 * Per-component packs of perceptual defaults. Each pack ships with
	 * the component (`src/uix/sema/components/{name}.ts`) and is
	 * concatenated into the cascade BEFORE `overrides.cascade`. Tree-
	 * shakable: only packs the app imports get included.
	 */
	components?: readonly Sema[];

	/** Override layers 5 (runtime path) + 6b (app cascade). */
	overrides?: EngineSemanticOverrides;

	/**
	 * Projector forwarded to the built-in VisualChannel. The engine stores no
	 * projector itself; channels own their prepare/materialization details.
	 */
	projector?: SignalProjector;

	/**
	 * DOM writer forwarded to the built-in VisualChannel's default projector.
	 * In `active-uix` this is `uix.dom`, so sema projects event attrs through
	 * the same DOM owner as soma.
	 */
	dom?: DomApplier | (DomApplier & SoundChannelDom);
}

interface PersistentSignalEntry {
	readonly preparations: readonly ChannelPreparation[];
	readonly target: HTMLElement | undefined;
}

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

	private readonly map: SemaMap;
	private readonly cascade: readonly SemaCascadeRule[];
	private readonly logger: Logger | undefined;

	/**
	 * Active non-transient signals — projection handles kept alive past the
	 * hold for `untilAction` / `untilFix` / `stateBound`. Cleared via
	 * `clear(id)` or `clearTarget(target)`. Per book §6.1: persistence is
	 * caller-managed; the engine only holds the cleanup handle.
	 */
	private readonly active = new Map<string, PersistentSignalEntry>();

	constructor(opts: EngineSemanticOptions = {}) {
		this.logger = opts.logger;

		// Layer 5 — runtime path overrides baked into the map at construction.
		this.map = applyMapOverrides(SEMA_MAP, opts.overrides?.runtime);

		// Layer 6 — flatten per-component packs (lower precedence) +
		// app-level cascade (higher precedence on tie).
		const packCascade: SemaCascadeRule[] = [];
		const preloadUrls = new Set<string>();
		for (const pack of opts.components ?? []) {
			for (const rule of pack.cascade) {
				packCascade.push(rule as SemaCascadeRule);
			}
			for (const url of pack.preloadSamples ?? []) {
				preloadUrls.add(url);
			}
		}
		this.cascade = [...packCascade, ...(opts.overrides?.cascade ?? [])];

		// Channels.
		if (opts.visual !== false) {
			const visualChannel: Channel = isChannel(opts.visual)
				? opts.visual
				: new VisualChannel({
						...(opts.visual ?? {}),
						dom: opts.dom,
						projector: opts.projector
					});
			this.register(visualChannel);
		}

		if (opts.sound !== undefined && opts.sound !== false) {
			let soundChannel: Channel;
			if (isChannel(opts.sound)) {
				soundChannel = opts.sound;
			} else {
				const soundOptions = opts.sound === true ? {} : opts.sound;
				soundChannel = new SoundChannel({
					...soundOptions,
					dom: soundOptions.dom ?? (isSoundChannelDom(opts.dom) ? opts.dom : undefined),
					logger: opts.logger
				});
			}
			this.register(soundChannel);

			// Pre-decode the WAVs declared by component packs so the first
			// emit doesn't pay the fetch + decode latency.
			if (preloadUrls.size > 0 && soundChannel instanceof SoundChannel) {
				void soundChannel.preloadSamples([...preloadUrls]);
			}
		}

		if (opts.haptic !== undefined && opts.haptic !== false) {
			const hapticChannel: Channel = isChannel(opts.haptic)
				? opts.haptic
				: new HapticChannel(opts.haptic === true ? {} : opts.haptic);
			this.register(hapticChannel);
		}
	}

	register(channel: Channel): void {
		if (this.channels.has(channel.id)) {
			throw new SemaDuplicateChannelError(channel.id);
		}
		this.channels.set(channel.id, channel);
	}

	/**
	 * Despacha una señal a todos los canales registrados.
	 *
	 * Lifecycle:
	 *   1. Generate id and run channel prepare hooks.
	 *      VisualChannel.prepare() projects `data-event-*` on target.
	 *   2. resolveSignature → cascade selectors match against the now-
	 *      projected target via native `target.matches()`.
	 *   3. Fire-and-forget non-visual channels.
	 *   4. Await visual channel hold.
	 *   5. Cleanup prepare handles.
	 *
	 * Sequential strict: the caller's structural commit happens AFTER
	 * cleanup. State change is strictly ordered after the perceptual window.
	 */
	async emit(signal: SemanticSignal): Promise<string> {
		const id = signal.id ?? `sig-${this.nextSignalId++}`;
		const enriched: SemanticSignal = { ...signal, id };

		// Explicit silence (capa 4 morfo override): `signal.channels: []`
		// skips EVERYTHING — no projection, no dispatch, no hold. The morfo
		// declared this event has no perceptual surface. Other paths to an
		// empty `effective.activeChannels` (e.g. signal with no family —
		// degenerate case) still go through dispatch so individual channels
		// can self-skip via their own activeChannels check.
		if (signal.channels !== undefined && signal.channels.length === 0) {
			return id;
		}

		const preparations: ChannelPreparation[] = [];
		for (const channel of this.channels.values()) {
			const handle = channel.prepare?.(enriched);
			if (handle) preparations.push(handle);
		}

		const persistence = signal.persistence ?? 'transient';
		const shouldAutoCleanup = persistence === 'transient';
		let cleanedUp = false;

		try {
			const effective = resolveSignature(enriched, {
				map: this.map,
				cascade: this.cascade
			});

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

			for (const channel of otherChannels) {
				channel.handle(enriched, effective).catch((err) => {
					this.logger?.error('sema', `channel "${channel.id}" failed`, {
						error: err,
						context: { channel: channel.id, signal: enriched.id }
					});
				});
			}

			// Visual owns the hold timing. It runs whenever there are ANY
			// active channels — the empty-channels case was already handled
			// by the early return above. Visual isn't in family activeChannels
			// (those describe real runtime channels like sound / haptic) —
			// it's a meta channel that gates the data-event-* hold for eidos
			// CSS reactions.
			if (visualChannel) {
				await visualChannel.handle(enriched, effective);
			}
		} finally {
			if (shouldAutoCleanup) {
				for (const handle of [...preparations].reverse()) {
					handle.cleanup();
				}
				cleanedUp = true;
			}
		}

		// Persistent signals: keep projection alive past the hold. Caller
		// (typically a soma provider) clears via `clear(id)` or
		// `clearTarget(target)` when the relevant condition is met. If the
		// caller never clears, the projection lingers until dispose() — by
		// design: persistence is caller-managed per book §6.1.
		if (!cleanedUp) {
			this.active.set(id, { preparations, target: signal.target });
		}

		return id;
	}

	/**
	 * Clear an active persistent signal by id. Returns `true` if the signal
	 * was found and cleared, `false` if it didn't exist (already cleared,
	 * was transient, or never emitted).
	 *
	 * Call this from the caller that originally emitted the signal when
	 * the underlying condition is met:
	 *   - `untilAction` — user acknowledged the alert.
	 *   - `untilFix`    — the validation error was corrected.
	 *   - `stateBound`  — the state ended.
	 */
	clear(id: string): boolean {
		const entry = this.active.get(id);
		if (!entry) return false;
		this.active.delete(id);
		for (const handle of [...entry.preparations].reverse()) {
			handle.cleanup();
		}
		return true;
	}

	/**
	 * Clear all active persistent signals whose `target` matches the given
	 * element. Returns the count of signals cleared. Useful when a single
	 * gesture invalidates multiple persistent signals on the same surface
	 * (e.g. a form with three field warnings: one form-valid clears all).
	 */
	clearTarget(target: HTMLElement): number {
		let count = 0;
		for (const [id, entry] of this.active) {
			if (entry.target === target) {
				this.active.delete(id);
				for (const handle of [...entry.preparations].reverse()) {
					handle.cleanup();
				}
				count++;
			}
		}
		return count;
	}

	/**
	 * Whether a persistent signal id is currently active. Read-only helper
	 * for diagnostics and tests; production code should not branch on this.
	 */
	hasActive(id: string): boolean {
		return this.active.has(id);
	}

	getChannel(id: string): Channel | undefined {
		return this.channels.get(id);
	}

	dispose(): void {
		// Clean up any lingering persistent signal projections before tearing
		// down channels, so DOM doesn't keep stale data-event-* attrs.
		for (const entry of this.active.values()) {
			for (const handle of [...entry.preparations].reverse()) {
				handle.cleanup();
			}
		}
		this.active.clear();

		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'
	);
}

function isSoundChannelDom(value: unknown): value is SoundChannelDom {
	return (
		value !== null &&
		typeof value === 'object' &&
		typeof (value as SoundChannelDom).getDocument === 'function' &&
		typeof (value as SoundChannelDom).listen === 'function'
	);
}