katrain-qt/TODO.md

Qt Port TODO

Completed

• Remove Kivy and katrain.gui imports from katrain/core.
• Replace direct core-to-widget calls with framework-neutral events.
• Move Kivy language observation, widget fonts, PV markup, and UI updates into Kivy adapters.
• Preserve behavior with core-boundary, parser, board, AI, and remote-engine tests.

1. Finish Core Host Separation

• Define Protocol types for the remaining host contract: configuration, logging, player/session state, and event delivery.
• Change BaseGame, engines, contribution code, and AI helpers to accept those narrow dependencies instead of an untyped katrain object.
• Move game/session ownership (game, pondering, active-game replacement) into a framework-neutral application controller.
• Replace engine-thread callbacks that mutate game state directly with controller-dispatched work.
• Add unit tests for event ordering, thread dispatch boundaries, configuration migration/backup, and translator fallback.

Done when katrain/core has no dependency on a concrete application object and can be embedded by a non-Kivy command-line test host.

2. Establish the Qt Application Shell

• Add PySide6 as the frontend dependency and create a Qt entry point without importing Kivy.
• Implement Qt versions of the core event sink and language adapter using queued Qt signals.
• Create application/session, configuration, engine-lifecycle, and error/recovery controllers.
• Add a minimal window with startup/shutdown, settings loading, KataGo restart, and localized status display.
• Confirm all core-originated UI events execute on the Qt main thread.

Done when Qt can open a window, start/stop KataGo, show engine failures, and load persisted settings without loading Kivy.

3. Build the Game Workspace

• Implement board rendering with independent board, black-stone, and white-stone image selection plus stone variants.
• Implement move entry, navigation, branches, insert mode, region-of-interest selection, and undo/redo.
• Implement the move tree, candidate moves, principal variation interaction, ownership display, and analysis graph.
• Implement SGF open/save, recent paths, metadata, comments, and generated analysis feedback.
• Add component and controller tests for SGF round trips, navigation, analysis refresh, and thread-safe redraws.

Done when an existing SGF can be opened, analyzed, navigated, edited, and saved from the Qt UI.

4. Port Play, Teaching, and Training

• Implement player setup, AI strategy settings, human-like model settings, and play-versus-AI flow.
• Implement timer behavior, mistake coloring, sounds where supported, teaching undo, and training feedback.
• Implement self-play/setup-game workflows and analysis modes: extra, sweep, equalize, alternatives, local, and full-game reanalysis.
• Implement tsumego frame generation and region analysis UI.
• Add deterministic controller tests with fake engines; keep KataGo strategy coverage as an integration test.

Done when normal play, teaching, and training use cases work at parity with the required functionality list in AGENTS.md.

5. Port Settings, Localization, and Remote Engine Support

• Build Qt settings dialogs for general, engine, AI, timer, and trainer configuration.
• Connect locale switching to Qt retranslation and per-language font selection.
• Build remote-engine configuration, reconnect status, warnings, and recovery UI using core events.
• Test custom, local, and remote engine backend selection without widget mocks.

Done when settings changes persist and apply immediately, language changes retranslate the active UI, and remote recovery is visible in Qt.

6. Release Readiness

• Add a core-only CI job that runs without Kivy installed.
• Add a Qt headless smoke-test job and keep KataGo integration tests separately marked.
• Run KataGo integration tests with RUSTICL_ENABLE=radeonsi; rerun the tuner after changing KataGo, its model, or analysis config.
• Remove Kivy runtime/build dependencies only after Qt reaches required-feature parity.
• Document packaging for Linux/Wayland and supported KataGo asset locations.

Done when the Qt frontend passes its smoke/integration suites and can be packaged without a Kivy runtime dependency.