feat: add Media Source platform for Media Browser integration

Expose rendered dashboard PNGs in HA's Media Browser so they can be sent
to screens running OpenDisplay or any media-consuming integration.

The platform is auto-discovered by HA. Each configured dashboard appears
as a playable image item resolving to the existing public PNG endpoint.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: cryptomilk

AGENTS.md

@@ -144,5 +144,5 @@ When adding new HA imports to production code, add matching stubs in
   half-finished code. A reviewer should be able to check out any single
   commit and get a working tree.
 
-Home Assistant Core Sources: `./.tmp/core`
-Home Assistant Frontend Sources: `./.tmp/frontend`
+Home Assistant Core Sources: `./.tmp/core/`
+Home Assistant Frontend Sources: `./.tmp/frontend/`

custom_components/eink_dashboard/manifest.json

@@ -1,6 +1,7 @@
 {
   "domain": "eink_dashboard",
   "name": "E-Ink Dashboard",
+  "after_dependencies": ["media_source"],
   "codeowners": ["@cryptomilk"],
   "config_flow": true,
   "documentation": "https://github.com/cryptomilk/hass-eink-dashboard",

custom_components/eink_dashboard/media_source.py

@@ -0,0 +1,117 @@
+"""Expose e-ink dashboard images as a Media Source."""
+
+from __future__ import annotations
+
+from homeassistant.components.media_player import (
+    BrowseError,
+    MediaClass,
+)
+from homeassistant.components.media_source import (
+    BrowseMediaSource,
+    MediaSource,
+    MediaSourceItem,
+    PlayMedia,
+    Unresolvable,
+)
+from homeassistant.core import HomeAssistant
+
+from .const import DOMAIN
+
+
+async def async_get_media_source(
+    hass: HomeAssistant,
+) -> EinkDashboardMediaSource:
+    """Return the e-ink dashboard media source."""
+    return EinkDashboardMediaSource(hass)
+
+
+class EinkDashboardMediaSource(MediaSource):
+    """Provide rendered dashboard PNGs as browsable media."""
+
+    name = "E-Ink Dashboard"
+
+    def __init__(self, hass: HomeAssistant) -> None:
+        """Initialise the media source."""
+        super().__init__(DOMAIN)
+        self.hass = hass
+
+    async def async_resolve_media(
+        self,
+        item: MediaSourceItem,
+    ) -> PlayMedia:
+        """Resolve a dashboard entry to its image proxy URL.
+
+        Args:
+            item: Parsed media source item whose identifier
+                is a config entry ID.
+
+        Returns:
+            PlayMedia pointing at the authenticated image
+            proxy endpoint.
+
+        Raises:
+            Unresolvable: If the entry ID is not found.
+        """
+        entry_data = self.hass.data.get(DOMAIN, {}).get(
+            item.identifier,
+        )
+        if not isinstance(entry_data, dict) or "entry" not in entry_data:
+            raise Unresolvable(f"Unknown dashboard: {item.identifier}")
+        entity = entry_data["entity"]
+        return PlayMedia(
+            f"/api/image_proxy/{entity.entity_id}",
+            "image/png",
+        )
+
+    async def async_browse_media(
+        self,
+        item: MediaSourceItem,
+    ) -> BrowseMediaSource:
+        """List configured dashboards as browsable media items.
+
+        When called with an empty identifier, returns a root
+        node whose children are the individual dashboards.
+        Each child is directly playable (can_play=True)
+        and cannot be expanded further.
+
+        Args:
+            item: Parsed media source item.  Only the root
+                (empty identifier) is supported.
+
+        Returns:
+            Root BrowseMediaSource with one child per
+            dashboard config entry.
+
+        Raises:
+            BrowseError: If a non-root identifier is requested.
+        """
+        if item.identifier:
+            raise BrowseError(f"Unknown item: {item.identifier}")
+
+        entries = self.hass.data.get(DOMAIN, {})
+        children = [
+            BrowseMediaSource(
+                domain=DOMAIN,
+                identifier=entry_id,
+                media_class=MediaClass.IMAGE,
+                media_content_type="image/png",
+                title=entry_data["entry"].title,
+                thumbnail=f"/api/image_proxy/{entry_data['entity'].entity_id}",
+                can_play=True,
+                can_expand=False,
+            )
+            for entry_id, entry_data in entries.items()
+            if isinstance(entry_data, dict) and "entry" in entry_data
+        ]
+
+        return BrowseMediaSource(
+            domain=DOMAIN,
+            identifier=None,
+            media_class=MediaClass.APP,
+            media_content_type="",
+            title="E-Ink Dashboard",
+            can_play=False,
+            can_expand=True,
+            children_media_class=MediaClass.IMAGE,
+            children=children,
+        )

pyproject.toml

@@ -65,6 +65,7 @@ include = [
     "custom_components/eink_dashboard/config_flow.py",
     "custom_components/eink_dashboard/image.py",
     "custom_components/eink_dashboard/http.py",
+    "custom_components/eink_dashboard/media_source.py",
     "custom_components/eink_dashboard/sensor.py",
     "custom_components/eink_dashboard/store.py",
 ]

tests/conftest.py

@@ -17,6 +17,8 @@ def _stub_module(name: str) -> ModuleType:
     "homeassistant.components.frontend",
     "homeassistant.components.http",
     "homeassistant.components.image",
+    "homeassistant.components.media_player",
+    "homeassistant.components.media_source",
     "homeassistant.components.sensor",
     "homeassistant.components.websocket_api",
     "homeassistant.config_entries",
@@ -75,6 +77,91 @@ def __init__(
     },
 )
 
+media_player_mod = sys.modules["homeassistant.components.media_player"]
+
+
+class _BrowseError(Exception):
+    pass
+
+
+class _MediaClass:
+    APP = "app"
+    IMAGE = "image"
+
+
+media_player_mod.BrowseError = _BrowseError  # type: ignore[attr-defined]
+media_player_mod.MediaClass = _MediaClass  # type: ignore[attr-defined]
+
+media_source_mod = sys.modules["homeassistant.components.media_source"]
+
+
+class _PlayMedia:
+    def __init__(self, url: str, mime_type: str) -> None:
+        self.url = url
+        self.mime_type = mime_type
+
+
+class _BrowseMediaSource:
+    def __init__(
+        self,
+        *,
+        domain: str | None,
+        identifier: str | None,
+        media_class: str,
+        media_content_type: str,
+        title: str,
+        can_play: bool,
+        can_expand: bool,
+        children: list | None = None,
+        children_media_class: str | None = None,
+        thumbnail: str | None = None,
+    ) -> None:
+        self.domain = domain
+        self.identifier = identifier
+        self.media_class = media_class
+        self.media_content_type = media_content_type
+        self.title = title
+        self.can_play = can_play
+        self.can_expand = can_expand
+        self.children = children
+        self.children_media_class = children_media_class
+        self.thumbnail = thumbnail
+
+
+class _MediaSource:
+    name: str | None = None
+
+    def __init__(self, domain: str) -> None:
+        self.domain = domain
+        if not self.name:
+            self.name = domain
+
+
+class _MediaSourceItem:
+    # Mirrors the real MediaSourceItem dataclass signature.
+    def __init__(
+        self,
+        hass: object,
+        domain: str | None,
+        identifier: str,
+        target_media_player: str | None = None,
+    ) -> None:
+        self.hass = hass
+        self.domain = domain
+        self.identifier = identifier
+        self.target_media_player = target_media_player
+
+
+class _Unresolvable(Exception):
+    pass
+
+
+media_source_mod.BrowseMediaSource = _BrowseMediaSource  # type: ignore[attr-defined]
+media_source_mod.MediaSource = _MediaSource  # type: ignore[attr-defined]
+media_source_mod.MediaSourceItem = _MediaSourceItem  # type: ignore[attr-defined]
+media_source_mod.PlayMedia = _PlayMedia  # type: ignore[attr-defined]
+media_source_mod.Unresolvable = _Unresolvable  # type: ignore[attr-defined]
+
 config_entries = sys.modules["homeassistant.config_entries"]
 config_entries.ConfigEntry = MagicMock  # type: ignore[attr-defined]
 config_entries.ConfigFlowResult = dict  # type: ignore[attr-defined]

tests/test_media_source.py

@@ -0,0 +1,152 @@
+"""Tests for the e-ink dashboard Media Source platform."""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock
+
+import pytest
+from homeassistant.components.media_player import BrowseError
+from homeassistant.components.media_source import (
+    MediaSourceItem,
+    Unresolvable,
+)
+
+from custom_components.eink_dashboard.media_source import (
+    EinkDashboardMediaSource,
+    async_get_media_source,
+)
+
+DOMAIN = "eink_dashboard"
+
+
+def _make_hass(
+    entries: dict | None = None,
+) -> MagicMock:
+    """Build a minimal stub hass with the given entry data."""
+    hass = MagicMock()
+    hass.data = {DOMAIN: entries or {}}
+    return hass
+
+
+def _make_item(
+    hass: object,
+    identifier: str = "",
+) -> MediaSourceItem:
+    """Build a MediaSourceItem with the given identifier."""
+    return MediaSourceItem(hass, DOMAIN, identifier)
+
+
+@pytest.mark.asyncio
+async def test_async_get_media_source() -> None:
+    """Factory returns an EinkDashboardMediaSource instance."""
+    hass = _make_hass()
+    source = await async_get_media_source(hass)
+    assert isinstance(source, EinkDashboardMediaSource)
+    assert source.name == "E-Ink Dashboard"
+
+
+@pytest.mark.asyncio
+async def test_browse_root_lists_entries() -> None:
+    """Root browse returns one child per dashboard entry."""
+    entry_a = MagicMock()
+    entry_a.title = "Kitchen"
+    entity_a = MagicMock()
+    entity_a.entity_id = "image.kitchen"
+    entry_b = MagicMock()
+    entry_b.title = "Office"
+    entity_b = MagicMock()
+    entity_b.entity_id = "image.office"
+    entries = {
+        "aaa": {
+            "entry": entry_a,
+            "entity": entity_a,
+            "widgets": [],
+        },
+        "bbb": {
+            "entry": entry_b,
+            "entity": entity_b,
+            "widgets": [],
+        },
+    }
+    hass = _make_hass(entries)
+    source = EinkDashboardMediaSource(hass)
+
+    result = await source.async_browse_media(
+        _make_item(hass),
+    )
+
+    assert result.can_expand is True
+    assert result.can_play is False
+    assert result.title == "E-Ink Dashboard"
+    assert len(result.children) == 2
+
+    ids = {c.identifier for c in result.children}
+    assert ids == {"aaa", "bbb"}
+    for child in result.children:
+        assert child.can_play is True
+        assert child.can_expand is False
+        assert child.media_content_type == "image/png"
+        expected_entity = (
+            "image.kitchen" if child.identifier == "aaa" else "image.office"
+        )
+        assert child.thumbnail == (f"/api/image_proxy/{expected_entity}")
+
+
+@pytest.mark.asyncio
+async def test_browse_root_empty_when_no_entries() -> None:
+    """Root browse returns an empty children list with no entries."""
+    hass = _make_hass({})
+    source = EinkDashboardMediaSource(hass)
+
+    result = await source.async_browse_media(
+        _make_item(hass),
+    )
+    assert result.children == []
+
+
+@pytest.mark.asyncio
+async def test_browse_non_root_raises() -> None:
+    """Browsing a non-root identifier raises BrowseError."""
+    hass = _make_hass()
+    source = EinkDashboardMediaSource(hass)
+
+    with pytest.raises(BrowseError):
+        await source.async_browse_media(
+            _make_item(hass, "some_id"),
+        )
+
+
+@pytest.mark.asyncio
+async def test_resolve_valid_entry() -> None:
+    """Resolving a known entry returns the image proxy URL."""
+    entry = MagicMock()
+    entry.title = "Kitchen"
+    entity = MagicMock()
+    entity.entity_id = "image.kitchen"
+    entries = {
+        "abc123": {
+            "entry": entry,
+            "entity": entity,
+            "widgets": [],
+        },
+    }
+    hass = _make_hass(entries)
+    source = EinkDashboardMediaSource(hass)
+
+    result = await source.async_resolve_media(
+        _make_item(hass, "abc123"),
+    )
+    assert result.url == "/api/image_proxy/image.kitchen"
+    assert result.mime_type == "image/png"
+
+
+@pytest.mark.asyncio
+async def test_resolve_unknown_entry_raises() -> None:
+    """Resolving an unknown entry raises Unresolvable."""
+    hass = _make_hass({})
+    source = EinkDashboardMediaSource(hass)
+
+    with pytest.raises(Unresolvable):
+        await source.async_resolve_media(
+            _make_item(hass, "nonexistent"),
+        )