span-panel-api 2.5.4__tar.gz → 2.6.1__tar.gz

{span_panel_api-2.5.4 → span_panel_api-2.6.1}/CHANGELOG.md

@@ -4,6 +4,53 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.6.1] - 04/2026
+
+### Changed
+
+- **`get_fqdn()` returns `str | None`** — `None` now distinguishes "no FQDN configured" (HTTP 404 or missing field) from an explicit empty string. Callers that treated `""` as "not registered" must update to check for `None`.
+- **Connection callback errors logged at WARNING** — `SpanMqttClient._on_connection_change` now logs callback exceptions via `_LOGGER.warning(..., exc_info=True)` instead of `_LOGGER.exception(...)`, consistent with `_dispatch_snapshot`.
+- **Reconnect loop catches all exceptions** — `AsyncMqttBridge._reconnect_loop` no longer silently drops on non-`OSError` failures (e.g. `WebsocketConnectionError`, `ssl.SSLError`). All exceptions are logged at WARNING and the loop keeps backing off.
+- **Abnormal MQTT disconnects logged at WARNING** — disconnects where `reason_code.is_failure` is true now log at WARNING; clean disconnects continue to log at DEBUG.
+
+### Fixed
+
+- **CA certificate no longer written to disk** — `AsyncMqttBridge.connect()` builds the `ssl.SSLContext` from the fetched PEM via `cadata`, eliminating the temp-file lifecycle (and the small leak window on unexpected process exit) that the prior
+  `tls_set(ca_certs=path)` path required.
+- **Deprecated `asyncio.get_event_loop()` removed** — `_wait_for_circuit_names` now uses `time.monotonic()`. The previous code emitted a `DeprecationWarning` on Python 3.12+.
+- **Negative-zero on circuit `instant_power_w`** — explicit guard replaces a cryptic `-raw or 0.0` idiom in `HomieDeviceConsumer._build_circuit`.
+- **DSM grid-exchanging heuristic uses epsilon** — replaces `!= 0.0` float comparison with `abs(x) > 1.0 W`, so the `DSM_OFF_GRID` branch is actually reachable when no BESS is commissioned and lugs readings hover near zero.
+- **`SpanPanelAPIError.__str__` override removed** — the override silently hid exception args beyond the first; default `Exception.__str__` is now used.
+- **Paho lock-layout check at import** — `span_panel_api.mqtt.async_client` verifies on import that the `_PAHO_LOCK_ATTRS` list exactly matches paho's `*_mutex` attributes. Raises `RuntimeError` (not `assert`, so `python -O` does not bypass it) on drift.
+
+### Documentation
+
+- **`register_v2()`** — docstring now warns that each call creates a new client entry on the panel; callers should persist and reuse the returned `V2AuthResponse` rather than re-registering on every restart.
+- **Stale simulation transport references removed** from `protocol.py` and `models.py` module docstrings.
+
+## [2.6.0] - 04/2026
+
+### Added
+
+- **`SpanMqttClient.register_connection_callback(cb)`** — subscribe to broker connection state transitions. Callback fires with `False` on broker disconnect and `True` on reconnect; returns an idempotent unregister function. Added to
+  `SpanPanelClientProtocol` so any transport that claims the protocol must implement it.
+- **`SpanPanelStaleDataError`** exception — raised by `get_snapshot()` when the client is not fully live. Derives from `SpanPanelError` (not from `SpanPanelConnectionError`), because "never connected" and "running but data not currently live" are
+  semantically distinct states.
+
+### Changed
+
+- **`get_snapshot()` contract** — now raises `SpanPanelStaleDataError` when the bridge is not connected or the Homie device has not reached ready state. Previously, the method silently returned a snapshot built from whatever the in-memory accumulator
+  happened to hold, which made offline panels indistinguishable from online ones. This is the primary reason the span integration could not detect panel-offline transitions.
+
+### Fixed
+
+- **Stale snapshot dispatch after bridge disconnect** — a pending snapshot-debounce timer scheduled just before a bridge disconnect could fire afterwards, delivering a snapshot built from the still-`ready()` accumulator to subscribers.
+  `_on_connection_change(False)` now cancels the pending timer, and `_dispatch_snapshot` is now guarded by the same liveness predicate as `get_snapshot()`, so push consumers never receive a post-disconnect stale snapshot.
+
+### Breaking
+
+- Consumers of `get_snapshot()` must now handle `SpanPanelStaleDataError`. Any consumer with a broad `except Exception` (or `except SpanPanelError`) branch already handles this correctly.
+
 ## [2.5.4] - 04/2026
 
 ### Reverted

{span_panel_api-2.5.4 → span_panel_api-2.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: span-panel-api
-Version: 2.5.4
+Version: 2.6.1
 Summary: A client library for SPAN Panel API
 Project-URL: Homepage, https://github.com/SpanPanel/span-panel-api
 Project-URL: Issues, https://github.com/SpanPanel/span-panel-api/issues
@@ -86,12 +86,12 @@ This ensures that the first `get_snapshot()` after connect returns human-readabl
 
 The library defines three structural subtyping protocols (PEP 544) that both the MQTT transport and the simulation engine implement:
 
-| Protocol                   | Purpose                                                                               |
-| -------------------------- | ------------------------------------------------------------------------------------- |
-| `SpanPanelClientProtocol`  | Core lifecycle: `connect`, `close`, `ping`, `get_snapshot`                            |
-| `CircuitControlProtocol`   | Relay and shed-priority control: `set_circuit_relay`, `set_circuit_priority`          |
-| `PanelControlProtocol`     | Panel-level control: `set_dominant_power_source`                                      |
-| `StreamingCapableProtocol` | Push-based updates: `register_snapshot_callback`, `start_streaming`, `stop_streaming` |
+| Protocol                   | Purpose                                                                                    |
+| -------------------------- | ------------------------------------------------------------------------------------------ |
+| `SpanPanelClientProtocol`  | Core lifecycle: `connect`, `close`, `ping`, `get_snapshot`, `register_connection_callback` |
+| `CircuitControlProtocol`   | Relay and shed-priority control: `set_circuit_relay`, `set_circuit_priority`               |
+| `PanelControlProtocol`     | Panel-level control: `set_dominant_power_source`                                           |
+| `StreamingCapableProtocol` | Push-based updates: `register_snapshot_callback`, `start_streaming`, `stop_streaming`      |
 
 Integration code programs against these protocols, not transport-specific classes.
 
@@ -175,6 +175,29 @@ async def main():
 asyncio.run(main())
 ```
 
+### Connection State Monitoring
+
+Push consumers that need to react to broker disconnect/reconnect events — for example, to mark downstream entities offline within a second of a dropped connection rather than waiting on a fallback poll — can register a connection callback. The callback
+fires `False` on disconnect and `True` on reconnect, edge-only (no synthetic call at registration time):
+
+```python
+def on_connection_change(connected: bool) -> None:
+    if connected:
+        print("Broker connection restored")
+    else:
+        print("Broker connection lost")
+
+unsubscribe_connection = client.register_connection_callback(on_connection_change)
+
+# Later, during teardown:
+unsubscribe_connection()
+```
+
+To check the current connection state on demand (for example, just after registering), call `await client.ping()`.
+
+When the client is not fully live (broker disconnected, or Homie device not yet ready), `await client.get_snapshot()` raises `SpanPanelStaleDataError` instead of returning cached data. Treat that exception as the canonical "panel currently unreachable"
+signal — see [Error Handling](#error-handling) below.
+
 ### Pre-Built Config Pattern
 
 If you already have MQTT broker credentials (e.g., stored from a previous registration):
@@ -227,9 +250,14 @@ await client.connect()
 
 `set_snapshot_interval()` controls how often push-mode snapshot callbacks fire. Lower values mean lower latency; higher values reduce CPU usage on constrained hardware. Dirty-node caching (v2.5.0) further reduces per-scan cost by skipping unchanged nodes.
 
+Passing `0` (or any non-positive value) disables debounce and dispatches a snapshot for every incoming property message — real-time mode, intended for fast consumers.
+
 ```python
 # Reduce snapshot frequency to every 2 seconds
 client.set_snapshot_interval(2.0)
+
+# Real-time dispatch — every property update triggers a callback
+client.set_snapshot_interval(0)
 ```
 
 ### Circuit Control
@@ -310,17 +338,25 @@ await delete_fqdn("192.168.1.100", token=auth.access_token)
 
 All exceptions inherit from `SpanPanelError`:
 
-| Exception                  | Cause                                                     |
-| -------------------------- | --------------------------------------------------------- |
-| `SpanPanelAuthError`       | Invalid passphrase, expired token, or missing credentials |
-| `SpanPanelConnectionError` | Cannot reach the panel (network/DNS)                      |
-| `SpanPanelTimeoutError`    | Request or connection timed out                           |
-| `SpanPanelValidationError` | Data validation failure                                   |
-| `SpanPanelAPIError`        | Unexpected HTTP response from v2 endpoints                |
-| `SpanPanelServerError`     | Panel returned HTTP 500                                   |
+| Exception                  | Cause                                                                                              |
+| -------------------------- | -------------------------------------------------------------------------------------------------- |
+| `SpanPanelAuthError`       | Invalid passphrase, expired token, or missing credentials                                          |
+| `SpanPanelConnectionError` | Cannot reach the panel (network/DNS) during initial connect                                        |
+| `SpanPanelStaleDataError`  | `get_snapshot()` called while the broker is disconnected or the Homie device has not reached ready |
+| `SpanPanelTimeoutError`    | Request or connection timed out                                                                    |
+| `SpanPanelValidationError` | Data validation failure                                                                            |
+| `SpanPanelAPIError`        | Unexpected HTTP response from v2 endpoints                                                         |
+| `SpanPanelServerError`     | Panel returned HTTP 500                                                                            |
+
+`SpanPanelStaleDataError` is distinct from `SpanPanelConnectionError`: the former means the client is running but data cannot be trusted right now (transient disconnect, or panel-declared not-ready); the latter means the initial connect failed and the
+client cannot be used at all.
 
 ```python
-from span_panel_api import SpanPanelAuthError, SpanPanelConnectionError
+from span_panel_api import (
+    SpanPanelAuthError,
+    SpanPanelConnectionError,
+    SpanPanelStaleDataError,
+)
 
 try:
     client = await create_span_client(host="192.168.1.100", passphrase="wrong")
@@ -328,6 +364,14 @@ except SpanPanelAuthError:
     print("Invalid passphrase")
 except SpanPanelConnectionError:
     print("Cannot reach panel")
+
+# Later, during normal operation:
+try:
+    snapshot = await client.get_snapshot()
+except SpanPanelStaleDataError as err:
+    # Broker dropped or panel declared not-ready — fall back to last-known
+    # data, a grace-period value, or mark downstream state unavailable.
+    print(f"Snapshot unavailable: {err}")
 ```
 
 ## Capabilities

{span_panel_api-2.5.4 → span_panel_api-2.6.1}/README.md

@@ -71,12 +71,12 @@ This ensures that the first `get_snapshot()` after connect returns human-readabl
 
 The library defines three structural subtyping protocols (PEP 544) that both the MQTT transport and the simulation engine implement:
 
-| Protocol                   | Purpose                                                                               |
-| -------------------------- | ------------------------------------------------------------------------------------- |
-| `SpanPanelClientProtocol`  | Core lifecycle: `connect`, `close`, `ping`, `get_snapshot`                            |
-| `CircuitControlProtocol`   | Relay and shed-priority control: `set_circuit_relay`, `set_circuit_priority`          |
-| `PanelControlProtocol`     | Panel-level control: `set_dominant_power_source`                                      |
-| `StreamingCapableProtocol` | Push-based updates: `register_snapshot_callback`, `start_streaming`, `stop_streaming` |
+| Protocol                   | Purpose                                                                                    |
+| -------------------------- | ------------------------------------------------------------------------------------------ |
+| `SpanPanelClientProtocol`  | Core lifecycle: `connect`, `close`, `ping`, `get_snapshot`, `register_connection_callback` |
+| `CircuitControlProtocol`   | Relay and shed-priority control: `set_circuit_relay`, `set_circuit_priority`               |
+| `PanelControlProtocol`     | Panel-level control: `set_dominant_power_source`                                           |
+| `StreamingCapableProtocol` | Push-based updates: `register_snapshot_callback`, `start_streaming`, `stop_streaming`      |
 
 Integration code programs against these protocols, not transport-specific classes.
 
@@ -160,6 +160,29 @@ async def main():
 asyncio.run(main())
 ```
 
+### Connection State Monitoring
+
+Push consumers that need to react to broker disconnect/reconnect events — for example, to mark downstream entities offline within a second of a dropped connection rather than waiting on a fallback poll — can register a connection callback. The callback
+fires `False` on disconnect and `True` on reconnect, edge-only (no synthetic call at registration time):
+
+```python
+def on_connection_change(connected: bool) -> None:
+    if connected:
+        print("Broker connection restored")
+    else:
+        print("Broker connection lost")
+
+unsubscribe_connection = client.register_connection_callback(on_connection_change)
+
+# Later, during teardown:
+unsubscribe_connection()
+```
+
+To check the current connection state on demand (for example, just after registering), call `await client.ping()`.
+
+When the client is not fully live (broker disconnected, or Homie device not yet ready), `await client.get_snapshot()` raises `SpanPanelStaleDataError` instead of returning cached data. Treat that exception as the canonical "panel currently unreachable"
+signal — see [Error Handling](#error-handling) below.
+
 ### Pre-Built Config Pattern
 
 If you already have MQTT broker credentials (e.g., stored from a previous registration):
@@ -212,9 +235,14 @@ await client.connect()
 
 `set_snapshot_interval()` controls how often push-mode snapshot callbacks fire. Lower values mean lower latency; higher values reduce CPU usage on constrained hardware. Dirty-node caching (v2.5.0) further reduces per-scan cost by skipping unchanged nodes.
 
+Passing `0` (or any non-positive value) disables debounce and dispatches a snapshot for every incoming property message — real-time mode, intended for fast consumers.
+
 ```python
 # Reduce snapshot frequency to every 2 seconds
 client.set_snapshot_interval(2.0)
+
+# Real-time dispatch — every property update triggers a callback
+client.set_snapshot_interval(0)
 ```
 
 ### Circuit Control
@@ -295,17 +323,25 @@ await delete_fqdn("192.168.1.100", token=auth.access_token)
 
 All exceptions inherit from `SpanPanelError`:
 
-| Exception                  | Cause                                                     |
-| -------------------------- | --------------------------------------------------------- |
-| `SpanPanelAuthError`       | Invalid passphrase, expired token, or missing credentials |
-| `SpanPanelConnectionError` | Cannot reach the panel (network/DNS)                      |
-| `SpanPanelTimeoutError`    | Request or connection timed out                           |
-| `SpanPanelValidationError` | Data validation failure                                   |
-| `SpanPanelAPIError`        | Unexpected HTTP response from v2 endpoints                |
-| `SpanPanelServerError`     | Panel returned HTTP 500                                   |
+| Exception                  | Cause                                                                                              |
+| -------------------------- | -------------------------------------------------------------------------------------------------- |
+| `SpanPanelAuthError`       | Invalid passphrase, expired token, or missing credentials                                          |
+| `SpanPanelConnectionError` | Cannot reach the panel (network/DNS) during initial connect                                        |
+| `SpanPanelStaleDataError`  | `get_snapshot()` called while the broker is disconnected or the Homie device has not reached ready |
+| `SpanPanelTimeoutError`    | Request or connection timed out                                                                    |
+| `SpanPanelValidationError` | Data validation failure                                                                            |
+| `SpanPanelAPIError`        | Unexpected HTTP response from v2 endpoints                                                         |
+| `SpanPanelServerError`     | Panel returned HTTP 500                                                                            |
+
+`SpanPanelStaleDataError` is distinct from `SpanPanelConnectionError`: the former means the client is running but data cannot be trusted right now (transient disconnect, or panel-declared not-ready); the latter means the initial connect failed and the
+client cannot be used at all.
 
 ```python
-from span_panel_api import SpanPanelAuthError, SpanPanelConnectionError
+from span_panel_api import (
+    SpanPanelAuthError,
+    SpanPanelConnectionError,
+    SpanPanelStaleDataError,
+)
 
 try:
     client = await create_span_client(host="192.168.1.100", passphrase="wrong")
@@ -313,6 +349,14 @@ except SpanPanelAuthError:
     print("Invalid passphrase")
 except SpanPanelConnectionError:
     print("Cannot reach panel")
+
+# Later, during normal operation:
+try:
+    snapshot = await client.get_snapshot()
+except SpanPanelStaleDataError as err:
+    # Broker dropped or panel declared not-ready — fall back to last-known
+    # data, a grace-period value, or mark downstream state unavailable.
+    print(f"Snapshot unavailable: {err}")
 ```
 
 ## Capabilities

{span_panel_api-2.5.4 → span_panel_api-2.6.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "span-panel-api"
-version = "2.5.4"
+version = "2.6.1"
 description = "A client library for SPAN Panel API"
 authors = [
     {name = "SpanPanel"}

{span_panel_api-2.5.4 → span_panel_api-2.6.1}/src/span_panel_api/__init__.py

@@ -23,6 +23,7 @@ from .exceptions import (
     SpanPanelConnectionError,
     SpanPanelError,
     SpanPanelServerError,
+    SpanPanelStaleDataError,
     SpanPanelTimeoutError,
     SpanPanelValidationError,
 )
@@ -109,6 +110,7 @@ __all__ = [  # noqa: RUF022
     "SpanPanelConnectionError",
     "SpanPanelError",
     "SpanPanelServerError",
+    "SpanPanelStaleDataError",
     "SpanPanelTimeoutError",
     "SpanPanelValidationError",
 ]

{span_panel_api-2.5.4 → span_panel_api-2.6.1}/src/span_panel_api/auth.py

@@ -47,6 +47,12 @@ async def register_v2(
     If ``passphrase`` is provided, it is sent as ``hopPassphrase``; omitting
     it enables door-bypass registration.
 
+    .. note::
+        Every call creates a new registered client entry on the panel. Callers
+        should persist and reuse the returned ``V2AuthResponse`` rather than
+        re-registering on every restart — otherwise stale entries will
+        accumulate over the panel's lifetime.
+
     Args:
         host: IP address or hostname of the SPAN Panel
         name: Client display name base (e.g., "home-assistant"); a UUID suffix is appended
@@ -310,7 +316,7 @@ async def get_fqdn(
     timeout: float = 10.0,
     port: int = 80,
     httpx_client: httpx.AsyncClient | None = None,
-) -> str:
+) -> str | None:
     """Retrieve the currently registered FQDN from the SPAN Panel.
 
     Args:
@@ -321,7 +327,9 @@ async def get_fqdn(
         httpx_client: Optional shared ``httpx.AsyncClient``; not closed by this function.
 
     Returns:
-        The registered FQDN, or empty string if none is configured
+        The registered FQDN string, or ``None`` when no FQDN is configured
+        (HTTP 404 or missing ``ebusTlsFqdn`` field). An empty string is only
+        returned when the panel reports an explicit empty FQDN value.
 
     Raises:
         SpanPanelAuthError: Token invalid or expired
@@ -344,13 +352,16 @@ async def get_fqdn(
         raise SpanPanelAuthError(f"Authentication failed (HTTP {response.status_code})")
 
     if response.status_code == 404:
-        return ""
+        return None
 
     if response.status_code != 200:
         raise SpanPanelAPIError(f"Failed to get FQDN: HTTP {response.status_code}")
 
     data: dict[str, object] = response.json()
-    return _str(data.get("ebusTlsFqdn"))
+    raw = data.get("ebusTlsFqdn")
+    if raw is None:
+        return None
+    return str(raw)
 
 
 async def delete_fqdn(

{span_panel_api-2.5.4 → span_panel_api-2.6.1}/src/span_panel_api/exceptions.py

@@ -28,9 +28,15 @@ class SpanPanelAPIError(SpanPanelError):
         super().__init__(message)
         self.status_code = status_code
 
-    def __str__(self) -> str:
-        return self.args[0] if self.args else ""
-
 
 class SpanPanelServerError(SpanPanelAPIError):
     """Server error (500)."""
+
+
+class SpanPanelStaleDataError(SpanPanelError):
+    """Raised when get_snapshot() is called while the client isn't live.
+
+    Distinct from SpanPanelConnectionError: this means the client is running
+    but data cannot be trusted right now (broker disconnected, or the Homie
+    device has declared $state=disconnected/lost).
+    """

{span_panel_api-2.5.4 → span_panel_api-2.6.1}/src/span_panel_api/models.py

@@ -1,8 +1,8 @@
 """Transport-agnostic snapshot models for SPAN Panel state.
 
-These dataclasses represent panel state regardless of how it was obtained
-(REST polling or MQTT push). Energy and power sign conventions are
-normalized at the transport boundary — consumers see a consistent view.
+These dataclasses represent panel state as produced by the MQTT/Homie
+transport. Energy and power sign conventions are normalized at the
+transport boundary — consumers see a consistent view.
 
 All snapshots are immutable (frozen) and memory-efficient (slots).
 """

{span_panel_api-2.5.4 → span_panel_api-2.6.1}/src/span_panel_api/mqtt/async_client.py

@@ -11,6 +11,7 @@ from __future__ import annotations
 from types import TracebackType
 
 from paho.mqtt.client import Client as MQTTClient
+from paho.mqtt.enums import CallbackAPIVersion
 
 _PAHO_LOCK_ATTRS = (
     "_in_callback_mutex",
@@ -23,6 +24,29 @@ _PAHO_LOCK_ATTRS = (
 )
 
 
+def _verify_paho_lock_attrs() -> None:
+    """Verify paho-mqtt's lock layout matches the list we monkey-patch.
+
+    Runs once at import. Raises ``RuntimeError`` if any expected attribute
+    is missing (paho renamed/removed one) or if paho grew a new lock we
+    don't yet patch. Running ``python -O`` does not bypass this check.
+    """
+    probe = MQTTClient(callback_api_version=CallbackAPIVersion.VERSION2)
+    expected = set(_PAHO_LOCK_ATTRS)
+    found = {name for name in vars(probe) if name.endswith("_mutex")}
+    missing = expected - found
+    extra = found - expected
+    if missing or extra:
+        raise RuntimeError(
+            "paho-mqtt lock attributes changed — NullLock monkey-patch is out of date. "
+            f"missing={sorted(missing)}, extra={sorted(extra)}. "
+            "Update _PAHO_LOCK_ATTRS in span_panel_api.mqtt.async_client."
+        )
+
+
+_verify_paho_lock_attrs()
+
+
 class NullLock:
     """No-op lock for single-threaded event loop execution.
 

{span_panel_api-2.5.4 → span_panel_api-2.6.1}/src/span_panel_api/mqtt/client.py

@@ -9,10 +9,12 @@ from __future__ import annotations
 
 import asyncio
 from collections.abc import Awaitable, Callable
+import contextlib
 import logging
+import time
 
 from ..auth import get_homie_schema
-from ..exceptions import SpanPanelConnectionError, SpanPanelServerError
+from ..exceptions import SpanPanelConnectionError, SpanPanelServerError, SpanPanelStaleDataError
 from ..models import FieldMetadata, HomieSchemaTypes, SpanPanelSnapshot
 from ..protocol import PanelCapability
 from .accumulator import HomiePropertyAccumulator
@@ -52,6 +54,8 @@ class SpanMqttClient:
         self._homie: HomieDeviceConsumer | None = None
         self._streaming = False
         self._snapshot_callbacks: list[Callable[[SpanPanelSnapshot], Awaitable[None]]] = []
+        self._connection_callbacks: list[Callable[[bool], None]] = []
+        self._live = False
         self._ready_event: asyncio.Event | None = None
         self._loop: asyncio.AbstractEventLoop | None = None
         self._background_tasks: set[asyncio.Task[None]] = set()
@@ -190,6 +194,7 @@ class SpanMqttClient:
             await self._bridge.disconnect()
             self._bridge = None
         self._accumulator = None
+        self._live = False
 
     async def ping(self) -> bool:
         """Check if MQTT connection is alive and device is ready."""
@@ -197,12 +202,43 @@ class SpanMqttClient:
             return False
         return self._bridge.is_connected() and self._homie.is_ready()
 
+    def register_connection_callback(self, callback: Callable[[bool], None]) -> Callable[[], None]:
+        """Subscribe to broker connection state transitions.
+
+        Callback fires with False on broker disconnect and True on reconnect.
+        No synthetic call is made at registration time — callbacks only fire
+        on real state edges. To check current connection state on registration,
+        await ping().
+
+        Returns an unregister function that removes the callback from the
+        dispatch list. Calling unregister twice is safe.
+        """
+        self._connection_callbacks.append(callback)
+
+        def unregister() -> None:
+            with contextlib.suppress(ValueError):
+                self._connection_callbacks.remove(callback)
+
+        return unregister
+
     async def get_snapshot(self) -> SpanPanelSnapshot:
         """Return current snapshot from accumulated MQTT state.
 
-        No network call — snapshot is built from in-memory property values.
+        Raises SpanPanelStaleDataError if the client is not fully live.
+        "Live" means: the bridge is connected AND the Homie accumulator
+        has reached ready state. Callers can treat SpanPanelStaleDataError
+        as the canonical "panel currently unreachable" signal.
+
+        No network call — snapshot is built from in-memory property values
+        when the liveness checks pass.
         """
-        return self._require_homie().build_snapshot()
+        if self._bridge is None or self._homie is None:
+            raise SpanPanelStaleDataError("Client not connected — call connect() first")
+        if not self._bridge.is_connected():
+            raise SpanPanelStaleDataError("MQTT broker disconnected")
+        if not self._homie.is_ready():
+            raise SpanPanelStaleDataError("Homie device not ready")
+        return self._homie.build_snapshot()
 
     # -- CircuitControlProtocol --------------------------------------------
 
@@ -289,22 +325,49 @@ class SpanMqttClient:
         # Dispatch snapshot callbacks if streaming
         if self._streaming and homie.is_ready() and self._loop is not None:
             if self._snapshot_interval <= 0:
-                # No debounce — dispatch immediately (backward compat)
+                # Real-time mode — dispatch immediately, no debounce.
                 self._create_dispatch_task()
             elif self._snapshot_timer is None:
                 # Schedule debounced dispatch
                 self._snapshot_timer = self._loop.call_later(self._snapshot_interval, self._fire_snapshot)
 
     def _on_connection_change(self, connected: bool) -> None:
-        """Handle MQTT connection state change (called from asyncio loop)."""
+        """Handle MQTT connection state change (called from asyncio loop).
+
+        Re-subscribes to the wildcard topic on reconnect (pre-existing
+        behavior), then fans out an edge-only notification to registered
+        connection callbacks. Duplicate state transitions are suppressed
+        so subscribers only see real edges.
+
+        On disconnect, any pending snapshot-debounce timer is cancelled
+        so a stale timer cannot dispatch a post-disconnect snapshot.
+        """
+        # Re-subscribe runs on every connected=True, including duplicates —
+        # paho may re-emit connected events after session restoration, and
+        # re-subscribing is broker-benign. Callback fan-out below is
+        # edge-only (see the guard after this block).
         if connected:
             _LOGGER.debug("MQTT connection established")
-            # Re-subscribe on reconnect
             if self._bridge is not None:
                 wildcard = WILDCARD_TOPIC_FMT.format(serial=self._serial_number)
                 self._bridge.subscribe(wildcard, qos=0)
         else:
             _LOGGER.debug("MQTT connection lost")
+            # Cancel any pending snapshot-debounce timer so it cannot
+            # fire post-disconnect with a stale snapshot.
+            self._cancel_snapshot_timer()
+
+        # Edge-only dispatch
+        if connected == self._live:
+            return
+        self._live = connected
+
+        # Iterate a copy — subscribers may unregister during their callback
+        for cb in list(self._connection_callbacks):
+            try:
+                cb(connected)
+            except Exception:  # pylint: disable=broad-exception-caught
+                _LOGGER.warning("Connection callback raised", exc_info=True)
 
     async def _wait_for_circuit_names(self, timeout: float) -> None:
         """Wait for all circuit-like nodes to have a ``name`` property.
@@ -315,8 +378,8 @@ class SpanMqttClient:
         timeout elapses (non-fatal — entities will use fallback names).
         """
         homie = self._require_homie()
-        deadline = asyncio.get_event_loop().time() + timeout
-        while asyncio.get_event_loop().time() < deadline:
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
             missing = homie.circuit_nodes_missing_names()
             if not missing:
                 _LOGGER.debug("All circuit names received")
@@ -357,15 +420,34 @@ class SpanMqttClient:
         """Update the snapshot debounce interval at runtime.
 
         Args:
-            interval: Seconds between snapshot dispatches. 0 = no debounce.
+            interval: Seconds between snapshot dispatches. ``0`` (or any
+                non-positive value) disables debounce and dispatches a
+                snapshot for every incoming property message — real-time
+                mode, intended for fast consumers.
         """
         self._snapshot_interval = interval
         # Cancel any pending timer so the new interval takes effect on next message
         self._cancel_snapshot_timer()
 
     async def _dispatch_snapshot(self) -> None:
-        """Build snapshot and send to all registered callbacks."""
-        snapshot = self._require_homie().build_snapshot()
+        """Build snapshot and send to all registered callbacks.
+
+        Guarded by the same liveness predicate as get_snapshot() — if the
+        bridge has disconnected or the Homie device is not ready, no
+        dispatch occurs. This prevents a pending debounce timer that was
+        scheduled just before a disconnect from delivering a stale
+        snapshot to subscribers after the fact.
+        """
+        bridge = self._bridge
+        homie = self._homie
+        if bridge is None or not bridge.is_connected() or homie is None or not homie.is_ready():
+            _LOGGER.debug(
+                "Skipping stale snapshot dispatch (bridge_connected=%s, homie_ready=%s)",
+                bridge is not None and bridge.is_connected(),
+                homie is not None and homie.is_ready(),
+            )
+            return
+        snapshot = homie.build_snapshot()
         for cb in list(self._snapshot_callbacks):
             try:
                 await cb(snapshot)