This page describes the WinUI migration as of September 22, 2026. The native Windows shell, the older Tauri/Vue app, and the website’s web player are separate entry points.
Three layers
| Layer | Location | Responsibility |
|---|---|---|
| Windows shell | src-winui/OFPlayer.WinUI |
XAML navigation, library lists and grids, settings, dialogs, system media session |
| C# core and transport | src-winui/OFPlayer.WinUI.Core |
Host protocol, stdio transport, state merging, output devices, application policy |
| Rust native host | src-tauri/src/native_host.rs, native_session.rs |
Database, import and scanning, queue, decoding and output, remote media, device handoff |
Immersive playback and Lyric Capsule reuse Vue views inside WebView2. They receive host playback state; they do not own another queue.
Navigation and state
SourcePickerView switches local libraries and remote connections. MainWindow owns the sidebar, and LibraryPageView shows local tracks, remote entries, and grouped grids. The data hierarchy is library → playlist → track. Recent, Favorites, and Queue are smart views. Album and artist groups come from tags; artist drill-down must keep its artist filter so same-named albums do not mix tracks.
The Catalog, Management, Playback, Remote, and Hub portions of MainViewModel coordinate UI and host calls. Assign state to the appropriate owner instead of creating another playback authority in a XAML event handler.
Playback and events
C# sends user requests to the Native Host. One native session owns the queue and playback. Host events update the main playback bar, Windows media session, immersive view, and capsule. Progress and meter events can be coalesced; critical state transitions must remain observable. The capsule meter comes from the audio engine. Serve artwork through controlled WebView2 resource paths, not arbitrary local file URLs.
Data and network boundary
NativeHostService uses a separate WinUI preview data directory by default and allows an explicit override. The host holds an exclusive cross-process database lock. Browser IndexedDB is unrelated. The desktop stdio channel requires no listening network port; enabling LAN phone handoff starts a separate, explicit network service.
Web theme tokens do not style native XAML directly, and lyric effects are not yet identical across views. An update-check or license display model is not proof of a complete install or entitlement flow. See Windows version status, Host protocol, and Build locally.