Hybélior
Site web interactif dédié à l'univers d'Hybélior : carte du monde, chronologie, lore et romans.
L'Atrium
Le savoir du site porte un nom : l'Atrium. C'est le graphe canonique
(data/kg-base.json, moteur lib/kg-core.js, portail monde.html), et c'est
la source de vérité du monde — la salle où toutes les sources tombent et se
gardent. Il sait tout et montre tout : aucune restriction, aucun mystère
caché. Quand un texte le contredit, c'est lui qui tranche ; si c'est lui qui a
tort, on le corrige là et le reste suit.
Les livres gardent leurs mystères ; l'Atrium, lui, sait. Les entités de type
question ne sont jamais résolues dans les livres : aucun narrateur
n'énonce la réponse. Pour les treize qui portent data.protege, l'Atrium
connaît pourtant la vérité d'auteur (data.verite, avec ses couches et ses
indices ; statut: proposée attend la validation de l'auteur). Le champ
disclosure ne gouverne que ce qu'un narrateur a le droit d'énoncer, jamais ce
que le site affiche.
Échelle, carte et vérifications
- Échelle : le monde fait 1 000 km de bord de mer à bord de mer, soit
1 u de carte ≈ 0,955 km (1 lieue ≈ 4,19 u).
- Carte vivante : les côtes de
data/monde-contours.json sont refaites
depuis le tracé de l'auteur (continents-trace.svg) et validées ; les
surfaces de pays ne le sont pas encore. Un rattachement (situe-dans,
capitale-de) vient des fiches, jamais d'un point-dans-polygone.
- Raccord livres et Atrium :
node scripts/verifier-raccord.js --detail
après toute retouche d'un livre.
- Trajets des personnages :
node scripts/tracer-routes.js, puis
node scripts/verifier-trajets.js --ecrire, puis npm run kg:db.
- Détail et conventions de travail :
CLAUDE.md.
Architecture
Le site est une Single Page Application (SPA) avec routage par hash (#accueil, #lore, #implementation, #carte, #frise). Les pages sont chargées dynamiquement dans index.html depuis le dossier pages/.
Structure du projet
index.html – Point d'entrée SPA
server.js – Serveur Node.js de développement (port 3001)
vercel.json – Configuration de déploiement Vercel
js/
router.js – Routeur SPA hash-based
map.js – Carte interactive (OpenSeadragon, frontières, timeline)
lore-reader.js – Lecteur modal de contenu lore (Markdown)
subtabs.js – Navigation par sous-onglets
css/
style.css – Styles principaux
map_adapted.css – Styles spécifiques à la carte
pages/ – Pages HTML chargées dynamiquement
accueil.html – Page d'accueil
carte.html – Carte interactive
frise.html – Frise chronologique
lore.html – Hub lore (8 catégories thématiques)
nation.html, continent.html, histoire.html, religion.html – Fiches lore (routes propres)
api/ – Routes serverless Vercel
auth.js – Authentification éditeur
borders.js – CRUD frontières (Turso DB)
overrides.js – Surcharges lore/entités
highlights.js – Surlignages éditeur
timeline.js – Données de la timeline
scripts/ – Outils de build : génération de Docs/_manifest.json
(gen-doc-manifest.js) et Docs/_search-index.json
(gen-search-index.js), validation JSON
data/ – Données de référence (timeline, noms historiques)
Docs/ – MIROIR du contenu GDD + Lore (auto-généré, voir ci-dessous)
HybeliorFull/ – Tuiles Deep Zoom pour OpenSeadragon (hors git)
fonts/ – Police personnalisée (Copperplate Gothic)
Fonctionnalités principales
Carte interactive
- Rendu multi-couches basé sur OpenSeadragon avec tuiles Deep Zoom
- Affichage adaptatif au zoom : continents → pays → régions → villes
- Système de frontières avec dessin, surbrillance et couleurs par pays
- Navigation temporelle avec slider par année et transitions entre ères
- Mode plein écran natif
Frise chronologique
- Couvre ~10 200 ans d'histoire avec 63 civilisations disparues
- Slider par année avec résolution dynamique des noms par époque
- Lignées de civilisations et régimes politiques
Lore
- Lecteur modal avec support Markdown (marked.js)
- Sous-sections : chronologie, cosmogonie, géographie, religions, histoires
- Préparation centralisée du contenu via
js/lore-content.js :
- retrait des sections éditoriales internes (
## Cadre interne — Patterns,
## Données canoniques) qui ne doivent jamais être servies au lecteur ;
- sanitization du HTML rendu via DOMPurify.
Implémentation
- Documentation du système de jeu, en sous-onglets Markdown pilotés par
NavConfig.subtabs.implementation
Source du contenu Lore
⚠️ Important : Docs/Lore/ est un miroir auto-généré.
La source de vérité du lore est dans H:/HybeliorWorld_Project/Documentation/Lore/.
Avant chaque déploiement Vercel, lancer le script de synchronisation :
H:\HybeliorWorld_Project\Documentation\sync-docs.ps1
Le miroir local est exclu du git. Voir Documentation/README.md pour plus de détails.
Lancer en local
node server.js
Le serveur démarre sur http://localhost:3001. Il fournit un fallback local (local-db.json) pour les API qui utilisent Turso en production.
Alternativement, ouvrir index.html directement dans un navigateur fonctionne pour la carte et la navigation, mais les fonctionnalités nécessitant les API (frontières, timeline DB) ne seront pas disponibles.
Déploiement
Le site est déployé sur Vercel avec des fonctions serverless pour les routes /api/*. La base de données Turso stocke les frontières et les données de timeline.
Qualité & CI
- Lint :
npm run lint (ESLint, config plate eslint.config.js). Les règles
« attrape-bug » sont en avertissement le temps de nettoyer la base existante.
- Format :
npm run format / npm run format:check (Prettier).
- CI (
.github/workflows/ci.yml) à chaque push/PR :
- vérification de syntaxe Node sur le JS (
node --check),
- validation de tous les JSON suivis (
scripts/validate-json.js),
- ESLint (informatif).
Dépendances
- OpenSeadragon – Zoom et navigation sur la carte
- marked.js – Rendu Markdown pour le contenu lore
- DOMPurify – Sanitization du HTML rendu
- Turso (libSQL) – Base de données en production
