Add SmartPaper restore bridge

smartpaper_restore_bridge/__init__.py

@@ -1 +1,50 @@
-1 
+# -*- coding: utf-8 -*-
+"""Invisible browser storage bridge used by SmartPaper authentication.
+
+The component is intentionally dependency-free. Its frontend is served by
+Streamlit itself and returns only JSON-serializable status data to Python.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import streamlit.components.v1 as components
+
+_FRONTEND_DIR = Path(__file__).resolve().parent / "frontend"
+_FRONTEND_ENTRY = _FRONTEND_DIR / "index.html"
+if not _FRONTEND_ENTRY.is_file():
+    raise RuntimeError("SmartPaper restore bridge frontend is missing.")
+
+_COMPONENT = components.declare_component(
+    "smartpaper_restore_bridge",
+    path=str(_FRONTEND_DIR),
+)
+
+
+def restore_bridge(
+    *,
+    action: str,
+    command_id: str,
+    token: str = "",
+    expires_at: str = "",
+    key: str = "sp_restore_bridge",
+) -> dict[str, Any] | None:
+    """Read, write, or delete SmartPaper's browser recovery token.
+
+    The return value is asynchronous: the first call normally returns ``None``;
+    after the frontend completes the requested storage operation, Streamlit
+    reruns the script and this function returns a result dictionary.
+    """
+
+    value = _COMPONENT(
+        action=str(action or "read"),
+        command_id=str(command_id or ""),
+        token=str(token or ""),
+        expires_at=str(expires_at or ""),
+        height=0,
+        default=None,
+        key=key,
+    )
+    return value if isinstance(value, dict) else None