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 |
| **Libraries added** | `cefpython3` (embedded Chromium), `pywin32` 312 (win32gui for window mgmt) |
| **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-007] Video plays behind Chromium on weblink→media transition
- **Status:** 🔧 **Fix in progress** 2026-07-24
- **Symptom:** When a weblink ends and the next media starts, the media plays
  *behind* Chromium. Audio is heard but user sees Chrome.
- **Root cause (Windows):** Linux renders Kivy widget UNDER Chromium → closes
  Chrome → widget visible. On Windows Chrome stays ON TOP.
  `Window.raise_window()` is unreliable.
- **Fix applied (2026-07-24):**
  1. **`_bring_kivy_to_front()`** — uses `win32gui.SetForegroundWindow(hwnd)`
     to reliably bring Kivy/SDL window to front (replaces `raise_window`)
  2. **`_windows_kill_weblink_after_frame()`** — kills Chrome IMMEDIATELY
     (not deferred one frame later) before next media starts
  3. **CEF browser** (`cefpython3`) — embedded Chromium widget replaces
     subprocess entirely. No process management, no z-order fights.
- **Files:** `windows/run_win.py`, `windows/cef_browser.py`

### [BUG-008] Intro video and media files not found at runtime
- **Status:** ✅ **Fixed** 2026-07-24
- **Symptom:** `[ERROR] [Image] Error loading <...intro1.mp4>` — intro
  broken. Also `❌ Media file not found` for playlist items.
- **Root cause:** Media download only ran when `server_version > local_version`.
  When versions matched (v16 == v16), `download_media_files` was never called
  → media folder stayed empty.
- **Fix:** Added download check in the "up to date" branch — now downloads
  missing media files even when playlist version hasn't changed.

### [BUG-009] Video never advances to next item (EOS handler empty)
- **Status:** ✅ **Fixed** 2026-07-24
- **Symptom:** Video plays but never advances to the next playlist item.
- **Root cause:** `_on_video_eos()` callback was a stub — just logged
  "Video finished playing (EOS)" but never called `next_media()`.
- **Fix:** Added `Clock.unschedule(self.next_media)` + `Clock.schedule_once`
  to advance after 0.5s when a video reaches end of stream.

---

## 🧪 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

- [x] ~~Investigate [BUG-006]~~ → merged into [BUG-007], fixed with CEF + win32gui
- [x] ~~Test `SetForegroundWindow`~~ → `_bring_kivy_to_front()` uses `win32gui`
- [x] Install `cefpython3` — embedded Chromium, no more subprocess
- [ ] Verify CEF embedded browser actually works at runtime
- [ ] Test the subprocess fallback path when CEF is unavailable
- [ ] Check why `AsyncImage` error shows for intro1.mp4 (path issue)
- [ ] Ensure media files are downloaded before playback
- [ ] Consider adding a startup `.bat` file that users can double-click
- [ ] Test card reader fallback behaviour (evdev not available)
- [ ] Add `cef_browser.py` to PyInstaller hidden imports in `build.spec`