openvoiceui 1.0.0

package/src/face/BaseFace.js

@@ -0,0 +1,259 @@
+/**
+ * BaseFace — abstract base class for face/avatar modules (ADR-009: simple manager pattern)
+ *
+ * All face implementations extend this class and override the lifecycle methods.
+ * The face manager loads faces from manifest.json and swaps them at runtime.
+ *
+ * Usage:
+ *   import { BaseFace } from './BaseFace.js';
+ *
+ *   class MyFace extends BaseFace {
+ *     init(container) { ... }
+ *     setMood(mood) { ... }
+ *     destroy() { ... }
+ *   }
+ *
+ * Events emitted on eventBus:
+ *   'face:mood'      { mood: string }         — mood changed
+ *   'face:ready'     { id: string }            — face initialized
+ *   'face:changed'   { from: string, to: string } — face swapped
+ */
+
+import { eventBus } from '../core/EventBus.js';
+
+export const VALID_MOODS = ['neutral', 'happy', 'sad', 'angry', 'thinking', 'surprised', 'listening'];
+
+/**
+ * @abstract
+ */
+export class BaseFace {
+    /**
+     * @param {string} id  unique face ID from manifest (e.g. 'eyes', 'orb')
+     */
+    constructor(id) {
+        if (new.target === BaseFace) {
+            throw new Error('BaseFace is abstract — extend it, do not instantiate it directly');
+        }
+        /** @type {string} */
+        this.id = id;
+        /** @type {string} */
+        this.currentMood = 'neutral';
+        /** @type {HTMLElement|null} */
+        this.container = null;
+        /** @protected */
+        this._initialized = false;
+    }
+
+    /**
+     * Initialize the face inside the given container element.
+     * Called once when the face is first activated.
+     * @param {HTMLElement} container  the .face-box element
+     * @abstract
+     */
+    init(container) {
+        throw new Error(`${this.constructor.name}.init() not implemented`);
+    }
+
+    /**
+     * Set the face's emotional state.
+     * @param {string} mood  one of VALID_MOODS
+     * @abstract
+     */
+    setMood(mood) {
+        throw new Error(`${this.constructor.name}.setMood() not implemented`);
+    }
+
+    /**
+     * Trigger a blink animation (optional — no-op by default).
+     */
+    blink() {
+        // optional override
+    }
+
+    /**
+     * React to audio amplitude (0-1). Used for speaking animations.
+     * @param {number} amplitude  0.0 (silent) to 1.0 (loud)
+     */
+    setAmplitude(amplitude) {
+        // optional override
+    }
+
+    /**
+     * Called when the face is deactivated / replaced by another face.
+     * Clean up timers, animation frames, DOM mutations.
+     * @abstract
+     */
+    destroy() {
+        throw new Error(`${this.constructor.name}.destroy() not implemented`);
+    }
+
+    // ── protected helpers ─────────────────────────────────────────────────────
+
+    /**
+     * Normalize and validate a mood string.
+     * @param {string} mood
+     * @returns {string}  valid mood, falls back to 'neutral'
+     * @protected
+     */
+    _normalizeMood(mood) {
+        return VALID_MOODS.includes(mood) ? mood : 'neutral';
+    }
+
+    /**
+     * Emit a face:mood event on the shared eventBus.
+     * @param {string} mood
+     * @protected
+     */
+    _emitMood(mood) {
+        this.currentMood = mood;
+        eventBus.emit('face:mood', { mood, faceId: this.id });
+    }
+
+    /**
+     * Emit face:ready after init completes.
+     * @protected
+     */
+    _emitReady() {
+        this._initialized = true;
+        eventBus.emit('face:ready', { id: this.id });
+    }
+}
+
+/**
+ * FaceManager — loads the active face from manifest, handles swapping.
+ *
+ * Usage:
+ *   import { faceManager } from './BaseFace.js';
+ *
+ *   await faceManager.load('eyes');   // activate EyeFace
+ *   faceManager.setMood('happy');
+ *   faceManager.blink();
+ *   await faceManager.load('orb');    // swap to OrbFace
+ */
+class FaceManager {
+    constructor() {
+        /** @type {BaseFace|null} */
+        this._active = null;
+        /** @type {HTMLElement|null} */
+        this._container = null;
+        /** @type {Record<string, () => Promise<BaseFace>>} */
+        this._registry = {};
+        /** @type {Object|null} loaded manifest */
+        this._manifest = null;
+    }
+
+    /**
+     * Point the manager at a container element and load the manifest.
+     * @param {HTMLElement} container  .face-box DOM element
+     * @param {string} [manifestUrl]   URL to manifest.json
+     */
+    async init(container, manifestUrl = '/src/face/manifest.json') {
+        this._container = container;
+        try {
+            const res = await fetch(manifestUrl);
+            if (res.ok) {
+                this._manifest = await res.json();
+            }
+        } catch (err) {
+            console.warn('[FaceManager] Could not load manifest:', err.message);
+        }
+    }
+
+    /**
+     * Register a face factory.
+     * @param {string} id
+     * @param {() => Promise<BaseFace>} factory  async factory that returns a face instance
+     */
+    register(id, factory) {
+        this._registry[id] = factory;
+    }
+
+    /**
+     * Activate a face by ID.  Destroys the current face first.
+     * @param {string} id
+     */
+    async load(id) {
+        if (!this._registry[id]) {
+            console.warn(`[FaceManager] Unknown face id: ${id}`);
+            return;
+        }
+
+        const previousId = this._active?.id ?? null;
+
+        // Destroy current face
+        if (this._active) {
+            this._active.destroy();
+            this._active = null;
+        }
+
+        // Create & init new face
+        const face = await this._registry[id]();
+        if (this._container) {
+            face.init(this._container);
+        }
+        this._active = face;
+
+        // Persist selection to server profile
+        const profileId = window.providerManager?._activeProfileId || 'default';
+        fetch('/api/profiles/' + profileId, {
+            method: 'PUT',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ ui: { face_mode: id } })
+        }).catch(e => console.warn('Failed to save face to profile:', e));
+        if (window._serverProfile) {
+            if (!window._serverProfile.ui) window._serverProfile.ui = {};
+            window._serverProfile.ui.face_mode = id;
+        }
+
+        eventBus.emit('face:changed', { from: previousId, to: id });
+    }
+
+    /**
+     * Load the previously saved face (or a default).
+     * @param {string} [defaultId]
+     */
+    async loadSaved(defaultId = 'eyes') {
+        let saved = defaultId;
+        try { saved = window._serverProfile?.ui?.face_mode || defaultId; } catch (_) {}
+        await this.load(saved);
+    }
+
+    /**
+     * Delegate setMood to the active face.
+     * @param {string} mood
+     */
+    setMood(mood) {
+        this._active?.setMood(mood);
+    }
+
+    /** Delegate blink to the active face. */
+    blink() {
+        this._active?.blink();
+    }
+
+    /**
+     * Delegate amplitude to the active face.
+     * @param {number} amplitude
+     */
+    setAmplitude(amplitude) {
+        this._active?.setAmplitude(amplitude);
+    }
+
+    /** @returns {string|null} */
+    get activeFaceId() {
+        return this._active?.id ?? null;
+    }
+
+    /** @returns {string} */
+    get currentMood() {
+        return this._active?.currentMood ?? 'neutral';
+    }
+
+    /** @returns {Array<{id, name, description}>} faces from manifest */
+    get availableFaces() {
+        return this._manifest?.faces ?? [];
+    }
+}
+
+// Singleton
+export const faceManager = new FaceManager();

package/src/face/EyeFace.js

@@ -0,0 +1,208 @@
+/**
+ * EyeFace — animated eye face extracted from index.html FaceModule
+ *
+ * Renders two eyes with:
+ *   - Mood-based eyelid animations (happy, sad, angry, thinking, surprised, listening)
+ *   - Mouse-tracking pupil movement
+ *   - Random autonomous blinking and looking behavior
+ *
+ * Usage (via FaceManager):
+ *   import { faceManager } from './BaseFace.js';
+ *   import { EyeFace } from './EyeFace.js';
+ *
+ *   faceManager.register('eyes', () => new EyeFace());
+ *   await faceManager.loadSaved('eyes');
+ *
+ * Or standalone:
+ *   import { EyeFace } from './EyeFace.js';
+ *   const face = new EyeFace();
+ *   face.init(document.querySelector('.face-box'));
+ *   face.setMood('happy');
+ */
+
+import { BaseFace, VALID_MOODS } from './BaseFace.js';
+import { eventBus } from '../core/EventBus.js';
+
+export class EyeFace extends BaseFace {
+    constructor() {
+        super('eyes');
+
+        /** @type {HTMLElement|null} */
+        this._leftEye = null;
+        /** @type {HTMLElement|null} */
+        this._rightEye = null;
+        /** @type {HTMLElement|null} */
+        this._leftPupil = null;
+        /** @type {HTMLElement|null} */
+        this._rightPupil = null;
+
+        /** @private timer IDs for cleanup */
+        this._blinkTimer = null;
+        this._lookTimer = null;
+        this._lastMouseMove = Date.now();
+
+        /** @private bound handlers for removeEventListener */
+        this._onMouseMove = this._handleMouseMove.bind(this);
+
+        /** @private eventBus unsub functions */
+        this._unsubs = [];
+    }
+
+    /**
+     * @param {HTMLElement} container  .face-box element
+     * @override
+     */
+    init(container) {
+        this.container = container;
+
+        // Grab existing DOM elements (created by index.html shell)
+        this._leftEye = document.getElementById('left-eye');
+        this._rightEye = document.getElementById('right-eye');
+        this._leftPupil = document.getElementById('left-pupil-container');
+        this._rightPupil = document.getElementById('right-pupil-container');
+
+        if (!this._leftEye || !this._rightEye) {
+            console.warn('[EyeFace] Eye elements not found in DOM');
+            return;
+        }
+
+        // Show eyes in case another face had hidden them
+        const eyesContainer = container.querySelector('.eyes-container');
+        if (eyesContainer) eyesContainer.style.display = 'flex';
+
+        // Subscribe to EventBus mood changes
+        this._unsubs.push(
+            eventBus.on('tts:start', () => this.setMood('listening')),
+            eventBus.on('tts:stop', () => this.setMood('neutral')),
+            eventBus.on('stt:start', () => this.setMood('listening')),
+            eventBus.on('stt:stop', () => this.setMood('neutral')),
+        );
+
+        this._startRandomBehavior();
+        this._emitReady();
+    }
+
+    /**
+     * Set the eye mood by toggling CSS mood classes on the eye elements.
+     * @param {string} mood
+     * @override
+     */
+    setMood(mood) {
+        if (!this._leftEye || !this._rightEye) return;
+
+        mood = this._normalizeMood(mood);
+
+        // Remove all mood classes
+        VALID_MOODS.forEach(m => {
+            this._leftEye.classList.remove(m);
+            this._rightEye.classList.remove(m);
+        });
+
+        // Add new mood class (neutral has no class)
+        if (mood !== 'neutral') {
+            this._leftEye.classList.add(mood);
+            this._rightEye.classList.add(mood);
+        }
+
+        this._emitMood(mood);
+    }
+
+    /**
+     * Trigger a quick blink animation (~150ms).
+     * @override
+     */
+    blink() {
+        if (!this._leftEye || !this._rightEye) return;
+
+        this._leftEye.classList.add('blinking');
+        this._rightEye.classList.add('blinking');
+
+        setTimeout(() => {
+            this._leftEye.classList.remove('blinking');
+            this._rightEye.classList.remove('blinking');
+        }, 150);
+    }
+
+    /**
+     * Move pupils toward a screen coordinate.
+     * @param {number} x  client X
+     * @param {number} y  client Y
+     */
+    updateEyePosition(x, y) {
+        if (!this._leftPupil || !this._rightPupil) return;
+
+        const centerX = window.innerWidth / 2;
+        const centerY = window.innerHeight / 2;
+        const maxOffset = 15;
+
+        const offsetX = ((x - centerX) / centerX) * maxOffset;
+        const offsetY = ((y - centerY) / centerY) * maxOffset;
+
+        const transform = `translate(${offsetX}px, ${offsetY}px)`;
+        this._leftPupil.style.transform = transform;
+        this._rightPupil.style.transform = transform;
+    }
+
+    /**
+     * Remove all event listeners, timers, and DOM mutations.
+     * @override
+     */
+    destroy() {
+        // Clear timers
+        if (this._blinkTimer) { clearTimeout(this._blinkTimer); this._blinkTimer = null; }
+        if (this._lookTimer) { clearTimeout(this._lookTimer); this._lookTimer = null; }
+
+        // Remove mouse listener
+        document.removeEventListener('mousemove', this._onMouseMove);
+
+        // Unsubscribe from eventBus
+        this._unsubs.forEach(unsub => unsub());
+        this._unsubs = [];
+
+        // Clear all mood classes
+        if (this._leftEye && this._rightEye) {
+            VALID_MOODS.forEach(m => {
+                this._leftEye.classList.remove(m);
+                this._rightEye.classList.remove(m);
+            });
+        }
+
+        this._initialized = false;
+    }
+
+    // ── private ───────────────────────────────────────────────────────────────
+
+    /** Start autonomous random blinking and looking timers. */
+    _startRandomBehavior() {
+        // Random blinking: every 2-6 seconds
+        const scheduleBlink = () => {
+            this._blinkTimer = setTimeout(() => {
+                this.blink();
+                scheduleBlink();
+            }, 2000 + Math.random() * 4000);
+        };
+        scheduleBlink();
+
+        // Mouse tracking
+        document.addEventListener('mousemove', this._onMouseMove);
+
+        // Random looking when mouse is idle
+        const scheduleRandomLook = () => {
+            this._lookTimer = setTimeout(() => {
+                if (Date.now() - this._lastMouseMove > 2000) {
+                    const x = window.innerWidth * (0.2 + Math.random() * 0.6);
+                    const y = window.innerHeight * (0.15 + Math.random() * 0.5);
+                    this.updateEyePosition(x, y);
+                }
+                scheduleRandomLook();
+            }, 1500 + Math.random() * 2500);
+        };
+        scheduleRandomLook();
+    }
+
+    /** @private */
+    _handleMouseMove(e) {
+        this._lastMouseMove = Date.now();
+        this.updateEyePosition(e.clientX, e.clientY);
+    }
+}