From ee3d39fa3d4aa2983f343ea83dc842f147015862 Mon Sep 17 00:00:00 2001
From: FredZinelli <145555278+FredZinelli@users.noreply.github.com>
Date: Tue, 25 Feb 2025 19:51:12 +0100
Subject: [PATCH 01/20] Modification des docstrings de certains contrats

---
 capytale/contracts/src/mode.ts                |  4 ++-
 capytale/contracts/src/reload.ts              | 16 +++++++++---
 capytale/contracts/src/simple-content-eval.ts | 19 +++++++++++---
 capytale/contracts/src/simple-content.ts      | 25 ++++++++++++++-----
 capytale/contracts/src/theme.ts               |  1 +
 capytale/contracts/src/workflow.ts            |  1 +
 6 files changed, 52 insertions(+), 14 deletions(-)

diff --git a/capytale/contracts/src/mode.ts b/capytale/contracts/src/mode.ts
index f3fedc8..3bc7a27 100644
--- a/capytale/contracts/src/mode.ts
+++ b/capytale/contracts/src/mode.ts
@@ -28,10 +28,12 @@ export type ModeV1 = {
 
     /**
      * L'interface qui expose l'*Application* au *MetaPlayer*.
+     * Les méthodes non implantées sont ignorées.
      */
     application: {
         /**
-         * Le *MetaPlayer* appelle cette méthode pour indiquer le mode à l'*Application*.
+         * Le *MetaPlayer* appelle cette méthode pour indiquer le mode à l'*Application*,
+         * après avoir appelé la méthode `loadContent`.
          * Ne devrait être appelé qu'une seule fois.
          * 
          * @param mode le mode à appliquer. 
diff --git a/capytale/contracts/src/reload.ts b/capytale/contracts/src/reload.ts
index af36971..2a17cb2 100644
--- a/capytale/contracts/src/reload.ts
+++ b/capytale/contracts/src/reload.ts
@@ -13,13 +13,20 @@ export type ReloadV1 = {
      */
     metaplayer: {
         /**
-         * L'*Application* peut appeler cette méthode pour demander un rechargement.
-         * L'iFrame est détruite puis recréée.
+         * L'*Application* peut appeler cette méthode pour demander un rechargement avec l'url
+         * passée en argument.
+         * 
+         * - L'iFrame est détruite puis recréée avec la nouvelle adresse.
+         * - Le *MetaPlayer* récupère un état (`state`) contenant toutes les données qui devront
+         *   être données ensuite à la nouvelle instance de l'*Application* (à minima, toutes les 
+         *   données liée à l'activité en cours).
+         * - Après rechargement, le *MetaPlayer* n'appellera _PAS_ la méthode `loadContent` de 
+         *   du contrat de l'*Application*, mais la méthode `reloaded` du présent contrat.
          * 
          * @param url l'URL à charger dans l'iFrame.
          *            Si null, l'URL actuelle est rechargée.
          * 
-         * @param state un état éventuel à transmettre à l'application après le rechargement.
+         * @param state un état à transmettre à l'application après le rechargement.
          * 
          */
         reload(url?: string | null, state?: any): void;
@@ -27,11 +34,14 @@ export type ReloadV1 = {
 
     /**
      * L'interface qui expose l'*Application* au *MetaPlayer*.
+     * Les méthodes non implantées sont ignorées.
      */
     application: {
         /**
          * Le *MetaPlayer* appelle cette méthode pour indiquer à l'*Application* qu'un
          * rechargement a eu lieu.
+         * Cette méthode est appelée en lieu et place de `loadContent`, suite à une
+         * demande de rechargement.
          * 
          * @param state l'état que l'application a transmis lors de l'appel à `reload`.
          */
diff --git a/capytale/contracts/src/simple-content-eval.ts b/capytale/contracts/src/simple-content-eval.ts
index a3e22a3..8292213 100644
--- a/capytale/contracts/src/simple-content-eval.ts
+++ b/capytale/contracts/src/simple-content-eval.ts
@@ -42,12 +42,15 @@ export type SimpleContentEvalV1<T> = {
 
     /**
      * L'interface qui expose l'*Application* au *MetaPlayer*.
+     * Les méthodes non implantées sont ignorées.
      */
     application: {
         /**
-         * Le *MetaPlayer* appelle cette méthode pour envoyer les données à l'*Application*.
+         * Le *MetaPlayer* appelle cette méthode pour envoyer les données à l'*Application*, lors 
+         * du chargement de la page, pour transmettre les données concernant l'activité.
          * 
-         * Si `content` est `null`, l'*Application* doit réinitialiser son contenu à la valeur par défaut initiale.
+         * Si `content` est `null`, l'*Application* doit réinitialiser son contenu à la valeur par 
+         * défaut initiale.
          * Si l'*Application* n'est pas en mesure de charger le contenu, elle doit lever une exeption.
          * 
          * @param content le contenu de l'activité
@@ -55,9 +58,17 @@ export type SimpleContentEvalV1<T> = {
         loadContent(content: T | null): void;
 
         /**
-         * Le *MetaPlayer* appelle cette méthode pour récupérer les données de l'*Application* dans le mode create.
+         * Le *MetaPlayer* appelle cette méthode pour récupérer les données de l'*Application*, 
+         * lorsque l'utilisateur effectue une action demandant d'enrgistrer des données sur 
+         * Capyale (typiquement, cliquer sur le bouton Enregsitrer dans le bandeau supérieur).
          * 
-         * L'*Application* peut retourner `null` si le contenu correspond à la valeur par défaut initiale.
+         * L'*Application* peut retourner `null` si le contenu correspond à la valeur par défaut
+         * initiale.
+         * 
+         * Contrat :
+         * Lorsque cette méthode est appelée, l'*Application* doit empêcher l'utilisateur de 
+         * modifier le contenu de la page, jusqu'à ce qu'elle reçoive la notification de fin 
+         * de sauvegarde, via l'appel à `contentSaved()`.
          * 
          * @returns le contenu de l'activité
          */
diff --git a/capytale/contracts/src/simple-content.ts b/capytale/contracts/src/simple-content.ts
index b9461e1..a1631f7 100644
--- a/capytale/contracts/src/simple-content.ts
+++ b/capytale/contracts/src/simple-content.ts
@@ -18,19 +18,23 @@ export type SimpleContentV1<T> = {
      */
     metaplayer: {
         /**
-         * L'*Application* doit appeler cette méthode pour indiquer au *MetaPlayer* que le contenu a été modifié par l'utilisateur.
+         * L'*Application* doit appeler cette méthode pour indiquer au *MetaPlayer* que le contenu 
+         * a été modifié par l'utilisateur.
          */
         contentChanged(): void;
     };
 
     /**
      * L'interface qui expose l'*Application* au *MetaPlayer*.
+     * Les méthodes non implantées sont ignorées.
      */
     application: {
         /**
-         * Le *MetaPlayer* appelle cette méthode pour envoyer les données à l'*Application*.
+         * Le *MetaPlayer* appelle cette méthode pour envoyer les données à l'*Application*, lors 
+         * du chargement de la page, pour transmettre les données concernant l'activité.
          * 
-         * Si `content` est `null`, l'*Application* doit réinitialiser son contenu à la valeur par défaut initiale.
+         * Si `content` est `null`, l'*Application* doit réinitialiser son contenu à la valeur par 
+         * défaut initiale.
          * Si l'*Application* n'est pas en mesure de charger le contenu, elle doit lever une exeption.
          * 
          * @param content le contenu de l'activité
@@ -38,16 +42,25 @@ export type SimpleContentV1<T> = {
         loadContent(content: T | null): void;
 
         /**
-         * Le *MetaPlayer* appelle cette méthode pour récupérer les données de l'*Application*.
+         * Le *MetaPlayer* appelle cette méthode pour récupérer les données de l'*Application*, 
+         * lorsque l'utilisateur effectue une action demandant d'enrgistrer des données sur 
+         * Capyale (typiquement, cliquer sur le bouton Enregsitrer dans le bandeau supérieur).
          * 
-         * L'*Application* peut retourner `null` si le contenu correspond à la valeur par défaut initiale.
+         * L'*Application* peut retourner `null` si le contenu correspond à la valeur par défaut
+         * initiale.
+         * 
+         * Contrat :
+         * Lorsque cette méthode est appelée, l'*Application* doit empêcher l'utilisateur de 
+         * modifier le contenu de la page, jusqu'à ce qu'elle reçoive la notification de fin 
+         * de sauvegarde, via l'appel à `contentSaved()`.
          * 
          * @returns le contenu de l'activité
          */
         getContent(): T | null;
 
         /**
-         * Le *MetaPlayer* appelle cette méthode pour indiquer à l'*Application* que le contenu a été sauvegardé.
+         * Le *MetaPlayer* appelle cette méthode pour indiquer à l'*Application* que le contenu 
+         * a été sauvegardé.
          */
         contentSaved(): void;
     };
diff --git a/capytale/contracts/src/theme.ts b/capytale/contracts/src/theme.ts
index 86cc35f..aab6415 100644
--- a/capytale/contracts/src/theme.ts
+++ b/capytale/contracts/src/theme.ts
@@ -23,6 +23,7 @@ export type ThemeV1 = {
 
     /**
      * L'interface qui expose l'*Application* au *MetaPlayer*.
+     * Les méthodes non implantées sont ignorées.
      */
     application: {
         /**
diff --git a/capytale/contracts/src/workflow.ts b/capytale/contracts/src/workflow.ts
index 454295e..e309592 100644
--- a/capytale/contracts/src/workflow.ts
+++ b/capytale/contracts/src/workflow.ts
@@ -24,6 +24,7 @@ export type WorkflowV1 = {
 
     /**
      * L'interface qui expose l'*Application* au *MetaPlayer*.
+     * Les méthodes non implantées sont ignorées.
      */
     application: {
         /**

From 3425ab6e83705d69f03039cefe17506c744fd56f Mon Sep 17 00:00:00 2001
From: FredZinelli <145555278+FredZinelli@users.noreply.github.com>
Date: Tue, 25 Feb 2025 20:11:15 +0100
Subject: [PATCH 02/20] fixes + more

---
 capytale/contracts/src/simple-content-eval.ts | 11 ++++++-----
 capytale/contracts/src/simple-content.ts      |  9 +++++----
 2 files changed, 11 insertions(+), 9 deletions(-)

diff --git a/capytale/contracts/src/simple-content-eval.ts b/capytale/contracts/src/simple-content-eval.ts
index 8292213..db74f4f 100644
--- a/capytale/contracts/src/simple-content-eval.ts
+++ b/capytale/contracts/src/simple-content-eval.ts
@@ -35,7 +35,9 @@ export type SimpleContentEvalV1<T> = {
      */
     metaplayer: {
         /**
-         * L'*Application* doit appeler cette méthode pour indiquer au *MetaPlayer* que le contenu a été modifié par l'utilisateur.
+         * L'*Application* doit appeler cette méthode pour indiquer au *MetaPlayer* que le contenu 
+         * a été modifié par l'utilisateur (permettant par exemple d'activer le bouton de sauvegarde 
+         * dans le bandeau supérieur de Capytale).
          */
         contentChanged(): void;
     };
@@ -46,8 +48,8 @@ export type SimpleContentEvalV1<T> = {
      */
     application: {
         /**
-         * Le *MetaPlayer* appelle cette méthode pour envoyer les données à l'*Application*, lors 
-         * du chargement de la page, pour transmettre les données concernant l'activité.
+         * Le *MetaPlayer* appelle cette méthode après la souscription au contrat, pour transmettre
+         * les données de l'activité à l'*Application*.
          * 
          * Si `content` est `null`, l'*Application* doit réinitialiser son contenu à la valeur par 
          * défaut initiale.
@@ -59,8 +61,7 @@ export type SimpleContentEvalV1<T> = {
 
         /**
          * Le *MetaPlayer* appelle cette méthode pour récupérer les données de l'*Application*, 
-         * lorsque l'utilisateur effectue une action demandant d'enrgistrer des données sur 
-         * Capyale (typiquement, cliquer sur le bouton Enregsitrer dans le bandeau supérieur).
+         * dans le mode create.
          * 
          * L'*Application* peut retourner `null` si le contenu correspond à la valeur par défaut
          * initiale.
diff --git a/capytale/contracts/src/simple-content.ts b/capytale/contracts/src/simple-content.ts
index a1631f7..753b3a9 100644
--- a/capytale/contracts/src/simple-content.ts
+++ b/capytale/contracts/src/simple-content.ts
@@ -19,7 +19,8 @@ export type SimpleContentV1<T> = {
     metaplayer: {
         /**
          * L'*Application* doit appeler cette méthode pour indiquer au *MetaPlayer* que le contenu 
-         * a été modifié par l'utilisateur.
+         * a été modifié par l'utilisateur (permettant par exemple d'activer le bouton de sauvegarde 
+         * dans le bandeau supérieur de Capytale).
          */
         contentChanged(): void;
     };
@@ -30,8 +31,8 @@ export type SimpleContentV1<T> = {
      */
     application: {
         /**
-         * Le *MetaPlayer* appelle cette méthode pour envoyer les données à l'*Application*, lors 
-         * du chargement de la page, pour transmettre les données concernant l'activité.
+         * Le *MetaPlayer* appelle cette méthode après la souscription au contrat, pour transmettre
+         * les données de l'activité à l'*Application*.
          * 
          * Si `content` est `null`, l'*Application* doit réinitialiser son contenu à la valeur par 
          * défaut initiale.
@@ -43,7 +44,7 @@ export type SimpleContentV1<T> = {
 
         /**
          * Le *MetaPlayer* appelle cette méthode pour récupérer les données de l'*Application*, 
-         * lorsque l'utilisateur effectue une action demandant d'enrgistrer des données sur 
+         * lorsque l'utilisateur effectue une action demandant d'enregistrer des données sur 
          * Capyale (typiquement, cliquer sur le bouton Enregsitrer dans le bandeau supérieur).
          * 
          * L'*Application* peut retourner `null` si le contenu correspond à la valeur par défaut

From 3bdd64d05a47b65936ad155af66d44d827745e5d Mon Sep 17 00:00:00 2001
From: FredZinelli <145555278+FredZinelli@users.noreply.github.com>
Date: Sun, 2 Mar 2025 18:37:03 +0100
Subject: [PATCH 03/20] Update reload.ts

---
 capytale/contracts/src/reload.ts | 1 +
 1 file changed, 1 insertion(+)

diff --git a/capytale/contracts/src/reload.ts b/capytale/contracts/src/reload.ts
index 2a17cb2..30e90d8 100644
--- a/capytale/contracts/src/reload.ts
+++ b/capytale/contracts/src/reload.ts
@@ -27,6 +27,7 @@ export type ReloadV1 = {
          *            Si null, l'URL actuelle est rechargée.
          * 
          * @param state un état à transmettre à l'application après le rechargement.
+         *        L'objet state doit être serializable avec JSON.stringify.
          * 
          */
         reload(url?: string | null, state?: any): void;

From 9ac6238ff9f0204929b4d79f8fafa2ae43106d8c Mon Sep 17 00:00:00 2001
From: FredZinelli <145555278+FredZinelli@users.noreply.github.com>
Date: Sun, 2 Mar 2025 18:51:55 +0100
Subject: [PATCH 04/20] Update reload.ts

---
 capytale/contracts/src/reload.ts | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/capytale/contracts/src/reload.ts b/capytale/contracts/src/reload.ts
index 30e90d8..21e66ff 100644
--- a/capytale/contracts/src/reload.ts
+++ b/capytale/contracts/src/reload.ts
@@ -25,6 +25,8 @@ export type ReloadV1 = {
          * 
          * @param url l'URL à charger dans l'iFrame.
          *            Si null, l'URL actuelle est rechargée.
+         *            ATTENTION: si la logique de l'*Application* repose sur des paramètres passés 
+         *            via l'URL, ne pas oublier de les rajouter.
          * 
          * @param state un état à transmettre à l'application après le rechargement.
          *        L'objet state doit être serializable avec JSON.stringify.

From 92b545f63835d2fd6825371fe7be4248520694c6 Mon Sep 17 00:00:00 2001
From: FredZinelli <145555278+FredZinelli@users.noreply.github.com>
Date: Wed, 12 Mar 2025 17:33:45 +0100
Subject: [PATCH 05/20] Apply suggestions from code review

cleanup
---
 capytale/contracts/src/reload.ts              | 2 +-
 capytale/contracts/src/simple-content-eval.ts | 4 ----
 capytale/contracts/src/simple-content.ts      | 4 ----
 capytale/contracts/src/theme.ts               | 1 -
 capytale/contracts/src/workflow.ts            | 1 -
 5 files changed, 1 insertion(+), 11 deletions(-)

diff --git a/capytale/contracts/src/reload.ts b/capytale/contracts/src/reload.ts
index 21e66ff..e23a977 100644
--- a/capytale/contracts/src/reload.ts
+++ b/capytale/contracts/src/reload.ts
@@ -20,7 +20,7 @@ export type ReloadV1 = {
          * - Le *MetaPlayer* récupère un état (`state`) contenant toutes les données qui devront
          *   être données ensuite à la nouvelle instance de l'*Application* (à minima, toutes les 
          *   données liée à l'activité en cours).
-         * - Après rechargement, le *MetaPlayer* n'appellera _PAS_ la méthode `loadContent` de 
+         * - Après rechargement, le *MetaPlayer* n'appellera _PAS_ la méthode `loadContent`
          *   du contrat de l'*Application*, mais la méthode `reloaded` du présent contrat.
          * 
          * @param url l'URL à charger dans l'iFrame.
diff --git a/capytale/contracts/src/simple-content-eval.ts b/capytale/contracts/src/simple-content-eval.ts
index db74f4f..08c970d 100644
--- a/capytale/contracts/src/simple-content-eval.ts
+++ b/capytale/contracts/src/simple-content-eval.ts
@@ -66,10 +66,6 @@ export type SimpleContentEvalV1<T> = {
          * L'*Application* peut retourner `null` si le contenu correspond à la valeur par défaut
          * initiale.
          * 
-         * Contrat :
-         * Lorsque cette méthode est appelée, l'*Application* doit empêcher l'utilisateur de 
-         * modifier le contenu de la page, jusqu'à ce qu'elle reçoive la notification de fin 
-         * de sauvegarde, via l'appel à `contentSaved()`.
          * 
          * @returns le contenu de l'activité
          */
diff --git a/capytale/contracts/src/simple-content.ts b/capytale/contracts/src/simple-content.ts
index 753b3a9..e685dfc 100644
--- a/capytale/contracts/src/simple-content.ts
+++ b/capytale/contracts/src/simple-content.ts
@@ -50,10 +50,6 @@ export type SimpleContentV1<T> = {
          * L'*Application* peut retourner `null` si le contenu correspond à la valeur par défaut
          * initiale.
          * 
-         * Contrat :
-         * Lorsque cette méthode est appelée, l'*Application* doit empêcher l'utilisateur de 
-         * modifier le contenu de la page, jusqu'à ce qu'elle reçoive la notification de fin 
-         * de sauvegarde, via l'appel à `contentSaved()`.
          * 
          * @returns le contenu de l'activité
          */
diff --git a/capytale/contracts/src/theme.ts b/capytale/contracts/src/theme.ts
index aab6415..86cc35f 100644
--- a/capytale/contracts/src/theme.ts
+++ b/capytale/contracts/src/theme.ts
@@ -23,7 +23,6 @@ export type ThemeV1 = {
 
     /**
      * L'interface qui expose l'*Application* au *MetaPlayer*.
-     * Les méthodes non implantées sont ignorées.
      */
     application: {
         /**
diff --git a/capytale/contracts/src/workflow.ts b/capytale/contracts/src/workflow.ts
index e309592..454295e 100644
--- a/capytale/contracts/src/workflow.ts
+++ b/capytale/contracts/src/workflow.ts
@@ -24,7 +24,6 @@ export type WorkflowV1 = {
 
     /**
      * L'interface qui expose l'*Application* au *MetaPlayer*.
-     * Les méthodes non implantées sont ignorées.
      */
     application: {
         /**

From 34beaeca765558178db1f88cac7eea6f8432c3a9 Mon Sep 17 00:00:00 2001
From: FredZinelli <145555278+FredZinelli@users.noreply.github.com>
Date: Wed, 12 Mar 2025 18:02:19 +0100
Subject: [PATCH 06/20] Update reload.ts

---
 capytale/contracts/src/reload.ts | 29 +++++++++++++++++++----------
 1 file changed, 19 insertions(+), 10 deletions(-)

diff --git a/capytale/contracts/src/reload.ts b/capytale/contracts/src/reload.ts
index e23a977..424b23a 100644
--- a/capytale/contracts/src/reload.ts
+++ b/capytale/contracts/src/reload.ts
@@ -1,5 +1,14 @@
 /**
- * Ce module définit le mécanisme de rechargement de l'iFrame.
+ * Ce module définit le mécanisme de rechargement de l'iFrame:
+ * 
+ * Si l'*Application* n'est pas une SWA (Single Web App), il peut lui être nécessaire de changer de page
+ * en cours d'utilisation. Dans ce cas, le *MetaPlayer* doit être notifié pour que l'iFrame soit détruite 
+ * et reconstruite avec la nouvelle URL.
+ * Ce contrat permet également de transmettre les informations sur le contenu actuel de l'*Application*
+ * entre la page initiale et la nouvelle page, sans passer par le mécanisme de sauvegarde des contrats
+ * de type `simple-content`.
+ *
+ * Souscription au contrat avec `reload:{v}`, où `{v}` est le numéro de version.
  */
 
 /**
@@ -18,18 +27,19 @@ export type ReloadV1 = {
          * 
          * - L'iFrame est détruite puis recréée avec la nouvelle adresse.
          * - Le *MetaPlayer* récupère un état (`state`) contenant toutes les données qui devront
-         *   être données ensuite à la nouvelle instance de l'*Application* (à minima, toutes les 
+         *   être ensuite passées à la nouvelle instance de l'*Application* (à minima, toutes les 
          *   données liée à l'activité en cours).
-         * - Après rechargement, le *MetaPlayer* n'appellera _PAS_ la méthode `loadContent`
-         *   du contrat de l'*Application*, mais la méthode `reloaded` du présent contrat.
+         * - Après chargement de la nouvelle page, l'*Application* souscrit aux différents contrats,
+         * mais le *MetaPlayer* n'appellera _PAS_ la méthode `loadContent` : c'est la la méthode 
+         * `reloaded` du présent contrat qui sera appelée à la place.
          * 
          * @param url l'URL à charger dans l'iFrame.
-         *            Si null, l'URL actuelle est rechargée.
-         *            ATTENTION: si la logique de l'*Application* repose sur des paramètres passés 
-         *            via l'URL, ne pas oublier de les rajouter.
+         *        Si `null`, l'URL actuelle est rechargée.
+         *        ATTENTION: si la logique de l'*Application* repose sur des paramètres passés 
+         *        via l'URL, ne pas oublier de les rajouter à cet argument.
          * 
          * @param state un état à transmettre à l'application après le rechargement.
-         *        L'objet state doit être serializable avec JSON.stringify.
+         *        L'objet `state` doit être serializable avec JSON.stringify.
          * 
          */
         reload(url?: string | null, state?: any): void;
@@ -37,12 +47,11 @@ export type ReloadV1 = {
 
     /**
      * L'interface qui expose l'*Application* au *MetaPlayer*.
-     * Les méthodes non implantées sont ignorées.
      */
     application: {
         /**
          * Le *MetaPlayer* appelle cette méthode pour indiquer à l'*Application* qu'un
-         * rechargement a eu lieu.
+         * rechargement a eu lieu et lui passé le dernier état de l'*Ap^plication*.
          * Cette méthode est appelée en lieu et place de `loadContent`, suite à une
          * demande de rechargement.
          * 

From 2c17f32815b9b13d5040cd2fb86a9977b901288c Mon Sep 17 00:00:00 2001
From: FredZinelli <145555278+FredZinelli@users.noreply.github.com>
Date: Wed, 12 Mar 2025 18:10:30 +0100
Subject: [PATCH 07/20] Update mode.ts

---
 capytale/contracts/src/mode.ts | 17 +++++++++++++----
 1 file changed, 13 insertions(+), 4 deletions(-)

diff --git a/capytale/contracts/src/mode.ts b/capytale/contracts/src/mode.ts
index 3bc7a27..a16a973 100644
--- a/capytale/contracts/src/mode.ts
+++ b/capytale/contracts/src/mode.ts
@@ -1,5 +1,15 @@
 /**
  * Ce module définit la transmission du mode de l'activité.
+ *
+ * Les modes peuvent être :
+ *    - `"create"` - Pour un enseignant en train de créer/modifier une activité.
+ *    - `"assignment"` - Pour un élève/participant en train d'effectuer le travail demandé.
+ *    - `"review"` - Pour un enseignant regardant la copie d'un élève.participant (que la
+ *                   copie soit finalisée ou non: voir le contrat `workflow`).
+ *    - `"view"` - Pour un enseignant regardant une activité créée par un autre enseignant
+ *                 depuis la bibliothèque d'activité de Capytale.
+ *
+ * Souscription avec `mode:{v}`, où `{v}` est le numéro de version du contrat.
  */
 
 type Mode =
@@ -32,11 +42,10 @@ export type ModeV1 = {
      */
     application: {
         /**
-         * Le *MetaPlayer* appelle cette méthode pour indiquer le mode à l'*Application*,
-         * après avoir appelé la méthode `loadContent`.
-         * Ne devrait être appelé qu'une seule fois.
+         * Le *MetaPlayer* appelle systématiquement cette méthode pour indiquer le mode à l'*Application*
+         * avant d'avoir appelé la méthode `loadContent` des contrats `simple-content`.
          * 
-         * @param mode le mode à appliquer. 
+         * @param mode le mode utilisé actuellement pour l'activité. 
         */
         setMode(mode: Mode): void;
     };

From 0a5bf14a076fbcfb9c683eb5a529a075cb969030 Mon Sep 17 00:00:00 2001
From: FredZinelli <145555278+FredZinelli@users.noreply.github.com>
Date: Wed, 12 Mar 2025 18:37:30 +0100
Subject: [PATCH 08/20] Update workflow.ts

---
 capytale/contracts/src/workflow.ts | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/capytale/contracts/src/workflow.ts b/capytale/contracts/src/workflow.ts
index 454295e..5f6d964 100644
--- a/capytale/contracts/src/workflow.ts
+++ b/capytale/contracts/src/workflow.ts
@@ -1,5 +1,15 @@
 /**
- * Ce module définit la transmission du workflow de l'assignment.
+ * Ce module définit la transmission de l'état actuel du workflow de la copie d'un 
+ * élève/participant.
+ * L'état workflow peut prendre l'une des valeurs suivante :
+ * 
+ *    - `"current"`  - L'élève n'a pas encore rendu la copie.
+ *    - `"finished"` - L'élève a rendu la copie : il ne peut plus la modifier (il peut encore
+ *                     la consulter ou pas, selon le réglage du "mode d'accès" de l'activité,
+ *                     dans les paramètres de l'activité).
+ *    - `"corrected"` - L'enseignant a marqué la copie comme corrigée/évaluée.
+ * 
+ * Souscription avec `workdlow:{v}`, où `{v}` est le numéro de version du contrat.
  */
 
 type Workflow = 'current' | 'finished' | 'corrected';

From 493e84a243c40afa50785215ec01774bcb241850 Mon Sep 17 00:00:00 2001
From: FredZinelli <145555278+FredZinelli@users.noreply.github.com>
Date: Wed, 12 Mar 2025 18:55:20 +0100
Subject: [PATCH 09/20] Update simple-content.ts

---
 capytale/contracts/src/simple-content.ts | 34 +++++++++++++++++-------
 1 file changed, 25 insertions(+), 9 deletions(-)

diff --git a/capytale/contracts/src/simple-content.ts b/capytale/contracts/src/simple-content.ts
index e685dfc..721779a 100644
--- a/capytale/contracts/src/simple-content.ts
+++ b/capytale/contracts/src/simple-content.ts
@@ -1,10 +1,21 @@
 /**
- * Ce module définit le contrat d'échange des contenus.
+ * Ce module définit le contrat d'échange des contenus de l'activité.
+ *
+ *    - Les données peuvent être `null` lorsqu'aucune donnée n'existe pour l'activité, 
+ *      côté Capytale (typiquement: au moment de la création de l'activité).
+ *    - Les données pour une acivité doivent toujours être du même type, quel que soit 
+ *      le mode utilisé (create, assignment, ...).
+ *
+ * Souscription avec `"simple-content({type}):{v}"`, où :
+ *    - `{v}` est le numéro de version du contrat.
+ *    - `{type}` est le type de données utilisées par l'*Application*. Peut être:
+ *            json
+ *            text
  */
 
 /**
  * Un contrat pour gérer un contenu simple :
- * - un seul contenu de type `T`
+ * - un seul contenu de type `T|null`
  * - le mode assignment est le même que le mode create c'est à dire que
  *   le contenu initial pour l'élève est celui qui a été préparé par l'enseignant.
  * 
@@ -27,16 +38,16 @@ export type SimpleContentV1<T> = {
 
     /**
      * L'interface qui expose l'*Application* au *MetaPlayer*.
-     * Les méthodes non implantées sont ignorées.
      */
     application: {
         /**
          * Le *MetaPlayer* appelle cette méthode après la souscription au contrat, pour transmettre
          * les données de l'activité à l'*Application*.
          * 
-         * Si `content` est `null`, l'*Application* doit réinitialiser son contenu à la valeur par 
-         * défaut initiale.
-         * Si l'*Application* n'est pas en mesure de charger le contenu, elle doit lever une exeption.
+         *     - Si `content` est `null`, l'*Application* doit initialiser son contenu à la valeur 
+         *       par défaut initiale.
+         *     - Si l'*Application* n'est pas en mesure de charger le contenu, elle doit lever une 
+         *       exeption.
          * 
          * @param content le contenu de l'activité
         */
@@ -47,17 +58,22 @@ export type SimpleContentV1<T> = {
          * lorsque l'utilisateur effectue une action demandant d'enregistrer des données sur 
          * Capyale (typiquement, cliquer sur le bouton Enregsitrer dans le bandeau supérieur).
          * 
-         * L'*Application* peut retourner `null` si le contenu correspond à la valeur par défaut
+         * L'*Application* peut renvoyer `null` si le contenu correspond à la valeur par défaut
          * initiale.
          * 
-         * 
          * @returns le contenu de l'activité
          */
         getContent(): T | null;
 
         /**
          * Le *MetaPlayer* appelle cette méthode pour indiquer à l'*Application* que le contenu 
-         * a été sauvegardé.
+         * a été sauvegardé, côté Capytale.
+         *
+         * Cette notification peut être utile à l'*Application* si elle gère des états `dirty` 
+         * (données non enregistrées dans Capytale) pour éviter que l'utilisateur ne puisse faire 
+         * certaines actions qui lui ferait perdre ces données par mégarde.
+         *
+         * Cette méthode n'est appelée que si la sauvegarde a été un succès.
          */
         contentSaved(): void;
     };

From 796ce6b45371d6ba3c8deb2ee1a4808a3ee709c5 Mon Sep 17 00:00:00 2001
From: FredZinelli <145555278+FredZinelli@users.noreply.github.com>
Date: Wed, 12 Mar 2025 18:58:54 +0100
Subject: [PATCH 10/20] Update mode.ts

---
 capytale/contracts/src/mode.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/capytale/contracts/src/mode.ts b/capytale/contracts/src/mode.ts
index a16a973..2de53ee 100644
--- a/capytale/contracts/src/mode.ts
+++ b/capytale/contracts/src/mode.ts
@@ -38,7 +38,7 @@ export type ModeV1 = {
 
     /**
      * L'interface qui expose l'*Application* au *MetaPlayer*.
-     * Les méthodes non implantées sont ignorées.
+     * Toutes les méthodes sont asynchrones.
      */
     application: {
         /**

From c196cd3b6cd62deff30abfb6f14b03a4dce0fb35 Mon Sep 17 00:00:00 2001
From: FredZinelli <145555278+FredZinelli@users.noreply.github.com>
Date: Wed, 12 Mar 2025 18:59:18 +0100
Subject: [PATCH 11/20] Update reload.ts

---
 capytale/contracts/src/reload.ts | 1 +
 1 file changed, 1 insertion(+)

diff --git a/capytale/contracts/src/reload.ts b/capytale/contracts/src/reload.ts
index 424b23a..ad97fee 100644
--- a/capytale/contracts/src/reload.ts
+++ b/capytale/contracts/src/reload.ts
@@ -47,6 +47,7 @@ export type ReloadV1 = {
 
     /**
      * L'interface qui expose l'*Application* au *MetaPlayer*.
+     * Toutes les méthodes sont asynchrones.
      */
     application: {
         /**

From e1f08faa8f305d840ff80cc1887e8ea73660b092 Mon Sep 17 00:00:00 2001
From: FredZinelli <145555278+FredZinelli@users.noreply.github.com>
Date: Wed, 12 Mar 2025 18:59:40 +0100
Subject: [PATCH 12/20] Update simple-content-eval.ts

---
 capytale/contracts/src/simple-content-eval.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/capytale/contracts/src/simple-content-eval.ts b/capytale/contracts/src/simple-content-eval.ts
index 08c970d..2d77602 100644
--- a/capytale/contracts/src/simple-content-eval.ts
+++ b/capytale/contracts/src/simple-content-eval.ts
@@ -44,7 +44,7 @@ export type SimpleContentEvalV1<T> = {
 
     /**
      * L'interface qui expose l'*Application* au *MetaPlayer*.
-     * Les méthodes non implantées sont ignorées.
+     * Toutes les méthodes sont asynchrones.
      */
     application: {
         /**

From beb266101d4454331d207528ccf9c0abcf5a7721 Mon Sep 17 00:00:00 2001
From: FredZinelli <145555278+FredZinelli@users.noreply.github.com>
Date: Wed, 12 Mar 2025 18:59:57 +0100
Subject: [PATCH 13/20] Update simple-content.ts

---
 capytale/contracts/src/simple-content.ts | 1 +
 1 file changed, 1 insertion(+)

diff --git a/capytale/contracts/src/simple-content.ts b/capytale/contracts/src/simple-content.ts
index 721779a..13157da 100644
--- a/capytale/contracts/src/simple-content.ts
+++ b/capytale/contracts/src/simple-content.ts
@@ -38,6 +38,7 @@ export type SimpleContentV1<T> = {
 
     /**
      * L'interface qui expose l'*Application* au *MetaPlayer*.
+     * Toutes les méthodes sont asynchrones.
      */
     application: {
         /**

From 6d7deb9c5d0df0f8a33f541f0008ce191c1cb6c0 Mon Sep 17 00:00:00 2001
From: FredZinelli <145555278+FredZinelli@users.noreply.github.com>
Date: Wed, 12 Mar 2025 19:00:15 +0100
Subject: [PATCH 14/20] Update theme.ts

---
 capytale/contracts/src/theme.ts | 1 +
 1 file changed, 1 insertion(+)

diff --git a/capytale/contracts/src/theme.ts b/capytale/contracts/src/theme.ts
index 86cc35f..a2723ab 100644
--- a/capytale/contracts/src/theme.ts
+++ b/capytale/contracts/src/theme.ts
@@ -23,6 +23,7 @@ export type ThemeV1 = {
 
     /**
      * L'interface qui expose l'*Application* au *MetaPlayer*.
+     * Toutes les méthodes sont asynchrones.
      */
     application: {
         /**

From 561126afd144925ff6af5ef26c8d8b40a4eb02bb Mon Sep 17 00:00:00 2001
From: FredZinelli <145555278+FredZinelli@users.noreply.github.com>
Date: Wed, 12 Mar 2025 19:01:09 +0100
Subject: [PATCH 15/20] Update theme.ts

---
 capytale/contracts/src/theme.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/capytale/contracts/src/theme.ts b/capytale/contracts/src/theme.ts
index a2723ab..772b3f9 100644
--- a/capytale/contracts/src/theme.ts
+++ b/capytale/contracts/src/theme.ts
@@ -1,5 +1,5 @@
 /**
- * Ce module définit la transmission du thème d'affichage.
+ * Ce module définit la transmission du thème d'affichage (`"dark"|"light"`).
  */
 
 /**

From 1ec32edd75f49353dd0eee791946b20bc77a334a Mon Sep 17 00:00:00 2001
From: FredZinelli <145555278+FredZinelli@users.noreply.github.com>
Date: Wed, 12 Mar 2025 19:01:32 +0100
Subject: [PATCH 16/20] Update workflow.ts

---
 capytale/contracts/src/workflow.ts | 1 +
 1 file changed, 1 insertion(+)

diff --git a/capytale/contracts/src/workflow.ts b/capytale/contracts/src/workflow.ts
index 5f6d964..315063d 100644
--- a/capytale/contracts/src/workflow.ts
+++ b/capytale/contracts/src/workflow.ts
@@ -34,6 +34,7 @@ export type WorkflowV1 = {
 
     /**
      * L'interface qui expose l'*Application* au *MetaPlayer*.
+     * Toutes les méthodes sont asynchrones.
      */
     application: {
         /**

From d00973f67d68e61223e16e8b0f8b18b1792c825c Mon Sep 17 00:00:00 2001
From: FredZinelli <145555278+FredZinelli@users.noreply.github.com>
Date: Wed, 12 Mar 2025 19:01:48 +0100
Subject: [PATCH 17/20] Update workflow.ts

---
 capytale/contracts/src/workflow.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/capytale/contracts/src/workflow.ts b/capytale/contracts/src/workflow.ts
index 315063d..4bee2d2 100644
--- a/capytale/contracts/src/workflow.ts
+++ b/capytale/contracts/src/workflow.ts
@@ -9,7 +9,7 @@
  *                     dans les paramètres de l'activité).
  *    - `"corrected"` - L'enseignant a marqué la copie comme corrigée/évaluée.
  * 
- * Souscription avec `workdlow:{v}`, où `{v}` est le numéro de version du contrat.
+ * Souscription avec `workflow:{v}`, où `{v}` est le numéro de version du contrat.
  */
 
 type Workflow = 'current' | 'finished' | 'corrected';

From c3eee2a16a623d77a5393445ae736b28bdb337b7 Mon Sep 17 00:00:00 2001
From: FredZinelli <145555278+FredZinelli@users.noreply.github.com>
Date: Wed, 12 Mar 2025 19:05:08 +0100
Subject: [PATCH 18/20] Update workflow.ts

---
 capytale/contracts/src/workflow.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/capytale/contracts/src/workflow.ts b/capytale/contracts/src/workflow.ts
index 4bee2d2..b46fe1c 100644
--- a/capytale/contracts/src/workflow.ts
+++ b/capytale/contracts/src/workflow.ts
@@ -1,7 +1,7 @@
 /**
  * Ce module définit la transmission de l'état actuel du workflow de la copie d'un 
  * élève/participant.
- * L'état workflow peut prendre l'une des valeurs suivante :
+ * L'état workflow peut prendre l'une des valeurs suivantes :
  * 
  *    - `"current"`  - L'élève n'a pas encore rendu la copie.
  *    - `"finished"` - L'élève a rendu la copie : il ne peut plus la modifier (il peut encore

From d0ad469dc9e1853e95afb3ec8e8f126bc772986b Mon Sep 17 00:00:00 2001
From: FredZinelli <145555278+FredZinelli@users.noreply.github.com>
Date: Wed, 12 Mar 2025 19:17:17 +0100
Subject: [PATCH 19/20] Update workflow.ts

---
 capytale/contracts/src/workflow.ts | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/capytale/contracts/src/workflow.ts b/capytale/contracts/src/workflow.ts
index b46fe1c..4b17923 100644
--- a/capytale/contracts/src/workflow.ts
+++ b/capytale/contracts/src/workflow.ts
@@ -39,9 +39,11 @@ export type WorkflowV1 = {
     application: {
         /**
          * Le *MetaPlayer* appelle cette méthode pour indiquer le workflow à l'*Application*.
-         * Peut être appelé plusieurs fois.
+         * Cette méthode est appelée une première fois juste après un appel à `setMode` (si le contrat 
+         * `mode` a été souscrit) pour indiqué l'état initial, puis elle est rappelée à chaque fois que 
+         * l'état de la copie de l'élève/du participant est modifié.
          * 
-         * @param mode le mode à appliquer. 
+         * @param workflow: la nouvelle valeur du workflow à appliquer. 
         */
         setWorkflow(wf: Workflow): void;
     };

From 1d2df87344f5b2dcd6e8e06d7355ae704c42aba4 Mon Sep 17 00:00:00 2001
From: FredZinelli <145555278+FredZinelli@users.noreply.github.com>
Date: Wed, 17 Sep 2025 16:43:23 +0200
Subject: [PATCH 20/20] Update simple-content-eval.ts

Info sur `evalLabel`
---
 capytale/contracts/src/simple-content-eval.ts | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/capytale/contracts/src/simple-content-eval.ts b/capytale/contracts/src/simple-content-eval.ts
index 2d77602..6ac553d 100644
--- a/capytale/contracts/src/simple-content-eval.ts
+++ b/capytale/contracts/src/simple-content-eval.ts
@@ -11,6 +11,11 @@ type StringEvaluation = {
     score: string;
 }
 
+
+/**Représente l'évaluation d'un exercice de l'activité.
+ *   - `evalLabel`: utiliser `"Exercice N" (sert d'identifiant pour enregistrer les données)
+ *   - `evalTitle`: titre (optionnel) de l'exercice.
+ */
 type Evaluation = {
     evalLabel: string;
     evalTitle?: string;