.. _arch-frontend: Architecture Frontend ===================== Cette section documente l'interface HUD (Heads-Up Display) de Mirza : stack technologique, organisation des composants React, protocole WebSocket binaire, rendu haute performance via OffscreenCanvas et gestion audio sur mobile. .. contents:: Sommaire :local: :depth: 2 ---- Vue d'Ensemble -------------- Le frontend de Mirza est une application monopage (**SPA**) haute performance conçue pour fournir un retour visuel en temps réel synchronisé avec l'orchestrateur vocal Python : .. figure:: mirza_hud_overview.png :alt: Vue d'ensemble du HUD client Mirza :align: center :width: 60% Vue générale de l'interface mobile : réacteur central réactif, télémétrie en direct et commandes de session. .. list-table:: Stack technologique frontend :widths: 30 20 50 :header-rows: 1 * - Technologie - Version - Rôle * - **React** - 18.x - Framework UI — gestion d'état, rendu déclaratif * - **TypeScript** - 5.x - Typage statique strict, interfaces WebSocket typées * - **Vite** - 5.x - Build rapide, HMR, optimisation des assets * - **Web Audio API** - Standard W3C - Capture micro PCM, lecture audio, oscillateur keep-alive * - **WebSocket API** - Standard W3C - Communication bidirectionnelle WSS avec transport binaire * - **OffscreenCanvas API** - Standard W3C - Délégation du rendu GPU au Web Worker (60/120 FPS sans jank UI) * - **KaTeX** - 0.16.x - Rendu LaTeX inline (``$...$``) et bloc (``$$...$$``) ---- Architecture des Composants React ----------------------------------- .. image:: /_static/diagrams/frontend_components.svg :alt: Arborescence des composants React :align: center :class: d2-diagram ---- Arborescence des Sources -------------------------- .. code-block:: text widget/src/ ├── main.tsx Point d'entrée React (StrictMode) ├── App.tsx Composant racine — état global et synchronisation hooks ├── types/ │ ├── telemetry.ts Métriques matérielles, tok/s, TTFT, état KV Cache │ ├── websocket.ts Union discriminée ServerEvent et ClientAction (TypeScript) │ ├── audio.ts États HUD : idle · listening · processing · speaking · agent │ ├── chat.ts Messages du chat et entrées de logs système │ └── history.ts Entrées de documentation et résultats agentiques (DOCS) ├── hooks/ │ ├── useWebSocket.ts WebSocket WSS avec reconnexion auto et transport binaire │ ├── useAudioRecorder.ts Capture micro WebAudio — ScriptProcessorNode PCM 16 kHz │ ├── useAudioPlayer.ts Lecture WebAudio + oscillateur keep-alive inaudible │ ├── useClock.ts Horloge locale synchronisée toutes les secondes │ └── useTheme.ts Interpolation dynamique des couleurs CSS ├── components/ │ ├── TopBar/ En-tête : horloge, statut, bouton extinction │ ├── Gauges/ Jauges circulaires RAM, VRAM, débit tokens/s, TTFT │ ├── Reactor/ │ │ ├── ReactorSection.tsx Conteneur du réacteur HUD et commandes audio Push-to-Talk │ │ ├── MainEyeCanvas.tsx Délègue le canvas au Worker (OffscreenCanvas) │ │ ├── eyeRenderer.worker.ts Web Worker — rendu 5 couches à 60/120 FPS │ │ ├── SatelliteBrainBoost.tsx Sélecteur de budget CoT (0 · 512 · 1024 · 2048 · 4096) │ │ ├── AgentCubeTrigger.tsx Déclencheur du mode Agent + menu outils │ │ ├── KVCacheWidget.tsx Satellite Contexte / KV Cache avec flush par maintien │ │ ├── CodeGeneratingReactor.tsx Réacteur oscillant de génération code / agent │ │ ├── AgentDocBadge.tsx Badge résultat Markdown / LaTeX et code │ │ ├── AgentToolsModal.tsx Modal de configuration des outils agentiques │ │ ├── ContextInspectorModal.tsx Modal d'inspection détaillée du prompt et contexte RAG │ │ └── HistoryWidgetModal.tsx Visualiseur interactif Docs, Historique & Mémoire SQL │ ├── Panels/ │ │ ├── BottomSplit.tsx Barre inférieure avec commande vocale et saisie texte │ │ └── BottomSheet.tsx Tiroir rétractable responsive │ └── common/ Icônes SVG vectorielles ├── utils/ │ └── formatMarkdown.ts Moteur KaTeX + Markdown → HTML sécurisé └── styles/ └── hud.css Thème Cyber Crimson — variables CSS, animations ---- Le Réacteur Central — Rendu OffscreenCanvas -------------------------------------------- .. image:: /_static/diagrams/frontend_offscreen.svg :alt: Architecture du rendu OffscreenCanvas dans le Web Worker :align: center :class: d2-diagram .. figure:: mirza_reactor_listening.png :alt: Réacteur central en écoute vocale active (MIC ACTIVE) :align: center :width: 60% Réacteur central en état d'écoute active (**MIC ACTIVE**) : ondes vocales dorées réactives modulées par l'énergie acoustique (Couche 5). .. list-table:: Détail des 5 couches de rendu :widths: 10 30 60 :header-rows: 1 * - Couche - Nom - Description * - **1** - Halo Laser Radial - Dégradé radial dynamique du centre vers l'extérieur. Intensité modulée par l'état (idle→speaking). * - **2** - Réticule Concentrique - Cercles concentriques rotatifs calculés trigonométriquement. Vitesse indexée sur le débit LLM. * - **3** - Ondes Vocales Mirza - Couronne de vagues vectorielles soyeuses animées selon l'amplitude audio TTS reçue. * - **4** - Arcs Orbitaux (Agent) - Arcs périphériques fixes en mode standard. **Transition vers bleu néon** (``#00e5ff``) avec interpolation ``smoothAgentPct`` lors de l'activation du mode Agent. * - **5** - Ruban Utilisateur - Ruban de vagues symétriques actif **uniquement pendant la capture microphone**, réagissant au niveau RMS de l'audio entrant. ---- Constellation Satellite ------------------------ Autour de l'œil central orbitent trois widgets satellites interactifs : .. image:: /_static/diagrams/frontend_satellites.svg :alt: Positionnement des satellites autour du réacteur principal :align: center :class: d2-diagram .. list-table:: Widgets satellites :widths: 15 25 60 :header-rows: 1 * - Widget - Composant - Rôle * - **BrainBoost** - ``SatelliteBrainBoost.tsx`` - Curseur circulaire de budget CoT : 0, 512, 1024, 2048 ou 4096 tokens de réflexion. * - **Agent** - ``AgentCubeTrigger.tsx`` - Activation/désactivation du mode agentique. Menu de configuration des outils disponibles. * - **Contexte (KV Cache)** - ``KVCacheWidget.tsx`` - Satellite contextuel à jauge annulaire. Maintien prolongé pour flush du cache, double-tap pour ouvrir l'inspecteur. * - **Génération Active** - ``CodeGeneratingReactor.tsx`` - Réacteur oscillant central alertant en temps réel lorsque du code est produit ou qu'un agent ReAct est à l'œuvre. * - **Docs & Historique** - ``AgentDocBadge.tsx`` & ``HistoryWidgetModal.tsx`` - Badge discret ouvrant le visualiseur complet : documents générés, mémoire épisodique SQL et historique. .. figure:: mirza_reactor_agent_active.png :alt: Satellite Agent activé avec arcs cyan :align: center :width: 60% Activation du mode Agent (**Agent ON**) : le satellite central s'illumine en cyan et les anneaux d'acquisition orbitale passent en bleu néon. .. figure:: mirza_reactor_brainboost_active.png :alt: Satellite BrainBoost activé en mode haute réflexion :align: center :width: 60% Mode de réflexion approfondie (**BrainBoost HIGH**) : faisceau d'énergie dirigé vers le réacteur et aura violette indicatrice de calcul de chaîne de pensée (CoT). ---- Restitution Documentaire et Historique (HistoryWidgetModal) ----------------------------------------------------------- .. figure:: mirza_drawer_docs_results.png :alt: Tiroir des documents et résultats d'outils :align: center :width: 60% Tiroir des résultats structurés (**DOCS & RÉSULTATS**) : restitution des fiches cliniques, synthèses documentaires et données générées par les outils hors du canal vocal. ---- Protocole Audio WebSocket -------------------------- .. image:: /_static/diagrams/frontend_audio_ws.svg :alt: Protocole de transfert audio binaire client ↔ serveur :align: center :class: d2-diagram ---- Gestion Audio Mobile et Anti-Suspension ----------------------------------------- Les navigateurs mobiles (iOS Safari, Android Chrome) appliquent des restrictions agressives sur le contexte WebAudio. Mirza contourne ces restrictions via deux mécanismes : .. list-table:: Mécanismes anti-suspension audio :widths: 30 70 :header-rows: 1 * - Mécanisme - Description * - **Oscillateur Keep-Alive** - Un oscillateur WebAudio à gain inaudible (``1e-5``) est maintenu actif en permanence dans ``useAudioPlayer.ts``. Cela empêche iOS Safari de suspendre le contexte audio pendant les phases de silence (réflexion CoT ou inactivité utilisateur). * - **Déblocage Tactile** - Un écouteur global ``touchstart`` / ``pointerdown`` intercepte le premier contact et appelle ``audioContext.resume()``. Requis par les politiques d'autoplay navigateur. * - **MuteGain Anti-Larsen** - Le ``ScriptProcessorNode`` de capture est connecté à un ``GainNode`` à valeur ``0`` avant ``context.destination``, empêchant physiquement le retour sonore et l'activation de l'AGC (Automatic Gain Control) hardware. ---- Flux de Données Complet Frontend ---------------------------------- .. image:: /_static/diagrams/frontend_dataflow.svg :alt: Flux de données complet côté frontend :align: center :class: d2-diagram