feat(config_flow,strings): CONF_LOGCAT_EVENTS options toggle (default off, stability-report wording) (P5-3)

custom_components/nvidia_shield/ha_adb_common/logcat_events.py

@@ -0,0 +1,79 @@
+"""Live events push (P5-3 / C-STREAM): logcat foreground trigger.
+
+Parses Android logcat's ActivityTaskManager ``START`` records and extracts
+the ``cmp=package`` part so the connection manager can stamp the foreground
+AppState instantly (sub-heartbeat latency). Logcat carries lifecycle only —
+no PlaybackState — so the hybrid split (ADB stays the playback/scene state
+source) is untouched: the stream never reads playback state.
+"""
+
+import re
+
+_LOG_RECORD_RE = re.compile(r"^\d{2}-\d{2}\s+\d{2}:\d{2}:\d{2}\.\d+")
+_CMP_RE = re.compile(r"cmp=([\w.]+)(?:/[^\s,}]+)?")
+_START_HINT_RE = re.compile(r"ActivityTaskManager:.*?START\b")
+
+
+def start_records(lines: list[str]) -> list[str]:
+    """Split raw logcat lines into START-record buffers (wrapped lines joined).
+
+    A record opens at a line that matches a log timestamp and mentions
+    ActivityTaskManager + START; subsequent lines that do NOT look like a
+    fresh log record are treated as continuations (the intent JSON can wrap
+    across lines). Anything else closes/open the next record.
+    """
+    records: list[str] = []
+    current: list[str] = []
+    for line in lines:
+        if _LOG_RECORD_RE.match(line) and _START_HINT_RE.search(line):
+            if current:
+                records.append("\n".join(current))
+            current = [line]
+        elif current and not _LOG_RECORD_RE.match(line):
+            current.append(line)  # wrapped intent text
+        else:
+            if current:
+                records.append("\n".join(current))
+            current = []
+    if current:
+        records.append("\n".join(current))
+    return records
+
+
+def foreground_from_logcat(lines: list[str]) -> str | None:
+    """The foreground package from the LAST valid START record, or None.
+
+    Non-START lines are ignored entirely; records whose intent carries no
+    ``cmp=`` (e.g. service starts) yield nothing; a explicit ``null`` cmp
+    is skipped too. Multi-user prefixes (``START u0``/``u10``...) are
+    tolerated — the user prefix is never part of the cmp value.
+    """
+    package: str | None = None
+    for record in start_records(lines):
+        match = _CMP_RE.search(record)
+        if not match:
+            continue
+        candidate = match.group(1)
+        if candidate and candidate != "null":
+            package = candidate  # last valid START wins
+    return package
+
+
+def foreground_packages(lines: list[str]) -> list[str]:
+    """Every distinct valid START package in order (test seam)."""
+    seen: list[str] = []
+    for record in start_records(lines):
+        match = _CMP_RE.search(record)
+        if not match:
+            continue
+        candidate = match.group(1)
+        if candidate and candidate != "null" and candidate not in seen:
+            seen.append(candidate)
+    return seen
+
+
+__all__ = [
+    "foreground_from_logcat",
+    "foreground_packages",
+    "start_records",
+]