ijsbreker/CLAUDE.md

# IJsbreker Workshop Spel

Browser-based interactief workshop spel waarbij deelnemers fysiek kiezen tussen twee stellingen die op een beamer worden getoond.

## Project Overzicht

**Type:** Hobby project / Workshop tool
**Status:** Volledig functioneel v1.0
**Gemaakt:** 2025-11-03

### Wat doet het?
Een presentatie tool voor workshops waar deelnemers tussen twee stellingen moeten kiezen. De facilitator toont stellingen op een beamer, een timer loopt visueel rond het scherm, en daarna zie je de stellingen grayed out terwijl mensen fysiek naar links/rechts bewegen.

### Features
- Startscherm met controle over startmoment
- Fullscreen modus voor presentaties zonder browser UI
- Timer animatie die synchroon rond het scherm loopt
- Geluidssignaal bij einde timer
- Overlay met stellingen na timer
- Stelling counter rechtsonder (toont voortgang)
- Keyboard shortcuts (spatiebalk voor volgende, ESC voor fullscreen uit)
- Direct eindscherm bij laatste stelling
- Web-based stellingen editor met Flask backend
- Workshop sets systeem (meerdere configuraties)
- Stellingkast met bibliotheek voor snelle import
- Drag & drop om stellingen te herordenen
- Real-time CRUD operaties op stellingen
- Kleurenpicker voor achtergronden
- Volledig offline werkend

### Tech Stack
- Frontend: Pure HTML/CSS/JavaScript
- Backend: Python Flask + flask-cors
- Config driven via JSON (sets.json voor meerdere configuraties)
- Geen externe dependencies voor presentatie modus

## Bestandsstructuur

```
/ijsbreker
├── index.html          # Presentatie modus (hoofdspel)
├── app.js              # Game logic en timer animatie
├── style.css           # Presentatie styling
├── config.json         # Actieve configuratie (gebruikt door presentatie)
├── sets.json           # Database met alle workshop sets
├── stellingkast.json   # Bibliotheek met stellingen voor import
├── editor.html         # Web-based config editor met sets beheer
├── editor.js           # Editor functionaliteit en sets management
├── editor.css          # Editor styling
├── server.py           # Flask backend voor editor en sets API
├── requirements.txt    # Python dependencies
├── .gitignore          # Exclude venv, .DS_Store, etc
└── README.md           # Uitgebreide documentatie
```

## Gebruik

### Presentatie Modus
```bash
# Start Flask server (nodig voor config.json laden)
source venv/bin/activate
python server.py

# Open in browser
open http://localhost:8000/index.html
```

**Controls:**
- Groene "Start IJsbreker" knop om te beginnen
- Fullscreen knop rechtsonder voor volledig scherm
- Spatiebalk: Start spel of ga naar volgende stelling
- ESC: Verlaat fullscreen modus
- Automatische timer animatie
- Geluidssignaal bij einde

### Stellingen Bewerken
```bash
# Start Flask server
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python server.py

# Open editor
open http://localhost:8000/editor.html
```

**Editor features:**
- **Sets beheer:** Meerdere workshop configuraties opslaan en laden
- **Sets dropdown:** Selecteer actieve set of maak nieuwe set aan
- Toevoegen/verwijderen stellingen via drag & drop
- Stellingkast met bibliotheek voor snelle import
- Timer aanpassen per set
- Kleuren aanpassen per set
- Auto-save naar sets.json en config.json

## Session History

### 2025-11-03 - Initiële Ontwikkeling
**Nieuwe features:**
- Browser-based interactief workshop spel gebouwd
- Timer animatie met visuele rand rond scherm
- Geluidssignaal implementatie bij timer einde
- Overlay systeem voor stellingen na timer
- Keyboard shortcuts voor presentatie flow
- Web-based stellingen editor met Flask backend
- Real-time CRUD operaties op config.json
- Kleurenpicker voor achtergrond customization
- Validatie en filtering van lege stellingen
- Volledig offline werkend systeem

**Tech beslissingen:**
- Pure HTML/CSS/JavaScript voor maximale portabiliteit
- Flask backend voor eenvoudige config management
- JSON als database voor simpele deployment
- Geen build process nodig voor presentatie modus
- flask-cors voor lokale development

**Deployment:**
- Eerste commit en push naar Forgejo
- Repository: git.dutchstack.nl:frankmeeuwsen/ijsbreker.git
- Volledig functionele v1.0 klaar voor gebruik

**Status:**
- Presentatie modus volledig werkend
- Editor volledig functioneel
- Documentatie compleet in README.md
- Klaar voor workshop gebruik

### 2025-11-07 - Startscherm Toegevoegd
**Nieuwe feature:**
- Startscherm met groene "Start IJsbreker" knop toegevoegd
- Timer begint nu pas na klik op startknop (voorheen automatisch)
- Gebruiker heeft volledige controle over startmoment presentatie
- Spatiebalk werkt op startscherm voor snelle start

**Gewijzigde bestanden:**
- `index.html` - Startscherm HTML toegevoegd, statementScreen krijgt .hidden class bij laden
- `style.css` - Styling voor start-screen en start-button (groene knop met hover effecten)
- `app.js` - Flow aangepast: nieuwe functies `showStartScreen()` en `startGame()`, event listeners voor startButton, spatiebalk werkt nu op startscherm EN overlay
- `config.json` - Kleine config aanpassingen

**Waarom:**
Voorheen begon de timer meteen bij het laden van de pagina, wat onhandig is bij voorbereiding van een workshop presentatie. Nu kan de facilitator in alle rust de browser op de beamer zetten voordat het spel daadwerkelijk start.

**Status:**
- Feature volledig werkend en getest
- Klaar voor workshop gebruik met betere controle over presentatie flow

### 2025-11-14 - UI Verbeteringen en Flow Fixes
**Nieuwe features:**
- Stelling counter rechtsonder toegevoegd (toont bijv. "1/8", "2/8" tijdens presentatie)
- Overlay transparantie verhoogd naar 0.4 voor betere leesbaarheid stellingen
- "Volgende stelling" knop verplaatst naar bovenkant (15vh) voor betere zichtbaarheid

**Bug fixes:**
- Laatste stelling flow gefixed: toont nu correct overlay voordat eindscherm verschijnt
- Voorheen ging laatste stelling direct naar finish screen zonder overlay tonen

**Gewijzigde bestanden:**
- `style.css` - Overlay opacity aangepast, knop positie gewijzigd, counter styling toegevoegd
- `app.js` - Statement counter logica toegevoegd, laatste stelling flow aangepast
- `index.html` - Statement counter div toegevoegd

**Waarom:**
Tijdens gebruik bleek de knop onderaan moeilijk leesbaar door de overlay, en de laatste stelling miste de overlay fase waardoor deelnemers geen tijd hadden om te kiezen. Counter helpt facilitator bij het bijhouden van voortgang.

**Status:**
- Alle wijzigingen getest en werkend
- Gecommit en gepusht naar remote (commit e1f1659)
- UX verbeterd voor workshop gebruik

### 2025-12-12 - Stellingkast en Drag & Drop
**Nieuwe features:**
- **Stellingkast:** Nieuw inschuif-paneel in de editor om direct stellingen uit een bibliotheek (`stellingkast.json`) te importeren.
- **Drag & Drop:** Stellingen kunnen nu in de editor versleept worden om de volgorde aan te passen.
- **Cache Busting:** Toegevoegd aan fetch calls om laadproblemen met verouderde JSON bestanden te voorkomen.
- **Validatie:** `stellingkast.json` is opgeschoond en bevat nu valide JSON.

**Gewijzigde bestanden:**
- `editor.html` - HTML structuur voor Stellingkast panel en nieuwe header knop
- `editor.css` - Styling voor slide-in panel, sleep-handvatten en responsive design
- `editor.js` - Logica voor drag & drop, stellingkast import, verbeterde foutafhandeling en loading states
- `stellingkast.json` - Opgeschoond (regelnummers verwijderd)

**Status:**
- Features volledig werkend en getest in browser
- Editor robuuster gemaakt tegen laadfouten

### 2025-12-16 - Workshop Sets Management
**Nieuwe features:**
- **Sets systeem:** Meerdere complete workshop configuraties kunnen opslaan en laden
- **Sets dropdown:** Bovenaan editor voor eenvoudig switchen tussen sets
- **"Opslaan als Nieuwe Set"** knop voor nieuwe configuraties aanmaken
- **Automatische migratie:** Huidige config.json wordt bij eerste gebruik omgezet naar default set
- **Backwards compatibility:** Systeem blijft werken zonder sets.json (legacy fallback)

**Gewijzigde bestanden:**
- `server.py` - Nieuwe endpoints: GET/POST `/api/sets`, helper functies voor sets management
- `editor.html` - Sets sectie met dropdown en knoppen toegevoegd
- `editor.css` - Styling voor sets UI (blauwe border-left accent)
- `editor.js` - Complete sets management logica: laden, switchen, opslaan, nieuwe sets aanmaken
- `config.json` - Blijft actieve configuratie voor presentatie modus

**Nieuwe bestanden:**
- `sets.json` - Database met alle workshop sets (wordt automatisch aangemaakt)

**Hoe het werkt:**
1. Editor openen → Zie dropdown met alle sets
2. Set selecteren → Laadt stellingen en instellingen van die set
3. Bewerken en opslaan → Overschrijft huidige set
4. "Opslaan als Nieuwe Set" → Maakt nieuwe set aan met custom naam
5. Presentatie starten → Gebruikt laatst opgeslagen set uit config.json

**Data structuur sets.json:**
```json
{
  "sets": [
    {
      "id": "default",
      "name": "Standaard Set",
      "config": { /* complete config */ }
    },
    {
      "id": "set-1234567890",
      "name": "PKM Workshop 2025",
      "config": { /* complete config */ }
    }
  ],
  "activeSetId": "default"
}
```

**Waarom:**
Facilitators kunnen nu meerdere workshop configuraties voorbereiden (bijv. verschillende doelgroepen, thema's) en eenvoudig tussen sets wisselen zonder telkens stellingen handmatig te moeten aanpassen.

**Status:**
- Backend endpoints volledig werkend (GET/POST /api/sets)
- Frontend UI en logic compleet geïmplementeerd
- Automatische migratie van bestaande config.json getest
- Sets kunnen worden aangemaakt, geladen, gewijzigd en opgeslagen
- Backwards compatible met oude systeem
- Klaar voor productie gebruik

### 2025-12-17 - Fullscreen Modus
**Nieuwe feature:**
- **Fullscreen knop:** Semi-transparante knop rechtsonder (naast counter) om presentatie in volledig scherm te tonen
- **Toggle functionaliteit:** Klik op knop om fullscreen te activeren/deactiveren
- **Visuele feedback:** Icoon draait 180° wanneer in fullscreen modus
- **ESC toets support:** Browser standaard ESC werkt om fullscreen te verlaten
- **Glasmorphism styling:** Moderne semi-transparante knop met blur effect

**Gewijzigde bestanden:**
- `index.html` - Fullscreen knop met SVG icoon toegevoegd
- `style.css` - Styling voor fullscreen button met hover states en is-fullscreen class
- `app.js` - toggleFullscreen() functie, event listeners voor knop en fullscreenchange
- `README.md` - Documentatie bijgewerkt met fullscreen instructies
- `CLAUDE.md` - Features lijst en Session History bijgewerkt

**Waarom:**
Voor workshop presentaties is het belangrijk dat de browser UI (adresbalk, tabs, bookmarks) niet zichtbaar is op de beamer. De fullscreen knop maakt het eenvoudig om de presentatie volledig scherm te tonen zonder browser elementen.

**Hoe het werkt:**
- Gebruikt Fullscreen API (`document.documentElement.requestFullscreen()`)
- Knop blijft zichtbaar in fullscreen modus voor gemakkelijke toggle
- Event listener voor `fullscreenchange` zorgt voor correcte state sync bij ESC toets
- Icoon rotatie geeft visuele feedback over huidige fullscreen state

**Status:**
- Feature volledig werkend en getest
- Documentatie bijgewerkt (README.md en CLAUDE.md)
- Klaar voor gebruik bij workshop presentaties