🧑‍💻 Écrire une page HTML5 dans Celestory

Le bloc HTML5 est la porte de sortie de Celestory. Vous y collez une page web complète — HTML, CSS, JavaScript — et Celestory l'affiche plein écran à ce moment du parcours. Un mini-jeu, un formulaire sur mesure, une simulation, un canevas dessiné à la main : tout ce pour quoi il n'existe pas de bloc.

Mais une page isolée ne sert à rien. Ce qui compte, c'est le contrat : comment la page reçoit des valeurs du graphe, et comment elle lui en rend. Il tient en trois éléments. 🔌

🔺 Le bloc HTML5 demande un abonnement Business.

📝 Où l'on écrit, et quand c'est enregistré

Ouvrez le bloc HTML5 (double-clic). Son entrée contenu accueille un éditeur de code complet — le moteur de Visual Studio Code — avec coloration syntaxique et repli de blocs.

🔺 Votre code n'est transmis au graphe qu'à la perte du focus. Tant que le curseur clignote dans l'éditeur, Celestory ne voit rien. Cliquez en dehors de l'éditeur, ou fermez la fenêtre d'édition du bloc : c'est à cet instant que le code est enregistré et que les points d'entrée et de sortie apparaissent ou disparaissent sur le bloc.

C'est la source de confusion numéro un. Si vous venez de coller un {{prenom}} et qu'aucune entrée n'apparaît, vous n'avez simplement pas encore quitté l'éditeur. 🙂

La page doit être autonome : rien n'est empaqueté à côté d'elle, aucun fichier voisin n'est servi. Tout ce dont elle a besoin tient dans le bloc, ou se charge depuis une URL publique.

📥 Recevoir des valeurs : les doubles accolades

Écrivez {{nom}} n'importe où dans le code, et Celestory crée une entrée de ce nom sur le bloc.

<h1>Bonjour {{prenom}} !</h1>
<p>Vous en êtes à {{score}} points.</p>

Deux entrées apparaissent : prenom et score. Branchez-y une variable, la sortie d'un autre bloc, ou saisissez une valeur en dur. Elles acceptent du Texte, un Nombre ou un Booléen.

🔺 Seules les lettres non accentuées, les chiffres et le tiret bas sont acceptés : a-z, A-Z, 0-9, _. {{Prénom}}, {{mon-score}} et {{ prenom }} ne sont pas détectés. Aucune entrée n'est créée, aucune erreur n'apparaît, et le repère s'affiche tel quel à l'écran. La casse compte. Ce sont exactement les règles de l'article Les doubles accolades.

🔺 Le remplacement est purement textuel, effectué dans le code source avant que la page ne s'exécute. En JavaScript, un texte doit donc porter ses guillemets :

<script>
  const points = {{score}};        // ✅ un nombre, tel quel
  const joueur = "{{prenom}}";     // ✅ un texte, entre guillemets
  const casse  = {{prenom}};       // ❌ erreur de syntaxe à l'exécution
</script>

🔺 Une entrée non branchée est remplacée par du vide. const points = ; : votre page ne démarre pas, et rien ne vous prévient.

📤 Renvoyer des valeurs : déclarer, puis poster

C'est le point le moins évident, et il se fait en deux temps.

1. Déclarer ce que la page rendra

Écrivez ce commentaire n'importe où dans la page :

<!-- celestory-outputs: score, verdict -->

Chaque nom listé devient une sortie sur le bloc, que vous pouvez lire, tester ou brancher comme n'importe quelle autre. Séparez-les par des virgules ou des espaces, sur une ligne ou sur plusieurs. Ces sorties acceptent du Texte, un Nombre ou un Booléen.

🔺 Les mêmes règles de nommage s'appliquent : lettres non accentuées, chiffres, tiret bas. Rien d'autre.

2. Poster la valeur pendant que la page tourne

<script>
  parent.document.dispatchEvent(
    new CustomEvent('CelestoryOutput', {detail: {key: 'score', value: 42}})
  );
</script>

Le key désigne la sortie, le value la valeur. Postez autant de fois que vous voulez : la dernière valeur postée pour une clé donnée est celle que le graphe lira.

Il existe une seconde voie, plus ancienne mais toujours active : si la clé est écrite littéralement dans l'appel, comme ci-dessus, Celestory la repère à la lecture du code et crée la sortie, même sans commentaire de déclaration.

🔺 Mais dès que la clé est calculée — key: nomDeLaSortie — plus rien n'est détecté. Déclarez toujours vos sorties dans le commentaire. C'est la seule méthode qui ne dépende pas de la façon dont vous écrivez votre code.

🏁 Rendre la main au graphe : CelestoryEnd

Tant que la page est à l'écran, le parcours est arrêté. Pour le relancer, la page envoie :

<script>
  parent.document.dispatchEvent(new CustomEvent('CelestoryEnd'));
</script>

Le flux repart alors par la sortie out du bloc. L'évènement est idempotent : envoyez-le dix fois, le graphe n'avance qu'une seule fois.

Postez vos valeurs avant de terminer. L'ordre compte : CelestoryEnd fait avancer le flux, et les blocs suivants lisent ce qui a été posté jusque-là.

🔺 Une page qui n'envoie jamais CelestoryEnd peut bloquer l'expérience. Il vous reste le bouton de fermeture, mais il n'apparaît que si la sortie out est branchée et si l'entrée bouton fermer vaut vrai. Sans l'un ni l'autre, le joueur est coincé.

⚠️ Le piège : les écouteurs sont sur le document

C'est confirmé dans le code, et c'est la cause d'échec la plus fréquente : Celestory écoute sur des document, jamais sur une window.

Votre page tourne dans un cadre isolé. Deux écoutes sont posées : une sur le document de l'application qui l'héberge, une sur le document de la page elle-même.

<script>
  // ✅ toujours correct — le document de l'application hôte
  parent.document.dispatchEvent(new CustomEvent('CelestoryEnd'));

  // ✅ correct aussi — le document de votre propre page
  document.dispatchEvent(new CustomEvent('CelestoryEnd'));

  // ❌ n'arrive nulle part, en silence
  window.dispatchEvent(new CustomEvent('CelestoryEnd'));
  parent.dispatchEvent(new CustomEvent('CelestoryEnd'));
  dispatchEvent(new CustomEvent('CelestoryEnd'));
</script>

🔺 Envoyer l'évènement à une window ne déclenche rien du tout, quoi que fasse le reste de votre page. Aucune erreur dans la console, aucun message : la page reste simplement figée.

🔺 Le poster sur un élément (un bouton, une div) ne marche pas non plus, sauf à le faire remonter explicitement — et un CustomEvent ne remonte pas par défaut. Prenez l'habitude de parent.document, il fonctionne dans tous les cas.

🧩 Une page complète, de bout en bout

<!-- celestory-outputs: reponse, correct -->
<!DOCTYPE html>
<html>
  <body style="font-family: sans-serif; text-align: center; padding: 40px">
    <h1>Bonjour {{prenom}} !</h1>
    <p>Combien font 7 × 6 ?</p>
    <input id="saisie" type="number" />
    <button id="valider">Valider</button>

    <script>
      document.getElementById('valider').addEventListener('click', () => {
        const valeur = Number(document.getElementById('saisie').value);

        parent.document.dispatchEvent(new CustomEvent('CelestoryOutput',
          {detail: {key: 'reponse', value: valeur}}));
        parent.document.dispatchEvent(new CustomEvent('CelestoryOutput',
          {detail: {key: 'correct', value: valeur === 42}}));

        parent.document.dispatchEvent(new CustomEvent('CelestoryEnd'));
      });
    </script>
  </body>
</html>

Sur le bloc, après avoir quitté l'éditeur, vous obtenez :

• une entrée prenom à brancher ;
• deux sorties reponse (un nombre) et correct (un booléen) ;
• la sortie de flux out, à brancher sur la suite — un bloc Condition sur correct, par exemple.

Le type de la sortie suit la valeur postée : un nombre arrive en Nombre, un booléen en Booléen, tout le reste en Texte.

🧷 Le reste du bloc

L'entrée bouton fermer affiche une croix en haut à droite de la page. Elle est active par défaut, et ne sert que de filet de sécurité : cliquer dessus fait exactement ce que ferait CelestoryEnd, sans qu'aucune valeur n'ait été postée. Mettez-la à faux pour un mini-jeu dont on ne doit pas pouvoir sortir — à condition que votre page sache se terminer toute seule.

✅ La liste de contrôle

Avant de tester, vérifiez ces cinq points :

1. Vous avez quitté l'éditeur : les points sont bien apparus sur le bloc.
2. Chaque {{nom}} est sans accent et branché.
3. Vos sorties sont déclarées dans <!-- celestory-outputs: … -->.
4. Tous vos évènements partent sur parent.document.
5. Votre page envoie CelestoryEnd — après avoir posté ses valeurs.

→ Prochaine étape : partez de la page complète ci-dessus, collez-la dans un bloc HTML5, quittez l'éditeur, branchez prenom et posez un bloc Condition sur la sortie correct. Vous tenez le schéma de tous les usages avancés de Celestory.

Mis à jour le : 21/09/2026