LocalStorage

conftest.py

@@ -1,4 +1,5 @@
 import time
+import uuid
 from collections.abc import Generator
 
 import pytest
@@ -9,6 +10,20 @@
 ]
 
 
+@pytest.fixture(autouse=True)
+def fake_browser_session_id(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Bypass the browser-backed local storage component during tests.
+
+    ``streamlit.testing.v1.AppTest`` cannot run the local storage frontend, so
+    the real component would block forever. Each simulated session instead gets
+    a fresh id, matching how distinct browsers behave in production.
+    """
+    monkeypatch.setattr(
+        "open_cups.session_state.load_or_create_session_id",
+        lambda: str(uuid.uuid4()),
+    )
+
+
 class MockTime:
     def __init__(self, initial_time: float | None = None) -> None:
         self._current_time = initial_time if initial_time is not None else time.time()

pyproject.toml

@@ -10,6 +10,7 @@ dependencies = [
     "qrcode>=8.1",
     "streamlit>=1.49.1",
     "streamlit-autorefresh>=1.0.1",
+    "streamlit-local-storage>=0.0.25",
 ]
 
 [dependency-groups]
@@ -75,6 +76,7 @@ mypy_path = "src"
 module = [
     "streamlit.*",
     "streamlit_autorefresh.*",
+    "streamlit_local_storage.*",
     "plotly.*",
 ]
 ignore_missing_imports = true

src/open_cups/session_state.py

@@ -1,21 +1,43 @@
 import uuid
 
 import streamlit as st
+from streamlit_local_storage import LocalStorage
+
+SESSION_ID_STORAGE_KEY = "session_id"
 
 
 class SessionState:
     """Per-user session state wrapper.
 
+    The session identity is persisted in the browser's local storage so it
+    survives Streamlit session loss (websocket drops while a phone is locked,
+    page reloads). Local storage is scoped to the browser and never travels in
+    the URL, so sharing the room link cannot leak a user's identity.
+
     See https://docs.streamlit.io/develop/api-reference/caching-and-state/st.session_state
     for more details.
     """
 
     def __init__(self) -> None:
-        if "session_id" not in st.session_state:
-            existing = st.query_params.get("session_id")
-            st.session_state.session_id = existing or str(uuid.uuid4())
-        st.query_params["session_id"] = st.session_state.session_id
+        if SESSION_ID_STORAGE_KEY not in st.session_state:
+            st.session_state.session_id = load_or_create_session_id()
 
     @property
     def session_id(self) -> str:
         return str(st.session_state.session_id)
+
+
+def load_or_create_session_id() -> str:
+    """Return the browser's persisted session id, creating one if absent.
+
+    This is the single seam touching the browser-backed component, which lets
+    tests patch it without driving a real frontend.
+    """
+    local_storage = LocalStorage()
+    existing = local_storage.getItem(SESSION_ID_STORAGE_KEY)
+    if existing:
+        return str(existing)
+
+    new_session_id = str(uuid.uuid4())
+    local_storage.setItem(SESSION_ID_STORAGE_KEY, new_session_id)
+    return new_session_id