# Guide de Spécification des Decks JSON - Mode Pause (`DECK_SPECIFICATION.md`)

Ce document est le guide de référence complet destiné à toute personne souhaitant **créer, personnaliser ou partager un Deck d'activités** pour l'application **Mode Pause** (`mp.aqualys.fr`).

---

## 1. Vue d'Ensemble d'un Deck

Un Deck est un fichier texte au format **JSON** respectant la convention de nommage `snake_case`. Il contient la liste des cartes d'activités, leurs visuels, leurs thèmes de couleur et leurs effets visuels ou temporels.

Les decks créés peuvent être importés dans l'application via :
1. **Un glisser-déposer** du fichier `.json` dans le modal d'importation.
2. **Le coller direct** du code JSON brut.
3. **Une URL publique** (ex: `https://mon-domaine.fr/mon_deck.json`).

---

## 2. Structure Globale du Fichier JSON

Voici le squelette de base d'un fichier de deck valide :

```json
{
  "deck_id": "mon_deck_custom",
  "deck_title": "Ma Pause Créative",
  "theme": "theme_home",
  "cards": [
    {
      "id": "card_exemple_1",
      "title": "Titre de la Pause",
      "description": "Consignes détaillées de l'activité à réaliser.",
      "duration": "5 min",
      "effects": [
        {
          "type": "open_activity",
          "config": {
            "animation_style": "pencil_doodle"
          }
        }
      ]
    }
  ]
}
```

### Propriétés de Niveau Supérieur

| Propriété | Type | Requis | Description / Valeurs autorisées |
| :--- | :--- | :--- | :--- |
| `deck_id` | `string` | **Oui** | Identifiant unique (ex: `"my_work_deck"`). Utiliser le `snake_case`. |
| `deck_title` | `string` | **Oui** | Titre affiché dans le menu de sélection (ex: `"Au Taf"`). |
| `theme` | `string` | **Oui** | Thème graphique du deck : `"theme_work"` (Bleu nuit), `"theme_home"` (Violet cosy), ou `"theme_vacation"` (Ambre ensoleillé). |
| `cards` | `array` | **Oui** | Liste des cartes d'activités appartenant au deck. |

---

## 3. Structure d'une Carte (`cards[]`)

Chaque objet carte dans le tableau `cards` possède les champs suivants :

```json
{
  "id": "card_journal",
  "title": "Journal personnel",
  "description": "Munissez-vous de votre journal et écrivez-y ce qui vous passe par la tête.",
  "duration": "Libre",
  "effects": [
    {
      "type": "open_activity",
      "config": {
        "animation_style": "writing_quill"
      }
    }
  ]
}
```

| Propriété | Type | Requis | Description |
| :--- | :--- | :--- | :--- |
| `id` | `string` | **Oui** | Identifiant unique de la carte (ex: `"card_baking"`). Détermine aussi l'icône fixe par défaut si non spécifié. |
| `title` | `string` | **Oui** | Titre principal imprimé sur la carte et sur l'écran d'action. |
| `description` | `string` | **Oui** | Texte explicatif réaffiché dans le bandeau d'instructions en haut de l'écran. |
| `duration` | `string` | **Oui** | Texte du badge de durée (ex: `"5 min"`, `"15 min"`, `"Libre"`). |
| `effects` | `array` | **Oui** | Liste combinatoire des effets à déclencher simultanément lors de l'activation. |

---

## 4. Catalogue des Effets Combinatoires (`effects[]`)

Le tableau `effects` permet d'associer **plusieurs modules simultanés** (ex: un chronomètre + une animation vectorielle + un fond assombri). Chaque effet est un objet avec un `type` et une `config`.

### A. Modules Temporels et Chronomètres (`type`)

#### 1. `open_activity` (Activité Libre sans timer)
Utilisé pour les pauses sans limite de temps stricte.
```json
{
  "type": "open_activity",
  "config": {
    "animation_style": "walking_shoes"
  }
}
```

#### 2. `digital_clock` (Horloge Rétro à Digits Rouges)
Affichage rétro réveil vintage à digits rouges positionné sous l'animation.
```json
{
  "type": "digital_clock",
  "config": {
    "duration_seconds": 300
  }
}
```

#### 3. `pie_chart_timer` (Camembert Solaire SVG)
Affiche un cadran camembert qui se vide progressivement, avec décompte sous l'icône.
```json
{
  "type": "pie_chart_timer",
  "config": {
    "duration_seconds": 600
  }
}
```

#### 4. `needle_clock` (Horloge Anti-Horlogique à Aiguille)
Cadran avec aiguille tournant dans le **sens inverse des aiguilles d'une montre**.
```json
{
  "type": "needle_clock",
  "config": {
    "duration_seconds": 900
  }
}
```

#### 5. `screen_crack` (Fissure d'Écran)
Affichage d'une fissure visuelle d'écran avec message personnalisé.
```json
{
  "type": "screen_crack",
  "config": {
    "duration_seconds": 1200,
    "message": "Fissure de pause ! Éloignez-vous de l'écran."
  }
}
```

---

### B. Modules Visuels et Ambiance (`type`)

#### 1. `dark_overlay` (Assombrissement du fond)
```json
{
  "type": "dark_overlay",
  "config": {
    "opacity": 0.85
  }
}
```

#### 2. `particle_text` (Mots ou Bulles Flottantes)
```json
{
  "type": "particle_text",
  "config": {
    "text": "Zzz...",
    "color": "#a855f7"
  }
}
```

#### 3. `water_glass` (Verre d'eau en 10 gorgées)
Affiche un verre se vidant de manière séquentielle en 10 gorgées précises.
```json
{
  "type": "water_glass",
  "config": {
    "sip_count": 10
  }
}
```

#### 4. `coffee_machine` (Tasse à café et vapeur)
```json
{
  "type": "coffee_machine",
  "config": {}
}
```

#### 5. `breathing_guide` (Guide de Respiration Rythmé)
Cercle d'expansion pour la cohérence cardiaque (inspiration / expiration).
```json
{
  "type": "breathing_guide",
  "config": {
    "inhale_sec": 3,
    "exhale_sec": 3
  }
}
```

---

### C. Catalogue des Animations Vectorielles (`animation_style`)

Ces styles s'utilisent dans la `config` des modules comme `open_activity`. Toutes les animations sont dessinées en pur fil de fer vectoriel (Line Art).

| `animation_style` | Description du Visuel |
| :--- | :--- |
| `"pencil_doodle"` | Crayon fil de fer oblique traçant des lignes avec 3 pauses d'inspection du trait. |
| `"walking_shoes"` | Baskets fil de fer en profil avec biomécanique exacte de marche (pose talon, déroulé, décollement). |
| `"writing_quill"` | Plume d'écriture Renaissance avec bec d'encre vers le bas. |
| `"cleaning_broom"` | Balai-brosse en T balayant le sol avec étincelles de propreté. |
| `"rolling_pin"` | Rouleau à pâtisserie avec cylindre orienté à 45° le long de ses poignées. |
| `"museum_frame"` | Tour Eiffel reconnaissable avec reflets d'objectifs photo (*camera lens flare*). |
| `"shopping_bags"` | Sac cabas avec boîtes de couleurs tombant 1 fois toutes les 15s (figeage net à l'impact). |
| `"sun_clouds"` | Soleil à 8 rayons extensibles avec nuage moutonneux opaque glissant devant. |
| `"photo_flash"` | Appareil photo numérique avec flash réactif et **tirage aléatoire de défi photo**. |
| `"gamepad_neon"` | Manette néon avec Croix D-Pad (+), boutons ABXY et balancement. |
| `"book_pages"` | Livre ouvert dont les pages tournent doucement. |
| `"retro_screen"` | Téléviseur vintage CRT avec effet de balayage. |
| `"compass_map"` | Boussole oscillante avec aiguille magnétique. |
| `"fireworks"` | Feux d'artifice et étoiles éclatantes. |
| `"cloche_dish"` | Cloche de service de restaurant se soulevant délicatement. |

---

### D. Option Spéciale : Tirage de Défis Aléatoires (`photo_flash`)

Pour l'animation `"photo_flash"`, vous pouvez spécifier un tableau de contraintes personnalisées dans `random_constraints`. L'application choisira au hasard une consigne à l'ouverture de la carte :

```json
{
  "type": "open_activity",
  "config": {
    "animation_style": "photo_flash",
    "random_constraints": [
      "Prendre en photo quelque chose de vert brillant",
      "Prendre en photo un reflet dans l'eau ou une vitre",
      "Prendre en photo un objet ayant une forme géométrique parfaite",
      "Prendre en photo une ombre allongée"
    ]
  }
}
```

---

## 5. Exemple d'un Fichier JSON Complet

Voici un exemple prêt à l'emploi que vous pouvez utiliser comme modèle pour concevoir votre propre deck :

```json
{
  "deck_id": "mon_deck_meditation",
  "deck_title": "Zen & Méditation",
  "theme": "theme_home",
  "cards": [
    {
      "id": "card_zen_breath",
      "title": "Respiration 3/3",
      "description": "Fermez les yeux et suivez le rythme du cercle pour apaiser votre esprit.",
      "duration": "3 min",
      "effects": [
        {
          "type": "digital_clock",
          "config": {
            "duration_seconds": 180
          }
        },
        {
          "type": "breathing_guide",
          "config": {
            "inhale_sec": 3,
            "exhale_sec": 3
          }
        }
      ]
    },
    {
      "id": "card_tea_moment",
      "title": "Savourer un thé",
      "description": "Préparez votre boisson chaude préférée et observez la vapeur monter sans consulter vos écrans.",
      "duration": "Libre",
      "effects": [
        {
          "type": "open_activity",
          "config": {
            "animation_style": "coffee_machine"
          }
        }
      ]
    }
  ]
}
```