Kiwy-Signage/windows/development-track.md

# 🧪 Development Track — Kiwy Signage Player (Windows Edition)

> This file tracks every change, bug fix, tested solution, build info, and
> pending issues for the Windows port. Read this FIRST before starting any
> debugging or coding session.

---

## 📅 Current Session — 2026-07-24

| Field | Value |
|-------|-------|
| **Branch** | `Windows-Player` |
| **Python** | 3.12.9 — `C:\Users\Dell-PC\AppData\Local\Programs\Python\Python312\python.exe` |
| **Venv** | `windows\venv312\` (pre-built, all deps installed) |
| **Kivy** | 2.3.1 |
| **PyInstaller** | 6.21.0 |
| **Last .exe build** | 2026-07-24 13:47 — `windows\dist\KiwySignagePlayer\KiwySignagePlayer.exe` (96 MB) |
| **Build command** | `Set-Location windows; venv312\Scripts\python.exe -m PyInstaller build.spec --clean --noconfirm` |

### ⚠️ Python Version Constraints
- **Python 3.12.9** — ✅ Confirmed working. Has pre-built Kivy 2.3.1 wheels.
- **Python 3.13** — ❌ Kivy wheels NOT available for Windows.
- **Python 3.14** — ❌ Tested 2026-07-24. `kivy_deps.sdl2_dev~=0.8.0` has no cp314 wheel.
  → Solution: removed Python 3.14 from system, keeping only 3.12.9.

---

## 🐛 Bug Tracker

### [BUG-001] RecursionError: play_current_media ↔ restart_playlist
- **Status:** ✅ Fixed 2026-07-24
- **Symptom:** Pressing "Restart Player" in settings with empty playlist causes
  infinite recursion: `play_current_media → restart_playlist → play_current_media → ...`
- **Fix:** Added empty-playlist guard in both `play_current_media()` and
  `restart_playlist()` → they return early instead of calling each other.
- **Files:** `src/main.py` — lines ~1304 and ~2073
- **Test:** Verified no Python syntax errors via `ast.parse`.

### [BUG-002] Settings fields cut off on small screens
- **Status:** ✅ Fixed 2026-07-24
- **Symptom:** "Screen Name", "Quickconnect" and other fields at the top of
  the settings popup are invisible on smaller resolutions because content
  overflows the popup.
- **Fix:** Wrapped settings content in a `ScrollView`. Moved "Save & Close" /
  "Cancel" buttons outside the scroll (always visible). Reduced row heights.
- **Files:** `src/signage_player.kv` — `<SettingsPopup@Popup>` block

### [BUG-003] Chromium not fullscreen on Windows
- **Status:** ✅ Fixed 2026-07-24
- **Symptom:** Web links open in a small window instead of fullscreen.
- **Fix:** Changed launch args from `--kiosk` to `--start-maximized --app=URL`
  + explicit `--window-size=WxH`. `--kiosk` uses Wayland exclusive-fullscreen
  protocol which doesn't work on Windows.
- **Tested rejected solutions:**
  - ❌ `--kiosk` alone → small window, no fullscreen
  - ❌ `--start-fullscreen` alone → not reliable
  - ✅ `--start-maximized --app=URL --window-size=...` → works
- **Files:** `windows/run_win.py` — `_windows_play_weblink()`

### [BUG-004] Desktop flash when switching between Chromium and Kivy
- **Status:** ✅ Fixed 2026-07-24
- **Symptom:** When Chrome closes, the desktop is briefly visible before Kivy
  reappears. Also when Chrome opens, there's a flash.
- **Fix:** Added `_Win32Overlay` class — a fullscreen black Win32 window that
  covers the screen during transitions. Shown BEFORE closing Chrome / opening
  Chrome, hidden AFTER Kivy is ready.
- **Tested rejected solutions:**
  - ❌ `Window.raise_window()` alone → still shows flash
  - ✅ Win32 black overlay → smooth masking
- **Files:** `windows/run_win.py` — `_Win32Overlay` class

### [BUG-005] Chrome processes linger after closing weblink
- **Status:** ✅ Fixed 2026-07-24
- **Symptom:** After a weblink item ends, Chrome child processes (GPU,
  renderer) remain running → blank windows accumulate.
- **Fix:** Use `taskkill /F /T /PID <pid>` to kill the entire process tree.
- **Tested rejected solutions:**
  - ❌ `proc.terminate()` → leaves children running
  - ❌ `proc.kill()` → same problem
  - ✅ `taskkill /F /T` → kills everything
- **Files:** `windows/run_win.py` — `_windows_kill_process_tree()`

### [BUG-006] Video plays in background behind Chromium
- **Status:** 🟡 **Known, needs investigation**
- **Symptom:** When transitioning from a weblink back to a video, the video
  starts playing while Chromium is still visible (audio plays, video is behind
  Chrome window).
- **Possible causes:**
  1. `_kill_weblink_after_frame` delay is too short — Kivy renders the video
     before Chrome is killed
  2. `Window.raise_window()` is not working reliably on Windows to bring
     Kivy to front
  3. Chrome's `--kiosk` / `--start-maximized` keeps it on top
  4. The `content_area.opacity` manipulation happens too early/late
- **Current approach:** `_windows_kill_weblink_after_frame()` shows overlay,
  kills Chrome tree, raises Kivy, hides overlay.
- **Next thing to test:** Use `user32.SetForegroundWindow(KivyHwnd)` instead
  of `Window.raise_window()`. Get Kivy's HWND via `Window.get_window_info()`.

---

## 🧪 Tested & Rejected Solutions Log

> Keep a record of approaches that were tried and didn't work, so we don't
> waste time re-testing them.

| Date | What was tested | Result | Reason it failed |
|------|----------------|--------|-----------------|
| 2026-07-24 | Python 3.14 with Kivy | ❌ | `kivy_deps.sdl2_dev~=0.8.0` has no cp314 wheel |
| 2026-07-24 | `--kiosk` Chrome flag on Windows | ❌ | Not fullscreen, Wayland exclusive-fullscreen not available |
| 2026-07-24 | `--start-fullscreen` alone | ❌ | Inconsistent, sometimes not full |
| 2026-07-24 | `proc.terminate()` for Chrome | ❌ | Leaves child processes running |
| 2026-07-24 | `proc.kill()` for Chrome | ❌ | Same as terminate — children survive |
| 2026-07-24 | `Window.raise_window()` for transition | ❌ | Brief desktop flash visible |

---

## 📁 Data Directory Behaviour

When the .exe runs:
1. Runtime hook (`pyi_runtime_hook.py`) sets `KIWY_DATA_DIR = exe_dir`
2. `run_win.py` patches `SignagePlayer.__init__` to use `KIWY_DATA_DIR`
3. Local folders created next to the .exe:
   ```
   KiwySignagePlayer.exe
   config/
     app_config.json
     resources/  (icons, intro video)
     certs/      (SSL certificates)
   media/
     edited_media/
   playlists/
   logs/
   .kivy/        (Kivy home)
   .player_heartbeat
   ```

---

## 🔧 Build Cheatsheet

```powershell
# Build the .exe (from project root or windows/)
Set-Location windows
& .\venv312\Scripts\python.exe -m PyInstaller build.spec --clean --noconfirm

# Run in dev mode (no build needed)
& .\venv312\Scripts\python.exe run_win.py

# Test imports only
& .\venv312\Scripts\python.exe test_import_fix.py
```

---

## 📝 Notes for the Next Session

- [ ] Investigate [BUG-006] — video playing behind Chromium
- [ ] Test if `SetForegroundWindow` works better than `Window.raise_window()`
- [ ] Consider adding a startup `.bat` file that users can double-click
- [ ] Check if the intro video plays correctly on Windows
- [ ] Test card reader fallback behaviour (evdev not available)