test: four-rung suite that asserts on decoded pixels, not log lines

130 tests, ~20s, 94% coverage. Four rungs, each proving something the one
below it cannot:

  registry   admission, fan-out, signal authorization and teardown, no I/O
  wire       camelCase round-trip, malformed frames, WebSocket lifecycle
  e2e        real capture -> encode -> SRTP -> decode -> painted frames
  realdisplay the actual X11 capture backend on a private Xvfb display

The e2e rung drives Chromium's fake media device, which produces a genuine
moving 1280x720 monitor stream, so the assertion is that a watcher's <video>
has a size and that its pixels change over time -- a frozen or never-started
peer connection fails the suite, which a "signal arrived" assertion would
not have caught.

Findings encoded as flags and comments, because each cost a debugging cycle:
the headless shell has no media stack at all (use channel="chromium");
mediaDevices is undefined off a secure context (serve over 127.0.0.1); and
--use-fake-ui-for-media-stream breaks real X11 capture by approving the
request without ever selecting a source, so the realdisplay suite selects
the source explicitly instead.

The realdisplay fixture strips WAYLAND_DISPLAY and DBUS_SESSION_BUS_ADDRESS
from the browser environment. Without that, a headed Chromium reaches
xdg-desktop-portal, mirrors the developer's actual desktop and raises a
permission dialog on their real screen -- which is exactly what happened
before this was isolated. Skipped unless MIRROR_REALDISPLAY=1.

Also guards the frontend's structure: scripts must parse as ES modules,
every id a script looks up must exist in its page, ids must not collide
across pages that share one stylesheet, and nothing may load from a CDN.

LLM-Generated: true

tests/test_protocol.py

@@ -0,0 +1,122 @@
+"""The wire contract, in both directions.
+
+These exist because the client speaks camelCase and Python speaks snake_case,
+and a silently-dropped field is the kind of bug that only shows up as a
+"cosmetic" column being blank three features later.
+"""
+
+from __future__ import annotations
+
+import pytest
+from pydantic import ValidationError
+
+from mirror import protocol
+
+
+class TestInbound:
+    def test_publish_accepts_the_camel_case_wire_format(self):
+        message = protocol.parse_client_message(
+            {
+                "type": "publish",
+                "label": "proj.gl — zsh",
+                "displaySurface": "window",
+                "width": 1920,
+                "height": 1080,
+                "audio": True,
+            }
+        )
+        assert message.display_surface == "window"
+        assert (message.width, message.height) == (1920, 1080)
+        assert message.audio is True
+
+    def test_snake_case_is_accepted_too_so_server_side_tools_can_replay_frames(self):
+        message = protocol.parse_client_message(
+            {"type": "publish", "display_surface": "monitor", "width": 800, "height": 600}
+        )
+        assert message.display_surface == "monitor"
+
+    def test_subscribe_carries_a_camel_case_stream_id(self):
+        assert (
+            protocol.parse_client_message({"type": "subscribe", "streamId": "p1"}).stream_id == "p1"
+        )
+        assert (
+            protocol.parse_client_message({"type": "unsubscribe", "streamId": "p1"}).stream_id
+            == "p1"
+        )
+
+    def test_a_missing_stream_id_is_a_validation_error_not_a_none(self):
+        with pytest.raises(ValidationError):
+            protocol.parse_client_message({"type": "subscribe"})
+
+    def test_dimensions_are_bounded(self):
+        for bad in (-1, 16385, "wide"):
+            with pytest.raises(ValidationError):
+                protocol.parse_client_message({"type": "publish", "width": bad})
+
+    def test_unknown_message_types_are_rejected(self):
+        with pytest.raises(ValidationError):
+            protocol.parse_client_message({"type": "teleport"})
+
+    def test_extra_keys_are_tolerated_for_forward_compatibility(self):
+        message = protocol.parse_client_message({"type": "ping", "someDayWeAddThis": True})
+        assert message.type == "ping"
+
+    def test_a_signal_payload_is_carried_verbatim(self):
+        payload = {"sdp": {"type": "offer", "sdp": "v=0\r\n"}}
+        message = protocol.parse_client_message({"type": "signal", "to": "p2", "payload": payload})
+        assert message.payload == payload
+
+
+class TestOutbound:
+    def test_the_stream_dto_is_camel_case(self):
+        dto = protocol.stream_dto(
+            stream_id="p1",
+            sharer_id="p1",
+            name="Tower",
+            label="Terminal",
+            display_surface="window",
+            width=1280,
+            height=720,
+            audio=False,
+            viewers=2,
+        )
+        assert set(dto) == {
+            "id",
+            "sharerId",
+            "name",
+            "label",
+            "displaySurface",
+            "width",
+            "height",
+            "audio",
+            "viewers",
+        }
+        assert dto["displaySurface"] == "window"
+
+    def test_every_server_message_advertises_its_type(self):
+        messages = [
+            protocol.welcome(peer_id="p1", role="viewer", streams=[]),
+            protocol.stream_added(stream={"id": "p1"}),
+            protocol.stream_updated(stream={"id": "p1"}),
+            protocol.stream_removed(stream_id="p1"),
+            protocol.peer_joined(stream_id="p1", viewer_id="p2", name="V"),
+            protocol.peer_left(stream_id="p1", viewer_id="p2"),
+            protocol.relayed_signal(frm="p1", to="p2", payload={}),
+            protocol.error(code="x", message="y"),
+            protocol.pong(),
+        ]
+        assert [m["type"] for m in messages] == [
+            "welcome",
+            "stream_added",
+            "stream_updated",
+            "stream_removed",
+            "peer_joined",
+            "peer_left",
+            "signal",
+            "error",
+            "pong",
+        ]
+
+    def test_an_error_says_whether_the_connection_survives_it(self):
+        assert protocol.error(code="x", message="y")["fatal"] is False
+        assert protocol.error(code="x", message="y", fatal=True)["fatal"] is True