R36SHack/.github/copilot-instructions.md

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.