Architecture Playlab42#

Playlab42 possède deux architectures complémentaires : l'application statique utilisée dans le navigateur et l'usine logicielle qui fabrique, vérifie et publie ses fichiers. Elles ne nécessitent ni backend applicatif ni WebSocket.

Vue d'ensemble#

À la construction
  Sources + manifests + specs
    → TypeScript / runtime / catalogues / guides
    → site/ → archive testée → GitHub Pages

Dans le navigateur
  Portail : Parcours | Outils | Jeux | Liens
    ├─ recherche, filtres, reprise, réglages, lien Guides
    ├─ outils / jeux dans une iframe
    ├─ viewer de parcours / slides
    └─ localStorage : préférences, scores et progression

Le serveur de développement ne fait que servir des fichiers. Les moteurs compatibles Node sont testés dans Node ; cela ne signifie pas qu'un serveur de jeu est déployé. Les données ne sont pas synchronisées entre appareils.

Les composants#

Portail et contenus#

Le portail lit data/catalogue.json, data/parcours.json et data/bookmarks.json. Les manifests décrivent les entrées ; le catalogue est reconstruit avant utilisation dans un checkout neuf. Les pages de guides sont accessibles par le lien Guides, sans iframe ni backend.

Une iframe sépare les documents et leurs styles. Ce n'est pas une promesse d'isolation de sécurité complète : le comportement effectif dépend du sandbox, de l'origine et des validations de messages. Utiliser le SDK et les conventions existants plutôt qu'inventer un protocole. Le lecteur permet les références dans un nouvel onglet ; quitter la slide pour le guide complet dans la fenêtre principale exige une activation utilisateur, pas une navigation automatique.

Outils#

Un outil peut être tools/<id>.html avec son JSON historique, ou un dossier :

tools/<id>/
  index.html
  tool.json
  src/ ou modules locaux (si nécessaire)
  dist/ (si TypeScript, généré)

HTML/CSS/JavaScript natifs restent la base. Les imports ESM et chargements de ressources exigent un service HTTP statique. file:// n'est utilisable que pour les versions simples qui n'ont pas ces besoins : ce n'est pas une garantie générale. Le kit fournit un outil directement utilisable.

Jeux : moteur, client, bot#

• Moteur : règles pures, sans DOM, réseau ou système de fichiers. État sérialisable, actions validées et résultat déterministe.
• Client : interface, événements et affichage. GameKit assure les interactions prévues avec le portail : disponibilité, pause, préférences et scores.
• Bot : joueur automatique recevant la vue du joueur, les actions légales et le générateur aléatoire prévu. Ce n'est pas un agent de code.

Même seed et mêmes actions donnent la même partie. Les tests portent sur les contrats observables : replay, immutabilité, actions illégales et fin de partie. Les signatures réelles sont définies dans les types du moteur (fichier source), pas dans un exemple simplifié de cette page.

Parcours et guides#

epic.json ordonne les slides et sections ; chaque slide garde son identifiant et son slide.json. Le build valide et agrège les manifests, convertit les slides Markdown si présentes et produit le catalogue.

Les slides réemploient slide-base.css et slide-utils.js pour thème, tableaux et footer. La navigation du viewer conserve URL et progression. Les guides sont rendus depuis les Markdown de docs/ dans docs/site/ : ne jamais modifier directement ce dossier généré.

Données et dépendances#

Préférences, scores et progression restent dans le navigateur. Le guide des données locales décrit validation et sauvegarde/restauration.

Les principales bibliothèques runtime sont épinglées, vérifiées puis copiées depuis npm dans assets/vendor/. Certains contenus gardent des dépendances externes : le projet ne promet pas que tous les outils fonctionneront hors réseau. Voir les bibliothèques runtime et les limites du socle navigateur.

L'usine logicielle#

Demande
  → OpenSpec : proposal / specs / design / tasks
  → skills : contexte et conventions, pas permissions supplémentaires
  → kit : gabarits, composants et exemples
  → implémentation + preuves locales Docker
  → PR + CI + revue humaine
  → main : CI complète → archive testée → Pages → contrôle HTTP
  → décision explicite de synchroniser / archiver après livraison

AGENTS.md est la source commune. Les skills vivent dans .github/skills/ ; .claude/skills est un lien vers cette source, pas une seconde copie ni une installation automatique de commandes slash OPSX.

La publication réutilise les validations et le même artefact testé. Elle ne crée pas de revue, merge ou release, et ne remplace pas les règles GitHub externes. Le guide de l'usine logicielle explique les étapes, les preuves attendues et les points restant à améliorer.

Stack et commandes#

make info
make npm CMD="run build:local"  # préparation complète sans collecte OG
make serve                    # URL externe affichée par make info
make typecheck
make test
make test-e2e

make build construit l'image Docker, pas les catalogues. Le port externe du worktree est calculé dans la plage 5200–5299 ; 5242 est le port interne. Les versions, signatures et commandes détaillées restent dans leurs sources canoniques, sans copie concurrente dans ce guide.

Voir aussi#

• Usine logicielle
• Workflow OpenSpec
• Skills
• Contribuer
• Kit de contribution
• Déploiement
• Moteur, client et bot

Actualisé le 3 octobre 2026.