sasedev-knowledge/docs/studies/002-ACTIX_MAUD_VITE_CORPUS_STUDY.md

Étude Actix/Maud/Vite — corpus actix-auth-app

Objet

Cette étude extrait uniquement le pattern d’intégration frontend/backend observé dans l’archive historique inachevée :

actix-auth-app-master.zip
SHA-256 bcdf4c568c827b77c70ee476218c2b07ea0fca408ab87d2f044333309d19ab71

Le corpus n’est pas une baseline autoritaire et son code n’est pas copié tel quel. L’objectif est de cadrer la future composition Knowledge entre :

• templates statiques et assets validés par le profil Web PGR ;
• rendu SSR Maud ;
• serveur Actix Web ;
• assets Vite hashés en production.

Pattern effectivement observé

Build Vite

Le fichier frontend/vite.config.ts observé :

• utilise frontend/ comme root ;
• configure un dev server sur le port 5173 ;
• utilise une base de production /res ;
• produit dans ../public/res ;
• active build.manifest = true ;
• déclare des entrées TypeScript et Sass explicites ;
• produit des noms JS/CSS hashés ;
• copie plusieurs familles d’assets statiques avec vite-plugin-static-copy ;
• utilise sass-embedded.

Ces choix prouvent qu’un build Vite peut servir de pipeline d’assets pour un backend SSR. Ils ne rendent ni /res, ni le port 5173, ni cette arborescence normatifs pour Knowledge.

Loader Rust

Le module src/app/vite.rs observé charge .vite/manifest.json en release et expose un Loader::entry_url(entry_key, fallback). Une entrée stable du type ts/main.ts ou sass/main.scss est ainsi convertie vers un fichier hashé du build.

Le loader existe aussi en debug, mais son manifest reste absent et entry_url renvoie alors un fallback. Les handlers choisissent de leur côté des URLs directes du dev server Vite en debug et la résolution par manifest en release.

Composition Maud

Les handlers Actix construisent le markup avec Maud puis injectent les URLs CSS/JS selon le mode :

dev     -> URL d’entrée Vite directe
release -> entrée stable -> manifest Vite -> URL d’asset hashé

Le pattern démontre que Vite et Maud ne sont pas concurrents : Vite possède la chaîne d’assets/client, tandis que Maud possède le markup runtime.

Éléments à reprendre conceptuellement

Knowledge retient pour ses futures tranches Web/serveur :

1. un frontend validable indépendamment des serveurs Rust ;
2. des templates statiques de référence pour travailler le markup et les assets ;
3. TypeScript, Sass et Bootstrap consommés par la chaîne Vite sélectionnée ;
4. un build de production avec manifest ;
5. des clés d’entrée stables indépendantes des noms hashés ;
6. un composant Rust commun capable de résoudre ces clés pour les pages Maud ;
7. une voie de développement utilisant le dev server Vite lorsqu’elle est utile ;
8. une gate d’intégration distincte prouvant que le backend résout réellement les sorties du build.

Éléments à ne pas copier mécaniquement

Le corpus contient plusieurs décisions locales ou incompatibles avec les règles Knowledge :

• http://localhost:5173 est codé directement dans plusieurs fichiers ;
• /res est traité comme convention locale ;
• le loader panique en release lorsqu’un manifest est absent/invalide ;
• l’arborescence et les copies d’assets sont spécifiques à l’application ;
• @types/node et @types/bootstrap existent dans le package mais doivent être réévalués selon les usages TypeScript réels ;
• le package utilise un alias npm rolldown-vite, choix qui n’est pas adopté automatiquement par Knowledge ;
• la présence de plusieurs fallbacks statiques peut masquer une divergence si elle n’est pas testée explicitement.

Knowledge devra donc adapter le pattern avec erreurs récupérables et observables, configuration explicite, tests et dépendances justifiées.

Contrat retenu pour 0.0.1

alpha.4

La tranche Web possède :

• choix explicite du package manager et du lockfile ;
• TypeScript strict et script typecheck ;
• Vite ;
• Sass ;
• Bootstrap ;
• templates statiques de référence ;
• build de production ;
• manifest Vite ;
• preview/smoke navigateur seulement lorsqu’une propriété runtime le justifie.

Elle ne possède pas encore le rendu Maud ni la lecture Rust du manifest.

alpha.5

La tranche de composition serveur possède :

• trois launchers Actix Web minces ;
• rendu Maud ;
• intégration avec les assets construits par alpha.4 ;
• résolution production par manifest ;
• configuration de la voie dev Vite si conservée ;
• tests/smokes ciblés de l’intégration.

La décision de créer ou non un knowledge-web-lib commun dépendra du code réellement partagé entre les trois serveurs.

Source de vérité UI

Les templates statiques sont des artefacts de référence et validation, pas une deuxième application à servir en production. Le markup runtime est Maud.

La tranche Web devra définir une méthode proportionnée pour limiter la dérive entre les deux représentations : par exemple contrats de classes/attributs critiques, snapshots ciblés ou smokes navigateur. La méthode exacte reste DEFER jusqu’à alpha.4; PGR n’impose pas une duplication exhaustive ni un framework de test particulier.