0.1.1-alpha.4

docs/templates/009-WEB_VITE.md

@@ -0,0 +1,174 @@
+<!-- file: docs/templates/009-WEB_VITE.md -->
+<!-- version: 1 -->
+
+# Guide d'adaptation Vite
+
+## Rôle
+
+Ce document accompagne le profil [`550-VITE.md`](../rules/550-VITE.md) lorsqu'un projet sélectionne réellement Vite.
+
+Il ne fournit volontairement pas de `vite.config.ts` copiable universel. Les corpus montrent une responsabilité réutilisable claire pour Vite, mais pas des valeurs universelles pour les chemins, ports, aliases, plugins ou hosts.
+
+L'objectif est donc de normaliser **ce qui doit être décidé et validé**, sans figer arbitrairement **la valeur de chaque décision**.
+
+## Manifest
+
+Le manifest réel du projet doit utiliser le package manager choisi par le projet et ajouter Vite comme outil de développement avec une version explicitement décidée.
+
+Les scripts usuels, lorsqu'ils correspondent au workflow réel, sont conceptuellement :
+
+```json
+{
+    "scripts": {
+        "dev": "vite",
+        "build": "vite build",
+        "preview": "vite preview"
+    }
+}
+```
+
+Ce fragment n'est pas un template complet de `package.json` et ne sélectionne aucun package manager.
+
+`dev` et `build` sont naturels lorsqu'un frontend Vite existe. `preview` MAY être omis si aucun smoke/prévisualisation locale ne l'utilise.
+
+Le type-check TypeScript reste une preuve séparée :
+
+```text
+typecheck -> tsc --noEmit
+build     -> vite build
+```
+
+Une CI peut exécuter successivement ces deux scripts sans imposer une syntaxe npm particulière.
+
+## Décider `root`
+
+Si `index.html` et les sources se trouvent à la racine comprise par Vite, aucune valeur explicite n'est nécessaire uniquement pour respecter PGR.
+
+Si le package contient une racine frontend dédiée, le projet doit configurer `root` vers cette racine. Le nom `frontend/` observé dans Games est une convention locale utile mais pas une obligation générique.
+
+## Décider `base`
+
+`base` doit suivre le mode réel de service/embarquement :
+
+```text
+site servi à la racine       souvent /
+site sous un sous-chemin     chemin public correspondant
+host embarqué                valeur relative si réellement requise
+```
+
+PGR ne copie donc pas automatiquement `base: "./"` depuis Games dans tous les projets Vite.
+
+## Cache
+
+Le cache Vite est reproductible et ne doit pas devenir un source versionné.
+
+Ordre de préférence PGR :
+
+1. placer `cacheDir` hors de l'arborescence source lorsqu'un emplacement de build externe existe déjà et reste simple à utiliser ;
+2. sinon accepter un cache interne dédié et l'ignorer explicitement ;
+3. ne jamais versionner le cache uniquement pour accélérer une machine locale.
+
+L'effacement du cache doit rester sans conséquence fonctionnelle autre qu'un recalcul.
+
+## Output de production
+
+`build.outDir` contient des artefacts générés.
+
+Ordre de préférence PGR :
+
+1. utiliser un répertoire de build externe au source tree si l'environnement du projet le permet proprement ;
+2. sinon utiliser un répertoire interne dédié, tel que `dist/`, explicitement ignoré ;
+3. ne versionner un output que si un autre contrat de distribution l'exige réellement et documente cet artefact comme livrable.
+
+Si `build.emptyOutDir` est activé, `outDir` doit être dédié à Vite. Le build ne doit pas pouvoir vider un répertoire partagé avec du WASM, des artefacts Rust, Android ou d'autres owners.
+
+## Assets
+
+Trois catégories doivent rester distinguées :
+
+```text
+asset source importé/référencé      source versionné
+asset source dans publicDir         source statique versionné
+asset copié/transformé dans outDir  output généré
+```
+
+`publicDir` MAY rester au défaut Vite, être déplacé ou être désactivé avec `false` selon le besoin du projet.
+
+Une copie réalisée par plugin n'autorise pas à supprimer la source de son owner ni à versionner la copie de build comme second source.
+
+## Dev server et exposition réseau
+
+Pour un développement local simple, rester sur une écoute locale/loopback est préférable.
+
+N'élargir `server.host` au LAN/toutes interfaces que lorsqu'un besoin réel l'impose, par exemple un test sur device ou un host externe. Dans ce cas, revoir aussi les contraintes de hosts autorisés, CORS, TLS, proxy et HMR selon l'intégration réelle.
+
+PGR déconseille les raccourcis globaux :
+
+```text
+server.allowedHosts = true
+server.cors = true
+```
+
+Ils ne doivent pas devenir des valeurs de template universelles.
+
+## Ports déterministes
+
+Un port fixe n'est pas une règle PGR universelle.
+
+Si rien ne consomme une URL déterministe, laisser Vite gérer son port peut être suffisant.
+
+Si un host ou un smoke attend un port connu, utiliser ensemble :
+
+```text
+server.port       valeur locale choisie
+server.strictPort true
+```
+
+Ainsi, un conflit de port échoue explicitement au lieu de déplacer silencieusement le dev server.
+
+La même logique peut s'appliquer à `preview.port` + `preview.strictPort` lorsqu'un smoke de preview exige une URL stable.
+
+## Preview
+
+`vite preview` sert à vérifier localement le build produit. Il ne constitue pas un serveur de production PGR.
+
+Un smoke MAY lancer `preview` après un build lorsque cette observation apporte une preuve nécessaire. Le deployment/serving réel reste hors du présent owner.
+
+## Ce qui reste local
+
+La configuration suivante n'est pas normalisée par ce guide sans preuve supplémentaire :
+
+```text
+ports exacts
+host exact
+base exact
+aliases
+plugins
+noms de chunks/assets
+minification
+sourcemaps
+proxy
+TLS
+HMR / WebSocket
+filesystem allowlists
+intégration WASM
+intégration Tauri
+```
+
+Games fournit des exemples utiles pour plusieurs de ces points, mais PGR ne transforme pas ces valeurs en défauts génériques.
+
+## Validation dans PGR et dans un projet destinataire
+
+PGR ne livre pas encore de `vite.config.ts` exécutable générique dans cette tranche ; il n'installe donc pas Vite uniquement pour valider un fichier fictif.
+
+Dans un projet réel qui adopte ce profil, la gate applicable doit sélectionner l'outil réel et peut comprendre :
+
+```text
+typecheck séparé
+build Vite de production
+inspection du outDir attendu
+preview/smoke seulement si nécessaire
+validation du host séparée
+```
+
+Les commandes concrètes passent par le package manager sélectionné par le projet. Un exemple npm dans une documentation tierce ne devient pas une obligation PGR.