# Copilot Instructions

## Product Goal

Build a balanced, production-oriented first milestone for an R36S DLNA browser with Wi-Fi support.

The application must:

- run on R36S-class Linux firmware derived from ArkOS
- use Python for the application logic
- use SDL2 for the user interface and input handling
- discover DLNA/UPnP media servers on the local LAN
- allow hierarchical browsing of remote media content
- support local playback on the device
- stay lightweight enough for RK3326-class hardware

## Balanced Development Plan

Copilot should follow this plan unless the user explicitly changes priorities.

### Phase 1 - Project Bootstrap

- Create a clean Python project layout with a package entrypoint.
- Keep dependencies minimal and explicit.
- Prefer simple run scripts and documentation that also make sense on-device.

### Phase 2 - DLNA Discovery And Browsing

- Implement SSDP discovery for media servers in the LAN.
- Filter and normalize DLNA MediaServer devices.
- Build a ContentDirectory client for browsing containers and media items.
- Support pagination, caching, and safe handling of incomplete metadata.

### Phase 3 - SDL2 User Interface

- Design the UI for 640x480 with readable typography and low visual overhead.
- Optimize navigation for D-pad controls with A/B and shoulder buttons.
- Keep the UI responsive while network operations run asynchronously.

### Phase 4 - Milestone 2: Integrated GStreamer Playback

- Implement playback through GStreamer inside the application process instead of launching an external player subprocess.
- Prefer the system GStreamer stack via `PyGObject` and `GstPlayBin` rather than custom decode loops.
- Prefer decoding video to `GstAppSink` and rendering frames through SDL2 so playback does not depend on a window manager, native overlay sinks, or X11 embedding.
- Support play, pause/resume, stop, relative seek, automatic return to browser on end-of-stream, and explicit error reporting when decode or frame upload fails.
- Keep the architecture ready for follow-up work on on-screen playback HUD, resume state, and device-specific video backend tuning.

### Phase 5 - Milestone 3: SDL Video Viewport, HUD, and Wayland Compatibility

- Reserve an explicit video viewport inside the SDL window and scale decoded video to that viewport instead of using the full window surface.
- Render a full playback HUD in SDL around the video area, including title, state, elapsed/duration, progress, volume, cache/buffer hints, resolution, and visible controls.
- Make the playback HUD controllable with the same device inputs used elsewhere in the app, at minimum covering pause/resume, stop, seek, and volume.
- Prefer SDL backends that work without a window manager on target hardware, especially `kmsdrm` on R36S-class devices.
- If the chosen frame upload path is too slow on target hardware, optimize within the SDL-rendered path rather than falling back to external overlay windows.

### Phase 6 - Device Integration And Hardening

- Handle Wi-Fi instability, timeouts, malformed XML, missing thumbnails, and unsupported media.
- Keep memory use and redraw frequency conservative.
- Document firmware assumptions, runtime prerequisites, and launch steps.

### Phase 7 - Validation

- Add focused tests for parsing, navigation state, and non-UI logic.
- Verify manually on a real LAN and, when possible, on the target device.
- Prefer incremental, testable milestones over broad unfinished features.

## State Tracking Requirements

Copilot must treat development state as a living artifact, not as implicit context.

- Track the current milestone, completed work, in-progress work, blockers, and next steps.
- Keep a repository status file updated during development at `docs/development-status.md`.
- Update that status file whenever a meaningful implementation step is completed, re-scoped, or blocked.
- Record only verified state, not guesses.
- Keep status entries concise, factual, and ordered by relevance to current work.
- If the plan changes, update both the active implementation and the tracked status.

The status file should normally include:

- current milestone
- current architecture decisions
- completed tasks
- tasks in progress
- blockers or open questions
- next recommended actions

## Implementation Preferences

- Favor simple, explicit modules over premature abstraction.
- Separate SDL2 UI concerns from networking and playback concerns.
- Keep async/network code isolated behind small adapters.
- Avoid features that increase complexity before the core browsing flow is stable.
- Prefer integrated GStreamer playback over subprocess control for Milestone 2.
- Prefer SDL-rendered playback from decoded frames over platform-specific window embedding on R36S-class targets.
- For Milestone 3, keep video and HUD in the same SDL render pass so the design remains compatible with DRM/KMS-only environments.

## Quality Bar

- Fix root causes when practical.
- Avoid unrelated refactors.
- Preserve performance on low-end ARM hardware.
- Make every milestone runnable, not just partially scaffolded.
- Treat documentation and development-state tracking as part of the deliverable.