Merge card id state isolation for 5.9 local

Author: r11a

CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 5.9.0-local - Unreleased
+
+Local development baseline for the next 5.9.0 release.
+
+Added:
+
+- Optional `card_id` YAML key. When set, HOMEii Flow namespaces browser-storage keys by the chosen id so multiple dashboards in the same browser can keep separate player selection, theme, layout, pinned/excluded players, screensaver settings, and other in-card customizations.
+- `src/core/state/card-id.js` foundation helpers with validation and storage-key scoping coverage.
+- `card_id` validator and visual-editor field in the Connection And Behavior section.
+
+Migration note:
+
+- Adding `card_id` to a card that previously had no `card_id` will appear to reset that card's in-card customizations once. The old global values stay in localStorage under their original keys; the card just starts reading from card-scoped keys.
+
 ## 5.8.2-beta.8 - 2026-06-03
 
 Focused beta follow-up for issue #28 after beta 7 exposed the next Home Assistant service-call layer.

README.md

@@ -474,6 +474,32 @@ condition:
     value_template: "{{ states('input_text.homeii_flow_active_player') | regex_match('^media_player\\.') }}"
 ```
 
+## Running Multiple Dashboards In One Browser
+
+By default, every HOMEii Flow card in the same browser shares its in-card customizations (theme, layout, excluded players, pinned players, screensaver settings, and the rest) via a single set of browser-storage keys. That keeps phones, tablets, and the desktop dashboard in sync when you only run one HOMEii Flow card.
+
+If you want **separate** dashboards — for example one card per kid's bedroom, or a kitchen wall tablet showing one player and a living-room phone view showing another — give each card its own `card_id`:
+
+```yaml
+type: custom:homeii-music-flow
+card_id: ida-music
+entity: media_player.ida_vaerelse
+```
+
+```yaml
+type: custom:homeii-music-flow
+card_id: toke-music
+entity: media_player.toke_vaerelse
+```
+
+Rules:
+
+- `card_id` is optional. Cards without it behave exactly as before (shared state).
+- `card_id` must be 1-64 characters of letters, digits, `-`, or `_`.
+- Two cards that share the same `card_id` will share state — useful when you want a phone and a wall tablet to stay in sync within one dashboard.
+- Adding `card_id` to a card that previously had no `card_id` will appear to reset its in-card customizations once. The old global values still live in localStorage under the original keys; the card now reads from the new card-scoped keys. Reconfigure once via the in-card Settings panel and you are done.
+- This only affects browser-local UI state. Music Assistant playback, your `media_player` entities, and Home Assistant configuration are unaffected.
+
 ## Sendspin Browser Player
 
 HOMEii Flow includes a local browser player flow powered by Sendspin. In the card this appears as **This device**.

dist/config/editor-forms.js

@@ -41,6 +41,7 @@ function homeiiRadioBrowserCountrySelectorOptions(translateFn = null, language =
 
 export function getBaseCardConfigForm() {
   const labels = {
+    card_id: homeiiEditorI18n("ui.card_id", {}, "Card ID"),
     config_entry_id: "Config Entry ID",
     ma_url: homeiiEditorI18n("ui.music_assistant_url"),
     music_assistant_external_url: "Music Assistant external URL",
@@ -65,6 +66,7 @@ export function getBaseCardConfigForm() {
     popup_opacity: homeiiEditorI18n("ui.popup_opacity"),
   };
   const helpers = {
+    card_id: homeiiEditorI18n("ui.card_id_helper", {}, "Unique slug (letters, digits, '-', '_'). Set this when running multiple HOMEii Flow dashboards in the same browser so each dashboard keeps its own player picker, theme, layout, and other in-card settings. Leave blank to share state with every other HOMEii Flow card in this browser (the original behaviour)."),
     config_entry_id: homeiiEditorI18n("ui.music_assistant_config_entry_id_if_you_want_direct_integration_lookup_th"),
     ma_url: homeiiEditorI18n("ui.leave_empty_if_the_card_should_use_home_assistant_only"),
     music_assistant_external_url: "Optional HTTPS Music Assistant URL for HTTPS dashboards, Nabu Casa, and Companion App browser-player connections.",
@@ -126,6 +128,7 @@ export function getBaseCardConfigForm() {
             flatten: true,
             column_min_width: "220px",
             schema: [
+              { name: "card_id", selector: { text: {} } },
               { name: "config_entry_id", selector: { text: {} } },
               { name: "ma_url", selector: { text: { type: "url" } } },
               { name: "music_assistant_external_url", selector: { text: { type: "url" } } },
@@ -289,6 +292,7 @@ export function getMobileEditorTexts() {
       player_sort_mode: homeiiEditorI18n("ui.player_sort"),
       player_order_entities: homeiiEditorI18n("ui.player_order"),
       ...playerOrderSlotLabels,
+      card_id: homeiiEditorI18n("ui.card_id", {}, "Card ID"),
       config_entry_id: "Config Entry ID",
       ma_url: homeiiEditorI18n("ui.music_assistant_url"),
       music_assistant_external_url: "Music Assistant external URL",
@@ -305,6 +309,7 @@ export function getMobileEditorTexts() {
       use_mass_queue_send_command: homeiiEditorI18n("ui.mass_queue_send_command_fallback"),
     },
     helpers: {
+      card_id: homeiiEditorI18n("ui.card_id_helper", {}, "Unique slug (letters, digits, '-', '_'). Set this when running multiple HOMEii Flow dashboards in the same browser so each dashboard keeps its own player picker, theme, layout, and other in-card settings. Leave blank to share state with every other HOMEii Flow card in this browser (the original behaviour)."),
       settings_source: homeiiEditorI18n("ui.choose_whether_settings_are_controlled_from_the_in_card_ui_or_from_the_c"),
       layout_mode: homeiiEditorI18n("ui.auto_chooses_mobile_or_tablet_based_on_actual_width"),
       height: homeiiEditorI18n("ui.card_height_in_pixels"),
@@ -673,6 +678,7 @@ export function getMobileCardConfigForm() {
             flatten: true,
             column_min_width: "220px",
             schema: [
+              { name: "card_id", selector: { text: {} } },
               { name: "config_entry_id", selector: { text: {} } },
               { name: "ma_url", selector: { text: { type: "url" } } },
               { name: "music_assistant_external_url", selector: { text: { type: "url" } } },

dist/config/validators.js

@@ -38,11 +38,26 @@ export function assertStringArrayValuesIfDefined(value, key, allowedValues) {
   }
 }
 
+const CARD_ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+
+export function assertCardIdIfDefined(value, key) {
+  if (value == null) return;
+  if (typeof value !== "string") throw new Error(`${key} must be a string`);
+  const trimmed = value.trim();
+  if (trimmed === "") return;
+  if (!CARD_ID_PATTERN.test(trimmed)) {
+    throw new Error(
+      `${key} must be 1-64 characters of letters, digits, '-' or '_'`
+    );
+  }
+}
+
 export function validateBaseCardEditorConfig(config) {
   if (!config || typeof config !== "object" || Array.isArray(config)) {
     throw new Error("Card config must be an object");
   }
 
+  assertCardIdIfDefined(config.card_id, "card_id");
   assertStringIfDefined(config.config_entry_id, "config_entry_id");
   assertStringIfDefined(config.ma_url, "ma_url");
   assertStringIfDefined(config.music_assistant_external_url, "music_assistant_external_url");

dist/core/base-music-card.js

@@ -3,6 +3,7 @@ export function createHomeiiBaseMusicCard({
   HOMEII_VISIBLE_LANGUAGE_OPTIONS,
   HomeiiStateFoundation,
   HomeiiConfigValidators,
+  HomeiiCardIdFoundation,
   HomeiiResponsiveFoundation,
   HomeiiMediaQueueFoundation,
   HomeiiMediaPresentationFoundation,
@@ -151,7 +152,7 @@ export function createHomeiiBaseMusicCard({
 
       try {
         const configuredLanguage = this._config.language || "en";
-        const storedLanguage = localStorage.getItem("homeii_music_flow_lang");
+        const storedLanguage = localStorage.getItem(this._lsKey("homeii_music_flow_lang"));
         const configControlsLanguage = typeof this._usesVisualSettings === "function" && this._usesVisualSettings();
         const configuredLanguageBase = String(configuredLanguage || "")
           .trim()
@@ -167,12 +168,12 @@ export function createHomeiiBaseMusicCard({
       }
 
       try {
-        this._state.cardTheme = localStorage.getItem("homeii_music_flow_theme") || this._config.theme_mode || "auto";
+        this._state.cardTheme = localStorage.getItem(this._lsKey("homeii_music_flow_theme")) || this._config.theme_mode || "auto";
       } catch (_) {
         this._state.cardTheme = this._config.theme_mode || "auto";
       }
       try {
-        this._state.tracksLayout = localStorage.getItem("homeii_music_flow_tracks_layout") || "list";
+        this._state.tracksLayout = localStorage.getItem(this._lsKey("homeii_music_flow_tracks_layout")) || "list";
       } catch (_) {
         this._state.tracksLayout = "list";
       }
@@ -3758,7 +3759,7 @@ export function createHomeiiBaseMusicCard({
 
     _toggleLanguage() {
       this._state.lang = this._nextLanguageCode();
-      try { localStorage.setItem("homeii_music_flow_lang", this._state.lang); } catch (_) {}
+      try { localStorage.setItem(this._lsKey("homeii_music_flow_lang"), this._state.lang); } catch (_) {}
 
       const currentTheme = this._state.cardTheme;
       const currentPlayer = this._state.selectedPlayer;
@@ -3813,7 +3814,7 @@ export function createHomeiiBaseMusicCard({
     _toggleCardTheme() {
       const effective = this._effectiveTheme();
       this._state.cardTheme = effective === "dark" ? "light" : "dark";
-      try { localStorage.setItem("homeii_music_flow_theme", this._state.cardTheme); } catch (_) {}
+      try { localStorage.setItem(this._lsKey("homeii_music_flow_theme"), this._state.cardTheme); } catch (_) {}
       const card = this.shadowRoot.querySelector(".card");
       if (card) {
         card.classList.remove("theme-dark", "theme-light");
@@ -3835,6 +3836,12 @@ export function createHomeiiBaseMusicCard({
       return player.state === "playing" || player.state === "paused" || !!attrs.media_title || !!attrs.active_queue;
     }
 
+    _lsKey(baseKey) {
+      return HomeiiCardIdFoundation
+        ? HomeiiCardIdFoundation.scopeStorageKey(baseKey, this._config?.card_id)
+        : baseKey;
+    }
+
     _thisDeviceStorageKey() {
       return `homeii-this-device-player::${this._maBrowserUrl() || this._config?.ma_url || location.origin || "default"}`;
     }
@@ -5189,7 +5196,7 @@ export function createHomeiiBaseMusicCard({
 
     _saveMobileRecentHistory() {
       try {
-        localStorage.setItem("homeii_music_flow_mobile_recent_history", JSON.stringify((this._state.mobileRecentHistory || []).slice(0, 10)));
+        localStorage.setItem(this._lsKey("homeii_music_flow_mobile_recent_history"), JSON.stringify((this._state.mobileRecentHistory || []).slice(0, 10)));
       } catch (_) {}
     }
 
@@ -6393,7 +6400,7 @@ export function createHomeiiBaseMusicCard({
     }
 
     _controlRoomScenesStorageKey() {
-      return "homeii_music_flow_control_room_scenes_v1";
+      return this._lsKey("homeii_music_flow_control_room_scenes_v1");
     }
 
     _normalizeControlRoomScene(scene = {}, index = 0) {
@@ -7924,11 +7931,11 @@ export function createHomeiiBaseMusicCard({
     }
 
     _likedStorageKey() {
-      return "homeii_music_flow_likes_v2";
+      return this._lsKey("homeii_music_flow_likes_v2");
     }
 
     _likedMetaStorageKey() {
-      return "homeii_music_flow_like_meta_v2";
+      return this._lsKey("homeii_music_flow_like_meta_v2");
     }
 
     _loadLikedUris() {
@@ -8920,7 +8927,7 @@ export function createHomeiiBaseMusicCard({
 
     _setTracksLayout(layout) {
       this._state.tracksLayout = layout === "grid" ? "grid" : "list";
-      try { localStorage.setItem("homeii_music_flow_tracks_layout", this._state.tracksLayout); } catch (_) {}
+      try { localStorage.setItem(this._lsKey("homeii_music_flow_tracks_layout"), this._state.tracksLayout); } catch (_) {}
       if (this._state.view === "tracks") this._renderTracks();
     }
 

dist/core/state/card-id.js

@@ -0,0 +1,17 @@
+const VALID_CARD_ID = /^[A-Za-z0-9_-]{1,64}$/;
+const SCOPE_SEPARATOR = "__";
+
+export function normalizeCardId(value) {
+  const id = String(value ?? "").trim();
+  if (!id) return "";
+  return VALID_CARD_ID.test(id) ? id : "";
+}
+
+export function isValidCardId(value) {
+  return normalizeCardId(value) !== "";
+}
+
+export function scopeStorageKey(baseKey, cardId) {
+  const id = normalizeCardId(cardId);
+  return id ? `${baseKey}${SCOPE_SEPARATOR}${id}` : baseKey;
+}

dist/localization/en.js

@@ -926,6 +926,8 @@ const messages = Object.freeze({
   "ui.hotel_mode": "Hotel Mode",
   "ui.hotel_mode_helper": "Minimal hotel-safe UI: player controls, volume, search, artwork browsing, and player selection only.",
   "ui.style_and_genres": "Style and genres",
+  "ui.card_id": "Card ID",
+  "ui.card_id_helper": "Unique slug (letters, digits, '-', '_'). Set this when running multiple HOMEii Flow dashboards in the same browser so each dashboard keeps its own player picker, theme, layout, and other in-card settings. Leave blank to share state with every other HOMEii Flow card in this browser (the original behaviour).",
 });
 
 export default messages;

dist/localization/es.js

@@ -926,6 +926,8 @@ const messages = Object.freeze({
   "ui.hotel_mode": "Modo hotel",
   "ui.hotel_mode_helper": "Interfaz mínima segura para hotel: solo controles del reproductor, volumen, búsqueda, navegación por carátulas y selección de reproductor.",
   "ui.style_and_genres": "Estilos y géneros",
+  "ui.card_id": "Card ID",
+  "ui.card_id_helper": "Unique slug (letters, digits, '-', '_'). Set this when running multiple HOMEii Flow dashboards in the same browser so each dashboard keeps its own player picker, theme, layout, and other in-card settings. Leave blank to share state with every other HOMEii Flow card in this browser (the original behaviour).",
 });
 
 export default messages;

dist/localization/fr.js

@@ -926,6 +926,8 @@ const messages = Object.freeze({
   "ui.hotel_mode": "Mode hôtel",
   "ui.hotel_mode_helper": "Interface minimale sécurisée pour l'hôtel : commandes du lecteur, volume, recherche, navigation dans les pochettes et sélection du lecteur uniquement.",
   "ui.style_and_genres": "Styles et genres",
+  "ui.card_id": "Card ID",
+  "ui.card_id_helper": "Unique slug (letters, digits, '-', '_'). Set this when running multiple HOMEii Flow dashboards in the same browser so each dashboard keeps its own player picker, theme, layout, and other in-card settings. Leave blank to share state with every other HOMEii Flow card in this browser (the original behaviour).",
 });
 
 export default messages;

dist/localization/he.js

@@ -926,6 +926,8 @@ const messages = Object.freeze({
   "ui.hotel_mode": "מצב מלון",
   "ui.hotel_mode_helper": "ממשק מצב מלון מינימלי: פקדי נגן, ווליום, חיפוש, דפדוף בעטיפות ובחירת נגן בלבד.",
   "ui.style_and_genres": "סגנונות וז'אנרים",
+  "ui.card_id": "Card ID",
+  "ui.card_id_helper": "Unique slug (letters, digits, '-', '_'). Set this when running multiple HOMEii Flow dashboards in the same browser so each dashboard keeps its own player picker, theme, layout, and other in-card settings. Leave blank to share state with every other HOMEii Flow card in this browser (the original behaviour).",
 });
 
 export default messages;