Alpha.7 - Screen Cleaning

.vscode/tasks.json

@@ -111,7 +111,7 @@
 						"permissions": "rw"
 					}
 				],
-					"customOptions": "--user root --label m3undle.run_mode=existing -p 5004:5004 -p 8080:8080 -p 1900:1900/udp -p 65001:65001/udp"
+					"customOptions": "--user root --label m3undle.run_mode=existing -p 5004:5004 -p 8080:8080 -p 1900:1900/udp"
 			},
 			"netCore": {
 				"appProject": "${workspaceFolder}/src/M3Undle.Web/M3Undle.Web.csproj",
@@ -157,7 +157,7 @@
 						"permissions": "rw"
 					}
 				],
-					"customOptions": "--user root --label m3undle.run_mode=force -p 5004:5004 -p 8080:8080 -p 1900:1900/udp -p 65001:65001/udp"
+					"customOptions": "--user root --label m3undle.run_mode=force -p 5004:5004 -p 8080:8080 -p 1900:1900/udp"
 			},
 			"netCore": {
 				"appProject": "${workspaceFolder}/src/M3Undle.Web/M3Undle.Web.csproj",

CHANGELOG.md

@@ -0,0 +1,153 @@
+# Changelog
+
+All notable changes to M3Undle are documented here. Newest release at the top.
+
+---
+
+## [v1.0.0-alpha.7] — 2026-06-05
+
+Alpha 7 is the final alpha milestone. It delivers adaptive live stream recovery for noisy provider channels, a first-class relay policy per provider, significant interface polish across nearly every page, and the consolidated schema migration that closes out all alpha database changes. Beta testing begins after this release.
+
+### Adaptive stream recovery
+
+M3Undle now tracks per-channel stream health across sessions and uses that history to make smarter relay decisions.
+
+- Channels are classified as **Stable**, **Cautious**, or **Unstable** based on observed disconnect and reconnect events
+- Health classification persists in the database — it survives restarts and informs the next session startup
+- Clean-watch duration is tracked after the last adverse event; a channel relaxes one health level after 30 minutes of clean playback
+- At session startup, channel health is loaded before the first upstream connection so the relay decision is already informed before a single byte arrives
+- When clean recovery from an MPEG-TS/H.264 boundary is not safe, M3Undle issues a hard controlled retune instead of continuing with corrupt data
+- Cooldown policy improved to be less aggressive and avoid thrash after a single bad event
+
+### Provider relay policy
+
+Replaced the hidden per-provider "clean remux" toggle with an explicit, user-facing **Relay policy** setting.
+
+- **Auto** — M3Undle decides: direct relay for Stable and Cautious channels, clean relay when channel health is Unstable
+- **On** — always use clean relay regardless of health
+- **Off** — always use direct relay regardless of health
+
+Existing providers migrate automatically: prior `off` rows become `Auto`, prior legacy remux rows become `On`.
+
+The relay policy, startup health classification, and relay decision reason are now visible on the stream monitor for every active session.
+
+### Stream monitor improvements
+
+- Transfer rates (bytes/sec) displayed per session and per connected client
+- Startup health and relay decision reason shown for each active session
+- Sessions display more detailed subscriber information
+
+### Retune compatibility fix
+
+A controlled downstream retune is now suppressed when an internal or Generated HLS relay subscriber is attached to the shared session. A Jellyfin or NextPVR retune no longer kills a concurrent IPTVnator or browser HLS stream that is still active.
+
+### HDHomeRun page
+
+New dedicated HDHomeRun page showing device identity, discovery endpoint, tuning endpoint, and configured tuner count. Makes manual client setup straightforward without hunting through settings.
+
+### About page
+
+New About page with application version, build date, and project links. Fixes #97.
+
+### Dashboard and navigation
+
+- Dashboard reorganized: active profiles are the primary focus, all published endpoint URLs grouped in one place
+- Always-on side drawer for fast navigation between pages without reopening a menu
+- Navigation highlights the currently active page
+- Setup guidance built into the navigation flow to help new users move through provider add, group mapping, and publish in the right order
+- Settings moved to the navigation bar for direct access
+
+### Channel mapping UX
+
+- New providers no longer mark all channels as needing review — only genuinely new channels are flagged
+- Channel tracking progress shown clearly during the mapping workflow
+- Group filter chips normalized with consistent colors and shapes for Pending, Include, Exclude, and New states
+- Group counts and mapped/unmapped states clearer at a glance
+- Fixed a case where adding a provider marked all existing channels and groups as needing review
+
+### Profiles
+
+- Fixed inactive provider issues incorrectly marking active providers as degraded on the Profiles page
+
+### Settings
+
+- Settings page reorganized to make each section easier to understand
+- Authentication and Xtream endpoint settings fixed
+
+### Logs
+
+- Log search and type-based filtering added
+- Actual error text now shown instead of the .NET array type name
+
+### Database and performance
+
+- Slow database load mitigations — the UI detects and displays when the database is not responding
+- UI performance improvements between page transitions
+- Fixed a bug where saving a snapshot could fail under certain conditions
+- All alpha migrations (Alpha 1 through Alpha 7) consolidated into a single baseline migration, removing the startup migration repair path
+
+**Container images**
+
+```text
+ghcr.io/sydney-elvis/m3undle:v1.0.0-alpha.7
+ghcr.io/sydney-elvis/m3undle:alpha
+```
+
+---
+
+## [v1.0.0-alpha.6] — 2026-04-26
+
+Alpha 6 focuses on practical reliability: stronger stream handling for unstable providers, better browser/HLS behavior, first-class observability, Xtream provider detection, and documentation that better matches how people are actually running M3Undle.
+
+### Streaming and HLS reliability
+
+- Hardened shared live stream handling so regular MPEG-TS clients and Generated HLS clients can coexist more predictably
+- Improved HLS session accounting, cleanup, retune behavior, and stream monitor visibility
+- Added stronger internal relay handling for Generated HLS playback, including MPEG-TS relay paths and safer fallback behavior
+- Improved handling for shaky providers with upstream cooldowns, content-stall detection, clean relay support, and MPEG-TS startup boundary handling
+- Fixed cases where HLS or relay sessions could hold stale client counts or make a parent shared stream look idle while playback was still active
+
+### Provider workflow and Xtream compatibility
+
+- Added Xtream-capable endpoint detection when adding providers, with clearer mode guidance in the UI
+- Added provider account and playlist-expiration visibility where the upstream exposes it
+- Improved support for Xtream/Roku-style endpoint behavior and stream URL handling
+- Added per-provider refresh scheduling so provider cadence can be tuned without forcing every profile to follow the same timing
+
+### Observability and diagnostics
+
+- Added Prometheus-compatible metrics with configurable access modes (Disabled, LocalOnly, Token, Public), local CIDR controls, and token-based scraping
+- Added liveness, readiness, and JSON health endpoints for containers, reverse proxies, and uptime checks
+- Added authenticated diagnostics APIs for provider refreshes, streams, lineup state, and EPG behavior
+- Added system event tracking and UI badging so stream/provider problems are easier to see without digging through logs first
+
+### Lineup, guide, and data reliability
+
+- Added the consolidated alpha.6 schema migration with new observability, system event, provider, and scheduling data
+- Improved EPG matching, coverage analysis, and guide handling around refresh/build workflows
+- Fixed guide carry-forward behavior so build-only refreshes do not keep serving an empty guide when cached EPG data is available
+- Added database indexes and service-side cleanup in areas expected to matter more as catalogs grow
+
+### Documentation, UI, and project hygiene
+
+- Reworked the README with current alpha status, Docker guidance, screenshots, endpoint examples, and troubleshooting notes
+- Added dedicated observability documentation covering metrics, probes, diagnostics APIs, labels, and Prometheus examples
+- Updated Docker and GUI documentation around generated HLS storage, endpoint security, refresh schedules, stream proxy settings, and HDHomeRun behavior
+- Continued the CLI/Core split so shared parsing, filtering, provider, EPG, and stream utilities live in the core project instead of the web layer
+
+### Testing
+
+- Expanded focused coverage around stream sharing, Generated HLS, upstream connector behavior, MPEG-TS boundary scanning, observability, refresh scheduling, system events, Xtream/provider handling, and EPG matching
+- Fixed a timing-sensitive CI failure in the HDHR-only subscriber keepalive test
+
+**Container images**
+
+```text
+ghcr.io/sydney-elvis/m3undle:v1.0.0-alpha.6
+ghcr.io/sydney-elvis/m3undle:alpha
+```
+
+---
+
+[v1.0.0-alpha.7]: https://github.com/Sydney-Elvis/M3Undle/compare/v1.0.0-alpha.6...v1.0.0-alpha.7
+[v1.0.0-alpha.6]: https://github.com/Sydney-Elvis/M3Undle/compare/v1.0.0-alpha.5...v1.0.0-alpha.6

README.md

@@ -8,7 +8,7 @@
 [![Release](https://img.shields.io/github/v/release/Sydney-Elvis/M3Undle?include_prereleases&style=flat-square)](https://github.com/Sydney-Elvis/M3Undle/releases/latest)
 [![License](https://img.shields.io/github/license/Sydney-Elvis/M3Undle?style=flat-square)](LICENSE)
 
-[**Sponsor**](https://github.com/sponsors/Sydney-Elvis) | [**Buy Me a Coffee**](https://buymeacoffee.com/jake1164s) | [**Changelog**](https://github.com/Sydney-Elvis/M3Undle/releases) | [**Docker**](https://github.com/Sydney-Elvis/M3Undle/pkgs/container/m3undle)
+[**Sponsor**](https://github.com/sponsors/Sydney-Elvis) | [**Buy Me a Coffee**](https://buymeacoffee.com/jake1164s) | [**Changelog**](CHANGELOG.md) | [**Docker**](https://github.com/Sydney-Elvis/M3Undle/pkgs/container/m3undle)
 
 </div>
 
@@ -26,19 +26,19 @@ Works with clients such as NextPVR, Jellyfin, IPTVnator, IPTV Smarters, and othe
 ![M3Undle dashboard showing system status, active profile, published channel counts, and output URLs](docs/images/readme-dashboard.png)
 
 > [!IMPORTANT]
-> **Alpha Status**
+> **Beta Status**
 >
-> M3Undle has completed Alpha 6. The core workflow is implemented, streaming has been hardened with shared-stream support and relay fallback for unstable providers, and observability endpoints are in place. Alpha 7 is focused on interface polish before moving into beta.
+> M3Undle has completed all alpha milestones and is entering beta. The core workflow is fully implemented: streaming is hardened with shared-stream support, adaptive stream health tracking, and relay policy for unstable providers. Observability, Xtream detection, HDHomeRun integration, and interface polish are all in place.
 >
-> It is stable enough for real LAN testing and personal use, but it is still alpha software. Expect rough edges and possible provider or client-specific issues before beta.
+> Beta focuses on broader DVR client validation, documentation, and final hardening before a stable release. It is suitable for real LAN use, but expect provider- and client-specific edge cases to surface during testing.
 
 ## Run it
 
 M3Undle is published to GitHub Container Registry.
 
-Pull the current alpha image:
+Pull the current beta image:
 
-    docker pull ghcr.io/sydney-elvis/m3undle:alpha
+    docker pull ghcr.io/sydney-elvis/m3undle:beta
 
 Create a working directory:
 
@@ -50,7 +50,7 @@ Create `compose.yaml`:
 
     services:
       m3undle:
-        image: ghcr.io/sydney-elvis/m3undle:alpha
+        image: ghcr.io/sydney-elvis/m3undle:beta
         container_name: m3undle
         ports:
           - "5004:5004"
@@ -82,7 +82,7 @@ Port `8080` serves the web UI, M3U, XMLTV, Xtream, and general compatibility end
 
 The `config` folder is bind-mounted so configuration files stay easy to inspect and back up. Runtime state, logs, snapshots, and browser playback working files use the Docker-managed `m3undle_data` volume.
 
-Use `alpha` for the latest alpha build. Specific release tags are listed on the [M3Undle container registry page](https://github.com/Sydney-Elvis/M3Undle/pkgs/container/m3undle).
+Use `beta` for the latest beta build. Specific release tags are listed on the [M3Undle container registry page](https://github.com/Sydney-Elvis/M3Undle/pkgs/container/m3undle).
 
 `latest` is not used during alpha or beta. It will be introduced no earlier than the release candidate track.
 
@@ -127,7 +127,7 @@ Publish the same managed lineup through M3U, XMLTV, HDHomeRun-compatible, and Xt
 
 ### Streaming
 
-Proxy live streams through M3Undle, hide provider credentials from clients, share live streams across multiple downstream clients, and monitor active stream sessions.
+Proxy live streams through M3Undle, hide provider credentials from clients, share live streams across multiple downstream clients, and monitor active stream sessions. M3Undle tracks per-channel stream health (Stable, Cautious, Unstable) and uses configurable relay policy to handle noisy provider channels without disrupting connected clients.
 
 ![Stream Monitor showing two active sessions with buffer usage and three connected clients sharing streams](docs/images/readme-streams.png)
 
@@ -239,13 +239,13 @@ When reporting an issue, include the M3Undle version tag, Docker compose file wi
 
 ## Roadmap
 
-Alpha 6 is released. Current work is Alpha 7 interface polish before moving into beta.
+All alpha milestones are complete. M3Undle is now in beta.
 
-Planned release path:
+Release path:
 
 1. Alpha 6 — released.
-2. Alpha 7 — interface polish and UX improvements.
-3. Beta — broader testing, documentation cleanup, and client compatibility work.
+2. Alpha 7 — released. Adaptive stream recovery, relay policy, stream health tracking, interface polish, and HDHomeRun improvements.
+3. **Beta — current.** Broader DVR client validation, documentation, and final hardening.
 4. Release candidate — final validation and packaging.
 5. v1.0.0 — stable release.
 

docs/DOCKER.md

@@ -22,7 +22,7 @@ docker compose up -d
 ```yaml
 services:
   m3undle:
-    image: ghcr.io/sydney-elvis/m3undle:alpha
+    image: ghcr.io/sydney-elvis/m3undle:beta
     container_name: m3undle
     user: "${PUID}:${PGID}"
     ports:
@@ -92,7 +92,7 @@ docker run -d \
   -v ./config:/config \
   -v ./data:/data \
   --restart unless-stopped \
-  ghcr.io/sydney-elvis/m3undle:alpha
+  ghcr.io/sydney-elvis/m3undle:beta
 ```
 
 ---
@@ -463,7 +463,7 @@ For auto-discovery to work identically to a real HDHomeRun (including from other
 ```yaml
 services:
   m3undle:
-    image: ghcr.io/sydney-elvis/m3undle:alpha
+    image: ghcr.io/sydney-elvis/m3undle:beta
     container_name: m3undle
     network_mode: host
     environment:
@@ -538,12 +538,11 @@ Database migrations run automatically on startup.
 
 | Tag | Tracks | Notes |
 |---|---|---|
-| `v1.0.0-alpha.1` | Exact version — immutable | Pin to this if you want full control over updates |
-| `alpha` | Latest alpha release | Moves forward as new alpha builds are published |
-| `beta` | Latest beta release | Available from v1.0.0-beta.1 |
+| `v1.0.0-beta.1` | Exact version — immutable | Pin to this if you want full control over updates |
+| `beta` | Latest beta release | Moves forward as new beta builds are published |
 | `latest` | Latest **stable** release | Not published until v1.0.0 — do not use during pre-release |
 
-**Current phase:** alpha — use the `alpha` tag or pin to a specific version like `v1.0.0-alpha.1`.
+**Current phase:** beta — use the `beta` tag or pin to a specific version like `v1.0.0-beta.1`.
 
 `latest` does not exist yet. Pulling it will return "image not found".
 

docs/GUI.md

@@ -11,6 +11,8 @@ The interface emphasizes:
 - Clear visibility
 - No hidden logic
 
+UI consistency rules used by contributors and AI agents are documented in `docs/dev/GUI_CONSISTENCY_CONTRACT.md`.
+
 ---
 
 ## UI Sections
@@ -27,6 +29,7 @@ Configuration includes:
 - Timeout settings
 - Enabled/disabled toggle
 - Optional per-provider max concurrent stream limit
+- Relay policy — controls how M3Undle handles the stream from this provider: **Auto** (applies clean relay for channels classified as Unstable), **On** (always clean relay regardless of health), or **Off** (direct relay only)
 
 The UI shows:
 
@@ -153,6 +156,8 @@ When the simultaneous-stream cap is full, zero-viewer streams waiting in their d
 
 MPEG-TS CDN-gap handling is automatic. M3Undle can send null-packet keepalives for external non-HDHomeRun players during short upstream gaps, while HDHomeRun-only sessions are left as plain upstream MPEG-TS for DVR compatibility. The advanced content-stall timeout for that behavior is configured through appsettings/environment variables rather than the UI.
 
+M3Undle tracks per-channel stream health across sessions. Each channel is classified as **Stable**, **Cautious**, or **Unstable** based on observed disconnect and recovery events, and that classification persists in the database. The stream monitor shows the startup health and relay policy decision for each active session so you can see which channels are being handled with additional relay protection.
+
 For HDHomeRun-style access, tuner ownership is tracked by the configured `Virtual Tuner ID`, not by remote IP. Re-tuning from the same virtual tuner replaces the prior playback session instead of consuming another tuner slot.
 
 **Browser Playback**
@@ -272,6 +277,27 @@ The **Manage Numbers** button in the page header switches the page into Number M
 
 ---
 
+### 9. HDHomeRun
+
+The HDHomeRun page shows the M3Undle device identity and endpoint URLs for clients that use HDHomeRun-compatible device discovery.
+
+It displays:
+
+- Device name, device ID, and firmware version (as presented to HDHomeRun clients)
+- Discovery endpoint URL (`http://<host>:5004/discover.json`)
+- Tuning endpoint URL (`http://<host>:5004/lineup.json`)
+- Configured tuner count
+
+Use this page to confirm your HDHomeRun setup and copy the tuner URL for manual client configuration. Auto-discovery depends on Docker networking and multicast; manual setup using the URL shown here is generally more reliable.
+
+---
+
+### 10. About
+
+The About page shows product information: application version, build date, and links to the project home and license.
+
+---
+
 ## UI Design Goals
 
 The Web UI is built around the following principles:

docs/design/DB_SCHEMA.md

@@ -31,7 +31,7 @@
 - created_utc (TEXT)
 - updated_utc (TEXT)
 
-Note: `providers.is_active` was removed in migration `Alpha6_ActiveProfile`. Active state now lives on `profiles.is_active`.
+Note: active state lives on `profiles.is_active`.
 
 Indexes:
 - idx_providers_enabled(enabled)

docs/dev/ALPHA5_VALIDATION_CHECKLIST.md

@@ -45,7 +45,7 @@ Legend: `[ ]` not started | `[x]` passed | `[!]` failed / investigate
 - [x] Make `ChannelSessionManager.RemoveIfClosedAsync()` atomic
 - [x] Add a transaction around `ProfilesPageService.DeleteProfileAsync()`
 - [x] Block disabled profiles from being activated in `ProfilesPageService.SetProfileActiveAsync()`
-- [x] Harden `20260404000000_Alpha6_ActiveProfile` migration table rebuild behavior
+- [x] Harden active-profile schema handling
 
 ## Post-Review Medium Coverage (2026-04-10)