feat(screenshot): report theme changes instead of writing them back

docs/beta.md

@@ -177,18 +177,31 @@ token grants. If the token is missing or invalid, Puppet lands on the login
 page and (by its design) restarts; ha-mcp surfaces this as a clear "set the
 engine's access token" error rather than a silent failure.
 
-Puppet's theme and dark-mode renderer controls used to dispatch Home
-Assistant's `settheme` event on every cold render, which Home Assistant
-persisted on the frontend profile of the user whose token the engine runs with
-— and synced to that user's real web and mobile sessions, flipping a dark-mode
-user's whole UI to light on every screenshot (#1909). Recent Puppet versions
-fixed that cold-render dispatch, so ha-mcp's snapshot/restore bracket around
-each capture is now disabled (#1991); the guard code is retained so it can be
-switched back on if a future engine regression reintroduces the write. If you
-run an older Puppet build, update the app (or your self-hosted sidecar
-image) — older engines still persist the theme selection and will keep
-flipping it. A dedicated Puppet account remains a sound belt-and-suspenders
-setup. Language selection is local to Puppet's browser session.
+Puppet dispatches Home Assistant's `settheme` event on cold renders, which
+Home Assistant persists on the frontend profile of the user whose token the
+engine runs with — and syncs to that user's real web and mobile sessions,
+flipping that user's whole UI on every screenshot (#1909). Upstream stopped
+the dispatch for renders that request no theme
+(balloob/home-assistant-addons#89), but by its own title only for that case,
+and it is unreleased as of Puppet 2.6.0 — so on current releases every render
+writes.
+
+The screenshot and dashboard-get tools **detect** this and report it, but
+never write: they read the engine account's saved theme before and after the
+render and, when it changed, emit a warning naming the previous value. Undoing
+it is a separate, explicitly write-annotated call —
+`ha_manage_theme(action="set_engine_theme", value=..., expected_current=...)`
+— passing both values from the warning, so a theme changed in the meantime is
+refused rather than overwritten — so these tools stay
+honestly `readOnlyHint: True` (#1991). `ha_manage_theme(action=
+"get_engine_theme")` inspects the same value. Note this is the engine
+account's *per-user* profile, a different layer from the backend default that
+`action="set"` changes.
+
+**Give the engine its own Home Assistant user and long-lived token** and the
+problem stops mattering: the write lands on an account nobody looks at, so no
+real session is disturbed. The warning is still emitted — ha-mcp has no signal
+telling it an account is dedicated — but it becomes safe to ignore. Language selection is local to Puppet's browser session.
 
 To change the Puppet engine app's own options (such as `keep_browser_open`)
 or to restart it, use `ha_manage_app`; the screenshot tools only render and
@@ -262,10 +275,15 @@ render failure to a warning so it never breaks a write that already committed.
 `include_screenshot` (get) does not commit a dashboard/config write, and the
 screenshot *is* the requested payload, so a total render failure surfaces as
 an error (matching the standalone `ha_get_dashboard_screenshot` tool) rather
-than a warning a caller might miss. Because Puppet can persist theme/dark
-preferences (and the theme-restore bracket writes frontend user data to undo
-that), screenshot operations are blocked in server Read Only Mode; ordinary
-dashboard get/list/search calls remain available.
+than a warning a caller might miss. Screenshot operations stay **available** in server Read
+Only Mode: both entry points are `readOnlyHint: True`, so the transform does
+not hide them and the middleware does not block them (#1991 removed the
+exemption that used to block them, pinned by
+`test_dashboard_config_screenshot_now_passes`). Rendering still makes Puppet
+persist theme/dark preferences on the engine account, and ha-mcp still reports
+that in warnings — so in Read Only Mode you get the warning but cannot act on
+it, since `ha_manage_theme` is exempted only for its read actions
+(`get_engine_theme` inspects the value; `set_engine_theme` stays blocked).
 
 **Raw rendered paths remain constrained.** `ha_get_dashboard_screenshot`
 validates legacy `dashboard_path` values (rejects URLs, query strings,

src/ha_mcp/dashboard_screenshot/capture.py

@@ -855,15 +855,12 @@ async def capture_dashboard_images(
     preset's native orientation. ``full_page`` is a compatibility alias for
     requesting the engine's native ``WIDTHxauto`` viewport.
 
-    The batch used to be bracketed by a :class:`ThemeGuard` that restored the
-    engine user's saved frontend theme when a cold render changed it (issue
-    #1909). That bracket is currently disabled (#1991): upstream Puppet no
-    longer dispatches ``settheme`` on cold renders, so there is nothing to undo.
-    The guard construction and the ``client`` / ``capture_warnings`` plumbing
-    are retained so the bracket can be re-enabled by uncommenting the
-    snapshot/restore calls if a future engine regression reintroduces the write;
-    while disabled ``capture_warnings`` simply stays empty and never affects the
-    captures themselves.
+    Each batch is bracketed by a :class:`ThemeGuard`, which reads the engine
+    user's saved frontend theme before and after rendering. It never writes:
+    when the render changed the theme it reports the previous value through
+    ``capture_warnings`` so the agent can restore it with the write-annotated
+    ``ha_manage_theme``, keeping this path honestly read-only (#1909, #1991).
+    Guard failures are non-fatal.
     """
     path = _validate_dashboard_path(dashboard_path)
     options = validate_capture_parameters(
@@ -888,16 +885,14 @@ async def capture_dashboard_images(
     mime_type = _MIME_TYPES[options.image_format]
     captures: list[DashboardImageCapture] = []
 
-    # ThemeGuard bracket — currently DISABLED (#1991). Stock Puppet used to
-    # dispatch a theme write into the authenticated frontend on cold renders,
-    # which Home Assistant persisted to the engine user's real profile (#1909);
-    # ha-mcp snapshotted before and restored after to undo it. Upstream Puppet
-    # has since fixed the cold-render settheme dispatch, so the bracket is no
-    # longer needed. The guard is still constructed (and the snapshot/restore
-    # calls kept below, commented out) so it can be re-enabled by uncommenting
-    # if a future engine regression reintroduces the write.
+    # ThemeGuard bracket. Puppet's settheme dispatch persists onto the engine
+    # token user's profile and syncs to that user's live sessions (#1909).
+    # Both reads here; the guard reports the change rather than undoing it, so
+    # this tool issues no writes and stays read-only (#1991). Armed for every
+    # capture, not just themed ones: the upstream fix that would spare the
+    # no-parameter case is unreleased as of Puppet 2.6.0.
     guard = ThemeGuard.for_capture(engine_target.addon_credential, client)
-    # await guard.take_snapshot()
+    await guard.take_snapshot()
     batch_error: ToolError | None = None
     try:
         async with httpx.AsyncClient(
@@ -977,7 +972,7 @@ async def capture_dashboard_images(
         # and its outcome can be attached to the error payload below.
         batch_error = exc
     finally:
-        # await guard.restore()  # ThemeGuard bracket disabled (#1991) — see above.
+        await guard.detect_change()
         if capture_warnings is not None:
             capture_warnings.extend(guard.warnings)