docs: audit OKI - conforme, fix anti-spoiler credit photo

docs/audit-oki.md

@@ -0,0 +1,176 @@
+# Audit OKI — JWE v2 (Agent Intégration & QA)
+
+Date : 2026-07-17 · Périmètre : `app/` (SvelteKit 2 + Svelte 5 + MapLibre GL 5)
+Méthode : tests **réellement exécutés** sur le build de production (`node build`, PORT=4173) + revue de code. Chaque point est accompagné de sa preuve (commande, extrait).
+
+Légende : ✅ conforme · ⚠️ conforme avec réserve / point d'amélioration · ❌ non conforme
+
+---
+
+## 1. Build et vérifications statiques
+
+| Test | Résultat | Preuve |
+|---|---|---|
+| `npm run check` | ✅ | `svelte-check found 0 errors and 0 warnings` |
+| `npm run build` | ✅ | `✓ built in 5.05s` + `adapter-node ✔ done` |
+
+### Isolation de MapLibre (bundle initial)
+
+- Le chunk MapLibre `xnoNZPIh.js` (**1031 KB brut / 277,8 KB gzip**) n'est chargé que par `import("./xnoNZPIh.js")` **dynamique** depuis le chunk de `GameMap` — vérifié par `grep` dans `build/client/_app/immutable/`.
+- Le HTML SSR de `/` (5,6 KB) ne contient **0 occurrence** de « maplibre » et ne bootstrap que `entry/app.js` + `entry/start.js`.
+- Le CSS MapLibre (`maplibre-gl.*.css`, 68,3 KB / 9,8 KB gz) est un asset séparé, chargé par le même import dynamique (`GameMap.svelte:279`).
+
+**✅ Le bundle initial ne contient pas MapLibre.**
+
+---
+
+## 2. API — tests fonctionnels (serveur `node build`, PORT=4173)
+
+### 2.1 Anti-triche `/api/round` ✅
+
+15 tirages variés (sans filtre, `region`, `region+categorie`, `categorie`, `region+categorie+exclude` avec 2 ids exclus) :
+
+```
+15/15 tirages : AUCUNE fuite (clés coordonnees/commune/region/wikidata_id absentes)
+```
+
+Payload conforme à `docs/architecture.md` §5 : `{ id, nom, nom_creole, categorie, difficulte, photo{url,credit,alt}, indices[] }`. `Cache-Control: no-store` présent. Les filtres sont respectés (ex. `region=REUNION&categorie=LIEU` → Piton de la Fournaise).
+
+*Note : le `nom` du lieu est dans le payload — c'est le choix de la spec (§5), pas une fuite : le jeu nomme le monument à reconnaître.*
+
+### 2.2 Partie complète + cohérence du score ✅
+
+Scénario réel : `GET /api/round?region=GUADELOUPE` → Jardin botanique de Deshaies (DIFFICILE, r=5 km) → `POST /api/guess` avec coords fausses :
+
+- Réponse : `distanceKm: 38.5, score: 2` — recalcul indépendant haversine + `round(5000·e^(−38.5/5))` = **2** → écart 0.
+- Second test (Fort Delgrès, MOYEN, guess à 10,0 km, `hintsUsed: 1`, `timeMs: 30000`) : serveur **2540**, recalcul `min(5000, 2572×0,9 + 2572×0,9×0,2×0,5)` = **2540** → écart 0. Pénalité −10 %/indice et bonus temps ≤ +20 % conformes.
+- `skip: true` → `score: 0, distanceKm: null`, vérité révélée (extension documentée, cohérente avec le bouton « Passer »).
+- Erreurs : id inconnu → **404**, coords invalides → **400**, id manquant → **400**, JSON invalide → **400**.
+
+### 2.3 Cas A — lieu avec `wikidata_id` ✅
+
+| Lieu | `/api/guess` | `/api/wiki/{qid}` |
+|---|---|---|
+| Fort Delgrès | `wikidata_id: "Q3077840"` | 200, `title: "Fort Delgrès"`, extrait FR **422 car.**, `url: https://fr.wikipedia.org/wiki/Fort_Delgr%C3%A8s` |
+| Centre spatial guyanais | `wikidata_id: "Q308987"` | 200, extrait FR **447 car.**, url fr.wikipedia |
+
+Cache : `cache-control: public, max-age=3600` vérifié par `curl -I` ; cache mémoire TTL 24 h + User-Agent Wikimédia explicite dans `routes/api/wiki/[qid]/+server.ts`.
+
+### 2.4 Cas B — lacune documentaire (CRUCIAL) ✅
+
+Corpus : **9 lieux `wikidata_id: null`** (2 GP, 2 MQ, 3 GUY, 2 REU) — intentionnels, conformes au piège de la spec §Agent Contenu.
+
+- `POST /api/guess` sur **Plage de Bois Jolan** (`ff00fd1d…`) et **Anse Noire** (`cd652fb7…`) → `wikidata_id: null` dans les deux réponses. ✅
+- Rendu (`WikiFiche.svelte:64-78`) : `wikidataId` null → panneau **`.cas-b`** visuellement distinct (fond `--oki-lacune-fond` #fdf3e3, bordure 2px `--oki-lacune-bord` #d9a441, icône ◌ en pointillés) vs `.cas-a` vert doux. ✅
+- Titre exact de la spec : **« Pwen blindé — Sa pa dokimanté »** (`fr.ts:68`, `gcf.ts:70`). ✅
+- Texte FR conforme à §4.3 (« Ce lieu existe, mais il n'a pas de page sur Wikipédia ni de fiche sur Wikidata… qui alimentent même l'intelligence artificielle). ») + équivalent créole complet dans `gcf.ts:71-72`. ✅
+- CTA **« Kontribyé sou Wikipédia »** → `https://fr.wikipedia.org/w/index.php?search={nom du lieu}&title=Spécial:Recherche` — titre du lieu pré-rempli dans la recherche (`WikiFiche.svelte:38-40`) + lien secondaire vers le guide « Premiers pas ». ✅
+- **Chemin « qid non null mais wiki 404 »** : `/api/wiki/Q15646372` (entité sans sitelink fr) → **404** ; dans `WikiFiche.svelte:28`, `res.ok ? … : null` → **bascule bien sur le panneau Cas B** (même comportement sur erreur réseau, ligne 29-30). ✅
+- Chaîne « Pwen blindé » présente dans le bundle client livré (`grep` dans `build/`). ✅
+
+### 2.5 `/api/lieux` ✅
+
+40 lieux ; toutes les coords sont des **multiples exacts de 0,05** (vérifié par script, ex. Fort Delgrès → `{lat: 16, lon: -61.7}`). `Cache-Control: public, max-age=300`.
+
+### 2.6 Pages ✅
+
+`/` 200 · `/jeu/monument` 200 · `/jeu/lieu` 200 · `/jeu/defi` 200 · `/explorer` 200 · `/manifest.webmanifest` 200 · `/service-worker.js` 200 · `/icon.svg` 200 · `/jeu/triche` → **404** (mode invalide rejeté).
+
+SSR vérifié : le HTML de `/` contient `<h1>JWE</h1>` rendu serveur (contenu visible avant hydratation).
+
+---
+
+## 3. Parité i18n FR / créole ✅
+
+Script Node comparant les clés aplaties de `fr.ts` et `gcf.ts` :
+
+```
+clés fr : 77 | clés gcf : 77
+manquantes dans gcf : aucune — manquantes dans fr : aucune
+```
+
+Le message de lacune existe dans les DEUX langues (titre, texte, CTA, guide). Double garantie : `gcf` est typé `Dict` (`gcf.ts:3`), donc toute clé manquante casserait `npm run check`. L'attribut `<html lang>` est mis à jour au changement de langue (`store.svelte.ts:25`).
+
+---
+
+## 4. A11y / doctrine OKI (revue de code)
+
+| Point | Verdict | Preuve |
+|---|---|---|
+| `prefers-reduced-motion` | ✅ | Règle globale `oki.css:111-117` ; vol du marqueur désactivé (`GameMap.svelte:56-57,116-117`) et transitions cartes à `duration: 0` ; transition du bottom-sheet coupée (`explorer/+page.svelte:256-260`) |
+| Navigation clavier carte | ✅ | Zone carte `role="application"`, `tabindex="0"`, `aria-label` i18n ; flèches = déplacer le marqueur (pas constant en pixels), Entrée = valider (`GameMap.svelte:246-273`) ; focus-visible visible (`oki.css:67-72`) |
+| Une seule action primaire / écran | ⚠️ | Accueil : « Jouer » seul corail. Jeu : « Valider » seul corail (Passer = secondaire, Indice = tertiaire). Bilan : « Partager » seul. **Réserve** : écran résultat Cas B = bouton corail « Lieu suivant » **+** CTA orange « Kontribyé sou Wikipédia » — deux éléments fortement colorés. Cohérent avec Peak-End (§5), mais en tension avec « une seule action primaire ». À trancher en design review. |
+| Bouton Valider en zone pouce | ✅ | `.barre-actions` sticky en bas + `env(safe-area-inset-bottom)` (`jeu/[mode]/+page.svelte:374-384`) ; accueil : `.zone-pouce` fixe bas |
+| Timer non anxiogène | ✅ | `TimerRing` : cercle qui se vide, couleur douce `--oki-vert-clair`, **aucun chiffre**, **aucune échéance** (à 0 le tour continue, le bonus s'arrête juste) ; timer désactivé par défaut |
+| Pas de mécanique dopaminergique | ✅ | `grep -i 'streak|leaderboard|classement|loot|confetti'` → 0 résultat ; pas de session serveur, pas de compte, « Passer » = 0 point sans pénalité, ton encourageant (« Kité sa ye ? ») |
+| Zoom contraint aux 4 régions | ✅ | `maxBounds` [-63,-23,57,18] + `minZoom: 4` (`regions.ts`) + 4 boutons « saut de région » avec `aria-label` groupe |
+| Photos | ✅ | `loading="lazy" decoding="async"` partout (`PhotoPanel`, `explorer`, `WikiFiche`) ; `alt` descriptif du corpus ; crédit affiché sous chaque photo |
+
+---
+
+## 5. Performance 4G (mesures build + estimation)
+
+Pas de Lighthouse disponible dans l'environnement → mesures réelles des artefacts + estimation argumentée.
+
+### Poids mesuré (sur fil, gzip — les `.gz` sont pré-générés dans le build)
+
+| Écran | Détail | Poids |
+|---|---|---|
+| **Premier écran `/`** | HTML 5,6 KB + JS initial 38,7 KB gz + CSS 1,8 KB gz | **≈ 43 KB** |
+| `/jeu/*` (supplément) | code page + GameMap | +12,9 KB gz |
+| MapLibre (lazy, uniquement écrans carte) | JS 277,8 KB gz + CSS 9,8 KB gz | 287,6 KB gz |
+| Photos | Wikimedia `?width=1200`, lazy | ~150-400 KB/photo |
+
+### Estimation 4G caribéen (≈ 10 Mbps, RTT 150 ms ; et slow 4G 1,6 Mbps)
+
+- **Premier écran < 3 s : ✅ large.** ~43 KB → < 0,5 s de transfert même en slow 4G ; SSR → `<h1>` et grille des régions visibles avant hydratation ; police système (aucune webfont) ; zéro requête tierce.
+- Écran de jeu : +300 KB gz (MapLibre) ≈ 1,5-2 s en slow 4G, chargé **après** l'affichage de la photo (lazy) — le joueur peut déjà observer la photo.
+- PWA : app shell pré-caché par le service worker → 2e visite quasi instantanée, photos en stale-while-revalidate.
+
+---
+
+## 6. Checklist d'audit OKI (spec §Agent Intégration & QA)
+
+- [x] **Une seule action primaire par écran** — ✅ (⚠️ réserve Cas B, voir §4)
+- [x] **Mobile : bouton Valider en zone du pouce, carte utilisable au doigt** — ✅ (sticky bottom, marqueur draggable, boutons zoom +/- visibles)
+- [x] **Performance : premier écran < 3 s, MapLibre lazy-loadé** — ✅ (~43 KB gz initial, chunk MapLibre dynamique)
+- [x] **Éthique : pas de mécanique dopaminergique, score non punitif** — ✅
+- [x] **Éducation : les deux cas (Wiki OK / Wiki manquant) fonctionnent et sont distincts visuellement** — ✅ (tests §2.3/§2.4, panneaux `.cas-a` vert / `.cas-b` sable-orangé)
+- [x] **Bilinguisme FR/créole présent (y compris message de lacune)** — ✅ (77/77 clés)
+- [x] **PWA installable** — ✅ avec réserve : manifest + SW + icônes SVG `any`/`maskable` valides, **mais aucun PNG 192/512** — Chrome desktop peut refuser l'invite d'installation sans PNG (⚠️).
+
+Intégration MapLibre + API Lieux + API Wikipedia : ✅. Partie complète jouée : ✅ (§2.2).
+
+---
+
+## 7. Bugs corrigés pendant l'audit
+
+1. **Libellés des boutons zoom MapLibre en anglais** — Les clés i18n `carte.zoomIn`/`zoomOut` existaient mais n'étaient jamais utilisées : le `NavigationControl` natif affichait les tooltips/aria-labels anglais « Zoom in / Zoom out » sur une UI FR/créole (a11y lecteur d'écran).
+   - **Correctif** : `app/src/lib/components/GameMap.svelte` — option `locale` ajoutée au constructeur `new mod.Map({…})` avec `'NavigationControl.ZoomIn': t().carte.zoomIn` et `'NavigationControl.ZoomOut': t().carte.zoomOut`.
+   - **Vérifié** : `npm run check` 0 erreur, rebuild OK, chaîne présente dans le chunk GameMap reconstruit, serveur relancé et endpoints re-testés (200).
+
+Aucun bug structurel trouvé.
+
+---
+
+## 8. Points d'amélioration restants (non bloquants)
+
+1. ⚠️ **Icônes PWA** : ajouter des PNG 192×192 et 512×512 (certains navigateurs n'acceptent pas le SVG seul pour l'invite d'installation).
+2. ⚠️ **Contraste du corail** `--oki-corail` #e4572e sur texte blanc ≈ **3,7:1** : conforme AA pour texte large et composants d'interface, juste sous les 4,5:1 du texte courant. Envisager `--oki-corail-fonce` au repos si on veut du AA strict.
+3. ⚠️ **Bonus temps basé sur `timeMs` fourni par le client** (`/api/guess`) : un client modifié peut s'accorder +20 %. Sans leaderboard ni enjeu, c'est acceptable — à documenter si un mode compétitif arrive un jour.
+4. ⚠️ **Deux accents forts sur l'écran résultat Cas B** (corail « Lieu suivant » + orange « Kontribyé ») : Peak-End assumé, mais à valider contre la règle « une seule action primaire ».
+5. **Clés i18n inutilisées** : `resultat.bravo`, `resultat.score`, `micro.pwenBlinde`, `defi.manche` — cosmétique, à nettoyer ou brancher.
+6. **Pas de tests automatisés** dans le dépôt (ni unitaires ni e2e) — les vérifications de cet audit sont manuelles ; un `vitest` sur `scoreGuess`/`sanitizeRound` + un test e2e du Cas B sécuriseraient les régressions.
+7. **Limite connue** (déjà documentée dans `architecture.md`) : l'enveloppe `maxBounds` rectangulaire inclut l'Atlantique tropical et le Brésil — inoffensif.
+
+---
+
+## Verdict
+
+**✅ Conforme à la spec.** Build propre, anti-triche étanche sur 15 tirages, scoring recalculé serveur et vérifié au point près, Cas A et Cas B fonctionnels (y compris le fallback 404 → Cas B), i18n FR/créole complet, doctrine OKI respectée (calm tech, zone pouce, reduced-motion, zéro dark pattern). 1 bug mineur corrigé (locale des contrôles zoom). 7 points d'amélioration non bloquants listés ci-dessus.
+
+---
+
+## Addendum post-audit (vérification finale orchestrateur)
+
+- **Fix anti-spoiler** : le crédit photo (`photo.credit`, souvent explicite sur le lieu) était affiché pendant la phase de devinette. Désormais masqué pendant la devinette (`PhotoPanel`, prop `revealed`) et affiché après validation dans `ResultPanel` — attribution CC conservée, indice supprimé. Re-vérifié : `npm run check` 0 erreur, `npm run build` OK.