Release 5.8.2 beta 7 diagnostics fallback

Author: r11a

CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 5.8.2-beta.7 - 2026-06-02
+
+Targeted beta follow-up for issue #28, Diagnostic v3, and the phone Queue Flow entry point.
+
+Release focus:
+
+- Keeps HOMEii usable through the Home Assistant Music Assistant integration when HA exposes `music_assistant` services even if config entry lookup returns `not_loaded`.
+- Allows generic HA `media_player` entities as Music Assistant compatibility fallback targets only when the integration service signal exists.
+- Upgrades in-card and visual-editor diagnostics to Diagnostic v3 with integration signal, strict/fallback player counts, selected-player markers, queue providers, library providers, browser context, Direct API, and Sendspin checks.
+- Classifies browser-blocked Direct API failures such as CORS/preflight or `Failed to fetch` as optional access-path warnings when the HA integration is available.
+- Removes the phone Queue Flow button above the artwork and keeps Queue Flow available through Quick Actions.
+- Removes the invalid `limit` payload from the HA `music_assistant.get_queue` queue snapshot path.
+- Keeps diagnostics privacy redaction for external/private hostnames.
+
+Validation:
+
+- Targeted lint and runtime/settings regression tests were run before the release version bump.
+- Full lint, full Vitest, production build, and release artifact sync were run for the final beta package.
+
 ## 5.8.2-beta.6 - 2026-06-02
 
 Cache-busting beta rebuild for the Diagnostic v2 privacy and queue-artwork fixes from beta 5.

README.md

@@ -47,7 +47,7 @@ https://github.com/user-attachments/assets/a0076e6e-0352-40f8-ac37-35737e717a80
 
 <p align="center">
   <a href="https://github.com/r11a/homeii-music-flow"><img alt="stable version" src="https://img.shields.io/badge/stable-5.8.1-gold"></a>
-  <a href="https://github.com/r11a/homeii-music-flow/releases/tag/v5.8.2-beta.6"><img alt="beta version" src="https://img.shields.io/badge/beta-5.8.2--beta.6-8A63D2"></a>
+  <a href="https://github.com/r11a/homeii-music-flow/releases/tag/v5.8.2-beta.7"><img alt="beta version" src="https://img.shields.io/badge/beta-5.8.2--beta.7-8A63D2"></a>
   <img alt="Home Assistant" src="https://img.shields.io/badge/Home%20Assistant-Dashboard-41BDF5">
   <img alt="Music Assistant" src="https://img.shields.io/badge/Music%20Assistant-required-7C5CFF">
   <img alt="Sendspin" src="https://img.shields.io/badge/Sendspin-browser%20player-18B6FF">
@@ -63,26 +63,24 @@ HOMEii Flow is a custom Home Assistant Dashboard card for Music Assistant. It tu
 
 HOMEii Flow started from my own daily use of Home Assistant and Music Assistant. I wanted it to feel less like a technical dashboard widget and more like a real music app inside Home Assistant, so a lot of thought went into the flow, touch interactions, Hebrew/RTL comfort, wall-tablet behavior, mobile details, and the small moments that make choosing music feel natural at home.
 
-## 5.8.2 Beta 6
+## 5.8.2 Beta 7
 
-HOMEii Flow 5.8.2 Beta 6 is a cache-busting pre-release follow-up for Diagnostic v2 privacy, visual-editor diagnostics, queue-artwork diagnostics, and Home Assistant integration-first operation.
+HOMEii Flow 5.8.2 Beta 7 focuses on issue #28, Diagnostic v3, and a cleaner phone Queue Flow entry point.
 
-- Upgrades Settings > Music Assistant > Diagnostics to Diagnostic v2 with browser, viewport, access path, Direct MA, Sendspin, queue, library, and artwork checks.
-- Adds a Diagnostics button to the Home Assistant visual editor near the version label.
-- Keeps diagnostics visible with green OK, red FAIL, yellow WARN, and blue INFO rows, plus a copyable report for GitHub issues.
-- Redacts external/private hostnames in diagnostics output by default while keeping protocol, host type, port, and path category for troubleshooting.
-- Adds queue-artwork diagnostics alongside the existing library-artwork checks.
-- Adds a close button to the visual-editor diagnostics panel.
-- Treats the Home Assistant Music Assistant integration as the primary supported path, so the card can keep working normally even when Direct MA access is not configured.
-- Avoids broken artwork placeholders caused by Music Assistant `/imageproxy` paths when the browser cannot directly reach Music Assistant.
-- Keeps the Beta 1 through Beta 5 artwork, Music Assistant compatibility, Danish localization, diagnostics, and performance fixes.
+- Lets the card keep working through the Home Assistant Music Assistant integration even when the MA config entry lookup reports `not_loaded` but HA still exposes `music_assistant` services.
+- Uses generic HA `media_player` entities as compatibility fallback targets only when Music Assistant services exist.
+- Improves diagnostics to Diagnostic v3 with integration signals, strict/fallback player markers, queue providers, library providers, browser-blocked Direct API classification, and the existing privacy redaction.
+- Treats browser-blocked Direct API/CORS failures as optional when the HA integration path is available, instead of making the whole card look broken.
+- Removes the phone Queue Flow button above the artwork and keeps Queue Flow available only as a Quick Action option.
+- Removes the invalid `limit` parameter from the HA `music_assistant.get_queue` diagnostic path.
+- Keeps the Beta 1 through Beta 6 artwork, Music Assistant compatibility, Danish localization, diagnostics, and performance fixes.
 
-Beta download: [v5.8.2-beta.6](https://github.com/r11a/homeii-music-flow/releases/tag/v5.8.2-beta.6)
+Beta download: [v5.8.2-beta.7](https://github.com/r11a/homeii-music-flow/releases/tag/v5.8.2-beta.7)
 
 Stable users can remain on 5.8.1. Beta users should hard refresh Home Assistant or use:
 
 ```text
-/local/community/homeii-music-flow/homeii-music-flow.js?v=5.8.2-beta.6
+/local/community/homeii-music-flow/homeii-music-flow.js?v=5.8.2-beta.7
 ```
 
 ## 5.8.1 Hotfix Release
@@ -1026,7 +1024,8 @@ src/core/                             extracted foundation helpers
 src/config/                           config validators
 tests/                                regression coverage
 scripts/release.mjs                   release sync tooling
-RELEASE_NOTES_5.8.2-beta.6.md         detailed GitHub release notes for the current beta
+RELEASE_NOTES_5.8.2-beta.7.md         detailed GitHub release notes for the current beta
+RELEASE_NOTES_5.8.2-beta.6.md         previous beta release notes
 RELEASE_NOTES_5.8.2-beta.5.md         previous beta release notes
 RELEASE_NOTES_5.8.2-beta.4.md         previous beta release notes
 RELEASE_NOTES_5.8.2-beta.3.md         previous beta release notes
@@ -1051,7 +1050,7 @@ npm run lint
 npm test
 ```
 
-Current packaged version: `5.8.2-beta.6`
+Current packaged version: `5.8.2-beta.7`
 
 ## Release Readiness
 
@@ -1105,6 +1104,7 @@ Credit and thanks:
 
 - [Local deployment guide](./LOCAL_DEPLOYMENT.md)
 - [Publishing checklist](./PUBLISHING.md)
+- [5.8.2 Beta 7 release notes](./RELEASE_NOTES_5.8.2-beta.7.md)
 - [5.8.2 Beta 6 release notes](./RELEASE_NOTES_5.8.2-beta.6.md)
 - [5.8.2 Beta 5 release notes](./RELEASE_NOTES_5.8.2-beta.5.md)
 - [5.8.2 Beta 4 release notes](./RELEASE_NOTES_5.8.2-beta.4.md)

RELEASE_NOTES_5.8.2-beta.7.md

@@ -0,0 +1,27 @@
+# HOMEii Music Flow 5.8.2-beta.7
+
+This beta focuses on issue #28, Diagnostic v3, and a cleaner phone Queue Flow entry point.
+
+## Fixed
+
+- Keeps the card usable through the Home Assistant Music Assistant integration when `music_assistant` services are available even if the config entry lookup reports `not_loaded`.
+- Uses generic HA `media_player` entities as compatibility fallback targets only when Music Assistant services are exposed by Home Assistant.
+- Treats browser-blocked Direct API failures such as CORS/preflight or `Failed to fetch` as optional Direct/Sendspin access-path warnings when the HA integration can still run core card features.
+- Removes the invalid `limit` payload from the HA `music_assistant.get_queue` queue snapshot path.
+- Removes the phone Queue Flow button above the artwork. Queue Flow remains available from Quick Actions.
+
+## Added
+
+- Upgrades in-card and visual-editor diagnostics to Diagnostic v3.
+- Adds integration signal reporting, strict/fallback player counts, selected-player marker details, queue provider checks, and library provider checks.
+- Keeps privacy redaction for Home Assistant, Music Assistant, Sendspin, and artwork hostnames.
+
+## Testing Notes
+
+After installing, hard refresh the Home Assistant dashboard and make sure the Lovelace resource URL/cache key is updated to:
+
+```text
+/local/community/homeii-music-flow/homeii-music-flow.js?v=5.8.2-beta.7
+```
+
+For artwork/queue/library issues, open the card, go to Settings > General, set Settings Source to In-card Settings, then run Settings > Music Assistant > Diagnostics and paste the copied Diagnostic v3 report into the GitHub issue.

dist/config/editor-element.js

@@ -391,11 +391,20 @@ return class HomeiiBaseMusicEditor extends HTMLElement {
     return raw?.result ?? raw;
   }
 
+  _editorDirectApiFailureDetail(error = null) {
+    const detail = String(error?.message || error || "").trim();
+    const lower = detail.toLowerCase();
+    if (lower.includes("failed to fetch") || lower.includes("networkerror") || lower.includes("cors") || lower.includes("preflight")) {
+      return "Direct Music Assistant API is blocked by the browser before HOMEii receives a response. This is usually CORS/preflight or local-network browser access. Core playback can still work through the Home Assistant integration; leave ma_url empty unless you need Direct API or Sendspin.";
+    }
+    return detail || "Direct API request failed.";
+  }
+
   _editorDiagnosticsReportText(items = []) {
     const maUrl = this._editorMaBrowserUrl();
     const lines = [
       "HOMEii Music Flow Editor Diagnostics",
-      "Diagnostics: v2",
+      "Diagnostics: v3",
       `Version: ${HOMEII_CARD_VERSION}`,
       `Generated: ${new Date().toISOString()}`,
       "Source: visual editor",
@@ -467,18 +476,21 @@ return class HomeiiBaseMusicEditor extends HTMLElement {
     const entities = this._hass?.entities || {};
     const players = Object.values(states)
       .filter((entity) => HomeiiPlayersFoundation.isMusicAssistantPlayer(entity, entities?.[entity.entity_id]));
+    const genericPlayers = Object.values(states)
+      .filter((entity) => entity?.entity_id?.startsWith?.("media_player."));
     const pinned = HomeiiMobileSettingsFoundation.normalizePinnedPlayerEntityList(this._config?.pinned_player_entities);
     const excluded = HomeiiMobileSettingsFoundation.normalizePinnedPlayerEntityList(this._config?.excluded_player_entities);
 
     add("ok", "Editor version", "Visual editor runtime is loaded.", HOMEII_CARD_VERSION);
-    add("ok", "Diagnostics version", "Diagnostic v2 is active.", "v2");
+    add("ok", "Diagnostics version", "Diagnostic v3 is active.", "v3");
     add("info", "Browser", this._editorBrowserSummary());
     add("info", "Viewport", this._editorViewportSummary());
     add("info", "Diagnostic privacy", "External/private hostnames are redacted in visible and copied diagnostic output.");
     add(this._hass ? "ok" : "fail", "Home Assistant frontend", this._hass ? "Editor has a Home Assistant frontend object." : "Editor does not have a Home Assistant frontend object.");
     add(services.length ? "ok" : "fail", "Music Assistant services", services.length ? `${services.length} service(s) are exposed by Home Assistant.` : "No music_assistant services are exposed by Home Assistant.");
     add(services.length ? "ok" : "warn", "Integration mode", services.length ? "Core card features can run through Home Assistant. HTTP/HTTPS only affects optional Direct/Sendspin browser access." : "Home Assistant does not expose music_assistant services.");
-    add(players.length ? "ok" : "warn", "Music Assistant players", `${players.length} player(s) visible in HA state.`);
+    add(services.length || maUrl ? "ok" : "fail", "Integration signal", `services ${services.length ? "yes" : "no"}, direct ${maUrl ? "configured" : "empty"}`);
+    add(players.length ? "ok" : (services.length && genericPlayers.length ? "warn" : "fail"), "Music Assistant players", players.length ? `${players.length} strict MA player(s), ${genericPlayers.length} generic HA media_player(s).` : `${genericPlayers.length} generic HA media_player(s), but no strict Music Assistant player markers were detected.`);
     add("info", "Player filters", `${pinned.length} pinned, ${excluded.length} excluded.`);
 
     if (this._hass?.connection?.sendMessagePromise) {
@@ -515,7 +527,7 @@ return class HomeiiBaseMusicEditor extends HTMLElement {
         const count = Array.isArray(rawPlayers) ? rawPlayers.length : (Array.isArray(rawPlayers?.players) ? rawPlayers.players.length : 0);
         add("ok", "Direct Music Assistant API", `Direct API responded with ${count} player(s).`);
       } catch (error) {
-        add("fail", "Direct Music Assistant API", error?.message || "Direct API request failed.");
+        add(services.length ? "warn" : "fail", "Direct Music Assistant API", this._editorDirectApiFailureDetail(error));
       }
     } else {
       add("info", "Direct Music Assistant API", maUrl ? "Skipped because ma_url needs attention." : "Skipped because ma_url is empty.");

dist/config/editor-forms.js

@@ -184,6 +184,7 @@ export function getMobileEditorTexts() {
     { value: "like", label: homeiiEditorI18n("ui.like_2") },
     { value: "lyrics", label: homeiiEditorI18n("ui.lyrics") },
     { value: "queue", label: homeiiEditorI18n("ui.queue_2") },
+    { value: "queue_flow", label: homeiiEditorI18n("ui.mobile_queue_flow", {}, "Fast queue wheel") },
     { value: "radio", label: homeiiEditorI18n("ui.quick_mix") },
     { value: "voice", label: homeiiEditorI18n("ui.flow_assistant", {}, "FLOW ASSISTANT") },
     { value: "history", label: homeiiEditorI18n("ui.history") },
@@ -229,6 +230,7 @@ export function getMobileEditorTexts() {
       mobile_compact_widget_mode: homeiiEditorI18n("ui.compact_widget_mode", {}, "Compact widget style"),
       mobile_compact_edge_to_edge: homeiiEditorI18n("ui.compact_edge_to_edge", {}, "Compact edge-to-edge expand"),
       mobile_layout_mode: homeiiEditorI18n("ui.mobile_layout_mode", {}, "Phone layout mode"),
+      mobile_cover_flow: homeiiEditorI18n("ui.mobile_cover_flow", {}, "Artwork cover flow"),
       mobile_swipe_mode: homeiiEditorI18n("ui.artwork_swipe"),
       mobile_footer_search_enabled: homeiiEditorI18n("ui.footer_search"),
       mobile_mic_mode: homeiiEditorI18n("ui.microphone_2"),
@@ -323,6 +325,7 @@ export function getMobileEditorTexts() {
       mobile_compact_widget_mode: homeiiEditorI18n("ui.choose_when_compact_mode_uses_the_two_row_mobile_widget", {}, "Choose when compact mode uses the smaller two-row mobile widget."),
       mobile_compact_edge_to_edge: homeiiEditorI18n("ui.compact_edge_to_edge_helper", {}, "When disabled, compact expand opens as a floating window so Home Assistant navigation remains visible."),
       mobile_layout_mode: homeiiEditorI18n("ui.mobile_layout_mode_helper", {}, "Auto uses the available card space. Full keeps the phone player inline and requests a tall Sections slot. Compact always uses the compact tile."),
+      mobile_cover_flow: homeiiEditorI18n("ui.mobile_cover_flow_helper", {}, "Adds the experimental vertical 3D cover flow to the main artwork area."),
       mobile_swipe_mode: homeiiEditorI18n("ui.choose_whether_artwork_swipe_changes_track_or_browses_covers"),
       mobile_footer_search_enabled: homeiiEditorI18n("ui.enable_or_disable_the_footer_search_button"),
       mobile_mic_mode: homeiiEditorI18n("ui.matches_the_microphone_setting_from_the_in_card_settings_screen"),
@@ -645,6 +648,7 @@ export function getMobileCardConfigForm() {
             column_min_width: "220px",
             schema: [
               { name: "mobile_swipe_mode", selector: { select: { mode: "dropdown", options: t.options.mobile_swipe_mode } } },
+              { name: "mobile_cover_flow", selector: { boolean: {} } },
               { name: "mobile_mic_mode", selector: { select: { mode: "dropdown", options: t.options.mobile_mic_mode } } },
               { name: "mobile_home_shortcut", selector: { boolean: {} } },
               { name: "mobile_home_shortcut_path", selector: { text: {} } },

dist/config/validators.js

@@ -144,6 +144,8 @@ export function validateMobileCardEditorConfig(config) {
   assertValueInList(config.mobile_compact_widget_mode, "mobile_compact_widget_mode", ["auto", "full", "mini"]);
   assertBooleanIfDefined(config.mobile_compact_edge_to_edge, "mobile_compact_edge_to_edge");
   assertValueInList(config.mobile_layout_mode, "mobile_layout_mode", ["auto", "full", "compact"]);
+  assertBooleanIfDefined(config.mobile_cover_flow, "mobile_cover_flow");
+  assertBooleanIfDefined(config.mobile_queue_flow, "mobile_queue_flow");
   assertBooleanIfDefined(config.mobile_show_up_next, "mobile_show_up_next");
   assertStringIfDefined(config.pinned_player_entity, "pinned_player_entity");
   assertStringArrayIfDefined(config.pinned_player_entities, "pinned_player_entities");