Momento/memento-note/lib/simulators/README.md

Simulateurs interactifs (plugins)

Bibliothèque de simulateurs pédagogiques pour les pages interactives (/p/{slug}). L'IA ne code jamais une simulation : elle choisit un simulateur de cette liste et le configure (preset = valeurs de la note), ou utilise generic-formula si aucun ne correspond au sujet.

Liste des simulateurs disponibles

simId	Famille	Sujet	Interaction
carnot-cycle	sim	Machine frigorifique / PAC / moteur de Carnot (2ᵉ principe)	Curseurs T_c, T_h, Q_c → COP, η, W min, Q_h en direct
carnot-cycle-anim	anim	Cycle de Carnot animé (piston + diagramme P–V live, 5 étapes)	Play / Pause / Step / Reset / vitesse + narration
generic-formula	sim	(générique) toute relation chiffrée y = f(paramètres)	Curseurs définis par l'IA, expressions sûres (aucun eval)

Deux familles de plugins : sim (manipulation de paramètres, calcul en direct) et anim (scène animée codée en dur, pilotée par le player Play/Step — narration par battements). Les deux sont choisis par l'IA via le même bloc { "type": "sim" }.

Comment l'IA les utilise

1. Le prompt de génération de section injecte catalogForPrompt(lang) (registry.ts) — id + résumé + mots-clés + bornes de chaque simulateur.
2. Si le contenu de la note correspond (keywords), l'IA émet { "type": "sim", "sim": { "simId": "carnot-cycle", "preset": { "t_hot": 300 } } }.
3. validateInteractivePage vérifie : simId connu, preset dans les bornes, compute(preset) fini — sinon rejet (renvoyé au LLM ou fallback).

Ajouter un plugin (5 étapes)

Pour un sim (curseurs) :

1. lib/simulators/<id>.ts — implémenter SimulatorPlugin (family: 'sim') : id, title/summary fr+en (le summary sert au matching IA), keywords, params (curseurs : bornes, pas, défaut, unité, intent), outputs (symbole KaTeX, unité), et compute(env) pur et déterministe.
2. lib/simulators/index.ts — ajouter au REGISTRY.
3. components/simulators/<id>-view.tsx — composant sur mesure (props : preset, title, disclaimer, lang). Réutiliser SimSlider / SimOutputCard / SimHeading / SimKaTeX de sim-controls.tsx.
4. components/simulators/index.ts — enregistrer dans SIMULATOR_VIEWS.
5. Vérifier : compute fini aux valeurs par défaut, npx tsc --noEmit, tester sur /dev/interactive-page.

Pour une anim (scène animée Play/Step) :

1. lib/simulators/<id>.ts — implémenter AnimPlugin (family: 'anim') : id, title/summary fr+en, keywords, disclaimer?, beats (narration fr+en par étape — KaTeX inline $…$ dans speak).
2. lib/simulators/index.ts — ajouter au REGISTRY.
3. components/simulators/<id>-anim-view.tsx — scène SVG/React pilotée par step (props : step, lang). Transitions CSS sur transform/opacity uniquement. Le chrome (Play/Pause/Step/Reset/vitesse + panneau de narration + clavier Espace/←/→/R) est fourni par AnimPlayerShell — ne pas le réécrire.
4. components/simulators/index.ts — enregistrer dans ANIM_VIEWS.
5. Vérifier : chaque step rend un état cohérent (y compris état final sans JS), npx tsc --noEmit, tester sur /dev/interactive-page.

Règles : pas de couleurs en dur (intents / tokens --pp-*), labels fr+en dans le plugin, tout calcul côté compute ou scène codée (jamais de logique LLM), SSR = état lisible sans JS.