Architecture

Architecture et contribution

Vue d’ensemble

src/
  pages/            assemblage de la page
  components/       UI React, un dossier par composant
  hooks/            état et orchestration React
  contexts/         contextes partagés
  services/         fichiers natifs, worker, préférences
  utils/logic/      moteur pur (sans React/DOM/natif)
  utils/            formats, exercices, SVG, keybinds, etc.
  styles/           tokens, global, polices
tests/
  logic/            moteur
  workspace/        formats, UI pure, exercices
  transpilation/    backends
docs/               contrats et état du projet
abstract/           site statique de présentation

Moteur

• Pur : aucun import React, DOM ou Neutralinojs.
• Source JSON v1 : modules + nœuds, relations distinctes moduleId, children, references.
• AST dérivé : arbre tolérant, trous et fragments invalides.
• Sémantique : portées, déclarations, types, génériques, diagnostics.
• Mutations : insertion, édition, suppression, déplacement, duplication, réordonnancement, contrats. Atomiques, avec réanalyse et rejet des régressions dures.
• Simulation : Run live coopératif par défaut, Run borné, debug, trace.
• Transpilation : JavaScript, Python et C expérimental restreint.
• Dashboard : export HTML autonome avec moteur embarqué.

Données

La source logique est la référence. L’AST, les types, les diagnostics et les index sont recalculés. La présentation (cartes, positions, pliage, notes, exercice) est séparée.

UI

• Composants fonctionnels, props explicites.
• Hooks spécialisés pour l’état complexe.
• Services pour les fichiers et le worker.
• Pas de bibliothèque UI tierce.
• Tokens CSS centralisés.

SDK et plugins

Les SDK locaux sont des packages ESM construits par Vite : @sapphire3/core (projet et AST), @sapphire3/runtime, @sapphire3/Transpiler, @sapphire3/debug, @sapphire3/project, @sapphire3/graph et @sapphire3/plugin-sdk. Ils réutilisent le moteur sans React ni API native.

Le Plugin SDK ajoute une couche déclarative : manifeste .sp3plugin, widgets, opérations natives typées et composites de niveau A. Le registre est configuré avant l’analyse, injecté dans les Workers et revalidé avant exécution. Les widgets restent des cartes de présentation, sans module ni AST. Voir Plugins.

Tests

pnpm test

770 tests Node et Python couvrent notamment :

• moteur, types, portées, génériques, lambdas, pointeurs ;
• mutations et diagnostics ;
• workspace, migrations, sauvegardes ;
• transpilation JavaScript/Python et C expérimental ;
• exemples, widgets, entrées typées, exercices, verrou PBKDF2 ;
• Run live, dashboard exporté, widgets de plugin et mini-carte ;
• SDK Core, Runtime, Transpiler, Debug, Project, Graph et Plugin ;
• accessibilité pure et formats.

CI

.github/workflows/ci.yml s’exécute sur chaque pull request :

1. installation pnpm --frozen-lockfile ;
2. construction et tests du sidecar Discord ;
3. contrôle des espaces, marqueurs de conflit et tests focalisés ;
4. pnpm test ;
5. pnpm build.

Contribuer

• Respecter AGENTS.md.
• Avancer par petits incréments demandés.
• Ne pas ajouter de dépendance sans nécessité.
• Ajouter ou adapter les tests purs.
• Mettre à jour docs/PROJECT_STATE.md après une fonctionnalité ou un changement structurant.
• Vérifier proportionnellement : tests, build, navigateur, natif si concerné.

Points d’entrée de lecture

• docs/LOGIC_API.md — contrats du moteur.
• docs/WORKSPACE_FILES.md — format .sp3.
• docs/EXERCISES.md — mode exercice.
• docs/ACCESSIBILITY.md — audit.
• docs/PROJECT_STATE.md — état et cartographie.