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.

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 :

Stack technologique frontend¶
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 ¶

Arborescence des Sources ¶

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 ¶

Réacteur central en écoute vocale active (MIC ACTIVE) — Réacteur central en état d’écoute active (**MIC ACTIVE**) : ondes vocales dorées réactives modulées par l’énergie acoustique (Couche 5).¶

Détail des 5 couches de rendu¶
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 :

Widgets satellites¶
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.

Satellite Agent activé avec arcs cyan — Activation du mode Agent (**Agent ON**) : le satellite central s’illumine en cyan et les anneaux d’acquisition orbitale passent en bleu néon.¶

Satellite BrainBoost activé en mode haute réflexion — 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)¶

Tiroir des documents et résultats d'outils — 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 ¶

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 :

Mécanismes anti-suspension audio¶
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.