From 2432bfacce645a9d1952b5268665b644cb0803d7 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 21 Feb 2026 01:39:39 +0000
Subject: [PATCH 1/9] Initial plan


From 4186f810d22eaff17a7d7248dee2a1484cf986ab Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 21 Feb 2026 01:52:42 +0000
Subject: [PATCH 2/9] Fix documentation code examples and add missing
 NativeWindowHandle methods

Co-authored-by: deeleeramone <85772166+deeleeramone@users.noreply.github.com>
---
 pywry/docs/docs/components/index.md         |   2 +-
 pywry/docs/docs/guides/window-management.md |  33 ++---
 pywry/pywry/widget_protocol.py              | 130 ++++++++++++++++++++
 pywry/tests/test_widget_protocol.py         | 130 ++++++++++++++++++++
 4 files changed, 279 insertions(+), 16 deletions(-)

diff --git a/pywry/docs/docs/components/index.md b/pywry/docs/docs/components/index.md
index b4346ac..6c7b84b 100644
--- a/pywry/docs/docs/components/index.md
+++ b/pywry/docs/docs/components/index.md
@@ -101,7 +101,7 @@ All interactive components emit events via the `event` parameter:
 
 ```python
 Button(label="Save", event="file:save")
-Select(label="Theme", event="settings:theme", ...)
+Select(label="Theme", event="settings:theme", options=[...])
 ```
 
 Use namespaced events like `category:action` for organization:
diff --git a/pywry/docs/docs/guides/window-management.md b/pywry/docs/docs/guides/window-management.md
index 802f7c8..0939988 100644
--- a/pywry/docs/docs/guides/window-management.md
+++ b/pywry/docs/docs/guides/window-management.md
@@ -149,7 +149,7 @@ handle = app.show(
 
 ## The Window Handle
 
-`app.show()` returns a handle object. In native mode this is a `WindowProxy` — a full-featured wrapper around the OS window. In browser/notebook mode it's an `InlineWidget` with a subset of the same interface.
+`app.show()` returns a `NativeWindowHandle` in native mode — a wrapper that provides the same `emit()` / `on()` interface as notebook widgets, plus access to the full OS window API via its `.proxy` attribute. In browser/notebook mode it's an `InlineWidget` with the same event interface.
 
 ### Common Methods (all modes)
 
@@ -158,10 +158,14 @@ handle = app.show(
 | `handle.emit(event, data)` | Send an event from Python to the window's JavaScript |
 | `handle.on(event, callback)` | Register a Python callback for events from the window |
 | `handle.label` | The window/widget label |
+| `handle.alert(message, ...)` | Show a toast notification |
+| `handle.set_toolbar_value(id, value, ...)` | Update a toolbar component's value |
+| `handle.set_toolbar_values({id: value, ...})` | Update multiple toolbar components |
+| `handle.request_toolbar_state()` | Request current toolbar state |
 
 ### Native-only Methods (WindowProxy)
 
-The `WindowProxy` exposes the full set of OS window operations:
+The `WindowProxy` (accessible via `handle.proxy`) exposes the full set of OS window operations:
 
 **Window state:**
 
@@ -187,28 +191,27 @@ The `WindowProxy` exposes the full set of OS window operations:
 | `set_resizable(bool)` | Toggle resizing |
 | `set_theme(ThemeMode)` | Change theme |
 
-**Read-only properties:**
+**Read-only properties (via `handle.proxy`):**
 
 ```python
-handle.title            # Current title
-handle.inner_size       # Content area size (PhysicalSize)
-handle.outer_size       # Window frame size
-handle.inner_position   # Content position on screen
-handle.is_fullscreen    # bool
-handle.is_maximized     # bool
-handle.is_focused       # bool
-handle.is_visible       # bool
-handle.current_monitor  # Monitor info (name, size, position, scale)
+handle.proxy.inner_size       # Content area size (PhysicalSize)
+handle.proxy.outer_size       # Window frame size
+handle.proxy.inner_position   # Content position on screen
+handle.proxy.is_fullscreen    # bool
+handle.proxy.is_maximized     # bool
+handle.proxy.is_focused       # bool
+handle.proxy.is_visible       # bool
+handle.proxy.current_monitor  # Monitor info (name, size, position, scale)
 ```
 
 **JavaScript execution:**
 
 ```python
 # Fire-and-forget
-handle.eval("document.title = 'Hello'")
+handle.eval_js("document.title = 'Hello'")
 
-# With return value (blocks up to timeout)
-result = handle.eval_with_result("document.querySelectorAll('li').length", timeout=5.0)
+# With return value (blocks up to timeout, via proxy)
+result = handle.proxy.eval_with_result("document.querySelectorAll('li').length", timeout=5.0)
 ```
 
 ## Updating Content
diff --git a/pywry/pywry/widget_protocol.py b/pywry/pywry/widget_protocol.py
index 94471ae..a51da9b 100644
--- a/pywry/pywry/widget_protocol.py
+++ b/pywry/pywry/widget_protocol.py
@@ -9,6 +9,8 @@
 
 from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
 
+from .state_mixins import _UNSET, _Unset
+
 
 if TYPE_CHECKING:
     from collections.abc import Callable
@@ -640,6 +642,134 @@ def is_alive(self) -> bool:
         resources = self.resources
         return resources is not None and not resources.is_destroyed
 
+    # ─────────────────────────────────────────────────────────────────────────
+    # Notification helpers
+    # ─────────────────────────────────────────────────────────────────────────
+
+    def alert(
+        self,
+        message: str,
+        alert_type: str = "info",
+        title: str | None = None,
+        duration: int | None = None,
+        callback_event: str | None = None,
+        position: str = "top-right",
+    ) -> None:
+        """Show a toast notification in this window.
+
+        Parameters
+        ----------
+        message : str
+            The message to display.
+        alert_type : str
+            Alert type: 'info', 'success', 'warning', 'error', or 'confirm'.
+        title : str, optional
+            Optional title for the toast.
+        duration : int, optional
+            Auto-dismiss duration in ms. Defaults based on type.
+        callback_event : str, optional
+            Event name to emit when confirm dialog is answered.
+        position : str
+            Toast position: 'top-right', 'top-left', 'bottom-right', 'bottom-left'.
+
+        Examples
+        --------
+        >>> handle.alert("File saved successfully")
+        >>> handle.alert("Export complete", alert_type="success", title="Done")
+        >>> handle.alert("Are you sure?", alert_type="confirm", callback_event="app:confirm")
+        """
+        payload: dict[str, Any] = {
+            "message": message,
+            "type": alert_type,
+            "position": position,
+        }
+        if title is not None:
+            payload["title"] = title
+        if duration is not None:
+            payload["duration"] = duration
+        if callback_event is not None:
+            payload["callback_event"] = callback_event
+        self.emit("pywry:alert", payload)
+
+    # ─────────────────────────────────────────────────────────────────────────
+    # Toolbar state helpers
+    # ─────────────────────────────────────────────────────────────────────────
+
+    def request_toolbar_state(self, toolbar_id: str | None = None) -> None:
+        """Request the current state of all toolbar components.
+
+        The response will be emitted as a 'toolbar:state-response' event
+        containing component IDs and their current values.
+
+        Parameters
+        ----------
+        toolbar_id : str, optional
+            If provided, only request state for the specified toolbar.
+
+        Examples
+        --------
+        >>> handle.request_toolbar_state()
+        """
+        payload: dict[str, Any] = {}
+        if toolbar_id:
+            payload["toolbarId"] = toolbar_id
+        self.emit("toolbar:request-state", payload)
+
+    def set_toolbar_value(
+        self,
+        component_id: str,
+        value: Any = _UNSET,
+        toolbar_id: str | None = None,
+        **attrs: Any,
+    ) -> None:
+        """Set a toolbar component's value and/or attributes.
+
+        Parameters
+        ----------
+        component_id : str
+            The component_id of the toolbar item to update.
+        value : Any, optional
+            The new value for the component. Pass explicitly to set it.
+        toolbar_id : str, optional
+            The toolbar ID (if applicable).
+        **attrs : Any
+            Additional attributes to set on the component:
+            label, disabled, variant, options, style, placeholder, min, max, step.
+
+        Examples
+        --------
+        >>> handle.set_toolbar_value("theme-select", "light")
+        >>> handle.set_toolbar_value("submit-btn", disabled=True, label="Loading...")
+        """
+        payload: dict[str, Any] = {"componentId": component_id}
+        if not isinstance(value, _Unset):
+            payload["value"] = value
+        if toolbar_id:
+            payload["toolbarId"] = toolbar_id
+        payload.update(attrs)
+        self.emit("toolbar:set-value", payload)
+
+    def set_toolbar_values(
+        self, values: dict[str, Any], toolbar_id: str | None = None
+    ) -> None:
+        """Set multiple toolbar component values at once.
+
+        Parameters
+        ----------
+        values : dict[str, Any]
+            Mapping of component_id to new value.
+        toolbar_id : str, optional
+            The toolbar ID (if applicable).
+
+        Examples
+        --------
+        >>> handle.set_toolbar_values({"theme-select": "light", "zoom-input": 100})
+        """
+        payload: dict[str, Any] = {"values": values}
+        if toolbar_id:
+            payload["toolbarId"] = toolbar_id
+        self.emit("toolbar:set-values", payload)
+
     def __str__(self) -> str:
         """Return the window label."""
         return self._label
diff --git a/pywry/tests/test_widget_protocol.py b/pywry/tests/test_widget_protocol.py
index e3cfc4d..f2822aa 100644
--- a/pywry/tests/test_widget_protocol.py
+++ b/pywry/tests/test_widget_protocol.py
@@ -585,3 +585,133 @@ def test_inject_css_with_complex_styles(self, native_handle):
             result = native_handle.inject_css(css, "complex-styles")
             assert result is True
             mock_inject.assert_called_once()
+
+
+# =============================================================================
+# NativeWindowHandle Notification and Toolbar State Tests
+# =============================================================================
+
+
+class TestNativeWindowHandleAlertAndToolbar:
+    """Tests for NativeWindowHandle alert and toolbar state methods."""
+
+    def test_alert_emits_pywry_alert_event(self, native_handle, mock_app):
+        """Test alert() emits pywry:alert with correct payload."""
+        native_handle.alert("File saved successfully")
+        mock_app.emit.assert_called_once_with(
+            "pywry:alert",
+            {"message": "File saved successfully", "type": "info", "position": "top-right"},
+            "test-window",
+        )
+
+    def test_alert_with_type_and_title(self, native_handle, mock_app):
+        """Test alert() with success type and title."""
+        native_handle.alert("Export complete", alert_type="success", title="Done")
+        mock_app.emit.assert_called_once_with(
+            "pywry:alert",
+            {
+                "message": "Export complete",
+                "type": "success",
+                "position": "top-right",
+                "title": "Done",
+            },
+            "test-window",
+        )
+
+    def test_alert_with_duration(self, native_handle, mock_app):
+        """Test alert() with custom duration."""
+        native_handle.alert("Warning", alert_type="warning", duration=8000)
+        call_args = mock_app.emit.call_args
+        assert call_args[0][1]["duration"] == 8000
+        assert call_args[0][1]["type"] == "warning"
+
+    def test_alert_with_callback_event(self, native_handle, mock_app):
+        """Test alert() confirm type with callback event."""
+        native_handle.alert(
+            "Are you sure?",
+            alert_type="confirm",
+            callback_event="app:confirm",
+        )
+        call_args = mock_app.emit.call_args
+        assert call_args[0][1]["type"] == "confirm"
+        assert call_args[0][1]["callback_event"] == "app:confirm"
+
+    def test_alert_with_position(self, native_handle, mock_app):
+        """Test alert() with custom position."""
+        native_handle.alert("Notice", position="bottom-left")
+        call_args = mock_app.emit.call_args
+        assert call_args[0][1]["position"] == "bottom-left"
+
+    def test_alert_optional_fields_not_included_when_none(self, native_handle, mock_app):
+        """Test alert() omits None optional fields from payload."""
+        native_handle.alert("Simple message")
+        payload = mock_app.emit.call_args[0][1]
+        assert "title" not in payload
+        assert "duration" not in payload
+        assert "callback_event" not in payload
+
+    def test_request_toolbar_state_emits_event(self, native_handle, mock_app):
+        """Test request_toolbar_state() emits toolbar:request-state."""
+        native_handle.request_toolbar_state()
+        mock_app.emit.assert_called_once_with(
+            "toolbar:request-state", {}, "test-window"
+        )
+
+    def test_request_toolbar_state_with_toolbar_id(self, native_handle, mock_app):
+        """Test request_toolbar_state() passes toolbar_id."""
+        native_handle.request_toolbar_state(toolbar_id="toolbar-abc123")
+        mock_app.emit.assert_called_once_with(
+            "toolbar:request-state",
+            {"toolbarId": "toolbar-abc123"},
+            "test-window",
+        )
+
+    def test_set_toolbar_value_with_value(self, native_handle, mock_app):
+        """Test set_toolbar_value() emits toolbar:set-value with value."""
+        native_handle.set_toolbar_value("theme-select", "light")
+        mock_app.emit.assert_called_once_with(
+            "toolbar:set-value",
+            {"componentId": "theme-select", "value": "light"},
+            "test-window",
+        )
+
+    def test_set_toolbar_value_without_value(self, native_handle, mock_app):
+        """Test set_toolbar_value() without value only sets other attrs."""
+        native_handle.set_toolbar_value("submit-btn", disabled=True, label="Loading...")
+        call_args = mock_app.emit.call_args
+        assert call_args[0][0] == "toolbar:set-value"
+        payload = call_args[0][1]
+        assert payload["componentId"] == "submit-btn"
+        assert payload["disabled"] is True
+        assert payload["label"] == "Loading..."
+        assert "value" not in payload
+
+    def test_set_toolbar_value_with_toolbar_id(self, native_handle, mock_app):
+        """Test set_toolbar_value() passes toolbar_id."""
+        native_handle.set_toolbar_value("slider", 50, toolbar_id="toolbar-abc")
+        payload = mock_app.emit.call_args[0][1]
+        assert payload["toolbarId"] == "toolbar-abc"
+
+    def test_set_toolbar_value_none_value_not_included(self, native_handle, mock_app):
+        """Test set_toolbar_value() with no value doesn't include it in payload."""
+        native_handle.set_toolbar_value("zoom-input", label="Zoom")
+        payload = mock_app.emit.call_args[0][1]
+        assert "value" not in payload
+        assert payload["label"] == "Zoom"
+
+    def test_set_toolbar_values_emits_event(self, native_handle, mock_app):
+        """Test set_toolbar_values() emits toolbar:set-values."""
+        values = {"theme-select": "light", "zoom-input": 100}
+        native_handle.set_toolbar_values(values)
+        mock_app.emit.assert_called_once_with(
+            "toolbar:set-values",
+            {"values": values},
+            "test-window",
+        )
+
+    def test_set_toolbar_values_with_toolbar_id(self, native_handle, mock_app):
+        """Test set_toolbar_values() passes toolbar_id."""
+        native_handle.set_toolbar_values({"slider": 50}, toolbar_id="toolbar-abc")
+        payload = mock_app.emit.call_args[0][1]
+        assert payload["toolbarId"] == "toolbar-abc"
+        assert payload["values"] == {"slider": 50}

From bb24be977e5dfb995b33ee0114727c2feca5a0fd Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 21 Feb 2026 05:50:23 +0000
Subject: [PATCH 3/9] Fix ruff formatting and flaky test_set_title polling
 logic

Co-authored-by: deeleeramone <85772166+deeleeramone@users.noreply.github.com>
---
 pywry/pywry/widget_protocol.py      |  8 ++++----
 pywry/tests/test_widget_protocol.py |  4 +---
 pywry/tests/test_window_proxy.py    | 11 +++++++++--
 3 files changed, 14 insertions(+), 9 deletions(-)

diff --git a/pywry/pywry/widget_protocol.py b/pywry/pywry/widget_protocol.py
index a51da9b..b036459 100644
--- a/pywry/pywry/widget_protocol.py
+++ b/pywry/pywry/widget_protocol.py
@@ -676,7 +676,9 @@ def alert(
         --------
         >>> handle.alert("File saved successfully")
         >>> handle.alert("Export complete", alert_type="success", title="Done")
-        >>> handle.alert("Are you sure?", alert_type="confirm", callback_event="app:confirm")
+        >>> handle.alert(
+        ...     "Are you sure?", alert_type="confirm", callback_event="app:confirm"
+        ... )
         """
         payload: dict[str, Any] = {
             "message": message,
@@ -749,9 +751,7 @@ def set_toolbar_value(
         payload.update(attrs)
         self.emit("toolbar:set-value", payload)
 
-    def set_toolbar_values(
-        self, values: dict[str, Any], toolbar_id: str | None = None
-    ) -> None:
+    def set_toolbar_values(self, values: dict[str, Any], toolbar_id: str | None = None) -> None:
         """Set multiple toolbar component values at once.
 
         Parameters
diff --git a/pywry/tests/test_widget_protocol.py b/pywry/tests/test_widget_protocol.py
index f2822aa..842c432 100644
--- a/pywry/tests/test_widget_protocol.py
+++ b/pywry/tests/test_widget_protocol.py
@@ -653,9 +653,7 @@ def test_alert_optional_fields_not_included_when_none(self, native_handle, mock_
     def test_request_toolbar_state_emits_event(self, native_handle, mock_app):
         """Test request_toolbar_state() emits toolbar:request-state."""
         native_handle.request_toolbar_state()
-        mock_app.emit.assert_called_once_with(
-            "toolbar:request-state", {}, "test-window"
-        )
+        mock_app.emit.assert_called_once_with("toolbar:request-state", {}, "test-window")
 
     def test_request_toolbar_state_with_toolbar_id(self, native_handle, mock_app):
         """Test request_toolbar_state() passes toolbar_id."""
diff --git a/pywry/tests/test_window_proxy.py b/pywry/tests/test_window_proxy.py
index 473c180..dfaae53 100644
--- a/pywry/tests/test_window_proxy.py
+++ b/pywry/tests/test_window_proxy.py
@@ -170,15 +170,22 @@ class TestWindowProxyActions:
 
     def test_set_title(self) -> None:
         """set_title actually changes the window title."""
+        import contextlib
+
         app = PyWry(theme=ThemeMode.DARK)
         proxy = show_and_wait_ready(app, "<h1>Title</h1>", title="Original Title")
 
         # Change title
         proxy.set_title("New Title")
-        time.sleep(0.1)  # Allow IPC to complete
 
-        # Verify title changed
+        # Poll until title propagates through IPC (fire-and-forget is async)
+        deadline = time.time() + 3.0
         new_title = proxy.title
+        while "New Title" not in new_title and time.time() < deadline:
+            time.sleep(0.1)
+            with contextlib.suppress(IPCTimeoutError):
+                new_title = proxy.title
+
         assert "New Title" in new_title
         app.close()
 

From 19319546be71876b9f85b7d6ae13ed3623507feb Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 21 Feb 2026 05:52:26 +0000
Subject: [PATCH 4/9] Move contextlib import to module level and tighten
 polling loop

Co-authored-by: deeleeramone <85772166+deeleeramone@users.noreply.github.com>
---
 pywry/tests/test_window_proxy.py | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/pywry/tests/test_window_proxy.py b/pywry/tests/test_window_proxy.py
index dfaae53..dc4f065 100644
--- a/pywry/tests/test_window_proxy.py
+++ b/pywry/tests/test_window_proxy.py
@@ -8,6 +8,7 @@
 
 from __future__ import annotations
 
+import contextlib
 import os
 import sys
 import time
@@ -170,8 +171,6 @@ class TestWindowProxyActions:
 
     def test_set_title(self) -> None:
         """set_title actually changes the window title."""
-        import contextlib
-
         app = PyWry(theme=ThemeMode.DARK)
         proxy = show_and_wait_ready(app, "<h1>Title</h1>", title="Original Title")
 
@@ -182,9 +181,10 @@ def test_set_title(self) -> None:
         deadline = time.time() + 3.0
         new_title = proxy.title
         while "New Title" not in new_title and time.time() < deadline:
-            time.sleep(0.1)
             with contextlib.suppress(IPCTimeoutError):
                 new_title = proxy.title
+            if "New Title" not in new_title:
+                time.sleep(0.1)
 
         assert "New Title" in new_title
         app.close()

From f31355b7865bbca5a1f087e4ef763532d2d4eac5 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 21 Feb 2026 06:24:57 +0000
Subject: [PATCH 5/9] Fix flaky Windows E2E test: robust cleanup in
 retry_on_subprocess_failure

Co-authored-by: deeleeramone <85772166+deeleeramone@users.noreply.github.com>
---
 pywry/tests/test_alerts.py | 26 +++++++++++++++++++-------
 1 file changed, 19 insertions(+), 7 deletions(-)

diff --git a/pywry/tests/test_alerts.py b/pywry/tests/test_alerts.py
index c51f56a..e505199 100644
--- a/pywry/tests/test_alerts.py
+++ b/pywry/tests/test_alerts.py
@@ -13,6 +13,7 @@
 
 from __future__ import annotations
 
+import sys
 import time
 
 from collections.abc import Callable
@@ -22,7 +23,12 @@
 import pytest
 
 # Import shared test utilities from tests.conftest
-from tests.conftest import show_and_wait_ready, wait_for_result
+from tests.conftest import (
+    _clear_registries,
+    _stop_runtime_sync,
+    show_and_wait_ready,
+    wait_for_result,
+)
 
 
 F = TypeVar("F", bound=Callable[..., Any])
@@ -40,8 +46,6 @@ def retry_on_subprocess_failure(max_attempts: int = 3, delay: float = 1.0) -> Ca
     def decorator(func: F) -> F:
         @wraps(func)
         def wrapper(*args: Any, **kwargs: Any) -> Any:
-            from pywry import runtime
-
             last_error: Exception | None = None
             for attempt in range(max_attempts):
                 try:
@@ -49,10 +53,18 @@ def wrapper(*args: Any, **kwargs: Any) -> Any:
                 except (TimeoutError, AssertionError) as e:
                     last_error = e
                     if attempt < max_attempts - 1:
-                        # Clean up and wait before retry
-                        runtime.stop()
-                        # Progressive backoff for CI stability
-                        time.sleep(delay * (attempt + 1))
+                        # Stop runtime and poll until the subprocess is fully
+                        # terminated (matches _stop_runtime_sync in conftest).
+                        _stop_runtime_sync()
+                        # Clear stale callback/lifecycle state before the next
+                        # attempt so leftover registrations don't interfere.
+                        _clear_registries()
+                        # Progressive backoff.  On Windows, the OS needs extra
+                        # time after process termination before the WebView2
+                        # "Chrome_WidgetWin_0" window class registration is
+                        # released and a new subprocess can re-register it.
+                        extra = 5.0 if sys.platform == "win32" else 0.0
+                        time.sleep(delay * (attempt + 1) + extra)
             raise last_error  # type: ignore[misc]
 
         return wrapper  # type: ignore[return-value]

From fbfce263c8435eecedd37f0097464ac7d53db0e1 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 21 Feb 2026 06:27:04 +0000
Subject: [PATCH 6/9] Guard against last_error being None in retry decorator

Co-authored-by: deeleeramone <85772166+deeleeramone@users.noreply.github.com>
---
 pywry/tests/test_alerts.py | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/pywry/tests/test_alerts.py b/pywry/tests/test_alerts.py
index e505199..1344109 100644
--- a/pywry/tests/test_alerts.py
+++ b/pywry/tests/test_alerts.py
@@ -65,7 +65,9 @@ def wrapper(*args: Any, **kwargs: Any) -> Any:
                         # released and a new subprocess can re-register it.
                         extra = 5.0 if sys.platform == "win32" else 0.0
                         time.sleep(delay * (attempt + 1) + extra)
-            raise last_error  # type: ignore[misc]
+            if last_error is None:
+                raise RuntimeError("retry_on_subprocess_failure: no attempts were made")
+            raise last_error
 
         return wrapper  # type: ignore[return-value]
 

From 883b320c4cb2ae696e2db496a38815431389915f Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 21 Feb 2026 23:30:22 +0000
Subject: [PATCH 7/9] Document OAuth2 auth:* events in event reference

Co-authored-by: deeleeramone <85772166+deeleeramone@users.noreply.github.com>
---
 pywry/docs/docs/reference/events.md | 83 ++++++++++++++++++++++++++++-
 1 file changed, 82 insertions(+), 1 deletion(-)

diff --git a/pywry/docs/docs/reference/events.md b/pywry/docs/docs/reference/events.md
index 1f9e3c8..b0fc52a 100644
--- a/pywry/docs/docs/reference/events.md
+++ b/pywry/docs/docs/reference/events.md
@@ -11,7 +11,7 @@ All events follow the `namespace:event-name` pattern:
 | namespace | Starts with letter, alphanumeric | `app`, `plotly`, `grid`, `myapp` |
 | event-name | Starts with letter, alphanumeric + hyphens | `click`, `row-select`, `update-data` |
 
-**Reserved namespaces:** `pywry:*`, `plotly:*`, `grid:*`, `toolbar:*`
+**Reserved namespaces:** `pywry:*`, `plotly:*`, `grid:*`, `toolbar:*`, `auth:*`
 
 ---
 
@@ -187,6 +187,53 @@ All events follow the `namespace:event-name` pattern:
 
 ---
 
+## Auth Events (auth:*)
+
+The `auth:*` namespace is used by the built-in OAuth2 authentication system.
+Events flow in both directions: the frontend can request login/logout, and the
+backend notifies the frontend when auth state changes (e.g. after a token
+refresh or successful logout).
+
+!!! note "Availability"
+    Auth events are only active when `PYWRY_DEPLOY__AUTH_ENABLED=true` and a
+    valid `PYWRY_OAUTH2__*` configuration is present. In native mode the full
+    flow is handled by `app.login()` / `app.logout()` — these events apply to
+    the frontend integration via `window.pywry.auth`.
+
+### Auth Requests (JS → Python)
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `auth:login-request` | `{}` | Frontend requests a login flow (calls `window.pywry.auth.login()`). In native mode the backend opens the provider's authorization URL; in deploy mode it redirects to `/auth/login`. |
+| `auth:logout-request` | `{}` | Frontend requests logout (calls `window.pywry.auth.logout()`). The backend revokes tokens, destroys the session, and emits `auth:logout` back. |
+
+### Auth Notifications (Python → JS)
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `auth:state-changed` | `{authenticated, user_id?, roles?, token_type?}` | Auth state changed (login succeeded or session expired). When `authenticated` is `false`, `window.__PYWRY_AUTH__` is cleared. |
+| `auth:token-refresh` | `{token_type, expires_in?}` | Access token was refreshed in the background. Updates the current session without requiring re-login. |
+| `auth:logout` | `{}` | Server-side logout completed. Clears `window.__PYWRY_AUTH__` and notifies registered `onAuthStateChange` handlers. |
+
+**`auth:state-changed` payload detail:**
+
+```python
+{
+    "authenticated": True,
+    "user_id": "user@example.com",   # sub / id / email from userinfo
+    "roles": ["viewer", "editor"],   # from session roles list
+    "token_type": "Bearer"           # OAuth2 token type
+}
+```
+
+When `authenticated` is `false` only the key itself is present:
+
+```python
+{"authenticated": False}
+```
+
+---
+
 ## Component Event Payloads
 
 Every toolbar component emits its custom event with these payloads:
@@ -271,6 +318,40 @@ window.__PYWRY_TOOLBAR__.getValue("component-id")       // Get value
 window.__PYWRY_TOOLBAR__.setValue("component-id", value) // Set value
 ```
 
+### Auth Globals (window.pywry.auth)
+
+When `auth_enabled=True` the `auth-helpers.js` script is injected and the
+`window.pywry.auth` namespace becomes available.
+
+```javascript
+// Check authentication state
+window.pywry.auth.isAuthenticated()   // boolean
+
+// Get the full auth state
+window.pywry.auth.getState()
+// Returns: { authenticated, user_id, roles, token_type }
+
+// Trigger OAuth2 login flow (emits auth:login-request to Python)
+window.pywry.auth.login()
+
+// Trigger logout (emits auth:logout-request to Python)
+window.pywry.auth.logout()
+
+// React to auth state changes (from auth:state-changed / auth:logout events)
+window.pywry.auth.onAuthStateChange(function(state) {
+    if (state.authenticated) {
+        console.log("Logged in as", state.user_id, "with roles", state.roles);
+    } else {
+        console.log("Logged out");
+    }
+});
+```
+
+**`window.__PYWRY_AUTH__`** is injected server-side for authenticated requests and
+contains `{ user_id, roles, token_type }`. Use `window.pywry.auth.getState()`
+rather than reading it directly — the helper normalizes the value and handles
+the unauthenticated case.
+
 ### Tauri Access (Native Mode Only)
 
 In native desktop mode, Tauri APIs are available:

From 1408ead423d735923342782e7930867701b158b5 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sun, 22 Feb 2026 00:37:04 +0000
Subject: [PATCH 8/9] Add multi-widget guide, auth reference docs, and fix
 why-pywry.md typo

Co-authored-by: deeleeramone <85772166+deeleeramone@users.noreply.github.com>
---
 pywry/docs/docs/getting-started/why-pywry.md  |   1 +
 pywry/docs/docs/guides/multi-widget.md        | 162 ++++++
 pywry/docs/docs/guides/oauth2.md              | 481 ++++++++++++++++++
 .../docs/reference/auth-callback-server.md    |  14 +
 .../docs/docs/reference/auth-deploy-routes.md |  23 +
 pywry/docs/docs/reference/auth-flow.md        |  36 ++
 pywry/docs/docs/reference/auth-pkce.md        |  14 +
 pywry/docs/docs/reference/auth-providers.md   |  67 +++
 pywry/docs/docs/reference/auth-session.md     |  14 +
 pywry/docs/docs/reference/auth-token-store.md |  56 ++
 pywry/docs/docs/reference/auth.md             |  45 ++
 pywry/docs/mkdocs.yml                         |  11 +
 12 files changed, 924 insertions(+)
 create mode 100644 pywry/docs/docs/guides/multi-widget.md
 create mode 100644 pywry/docs/docs/guides/oauth2.md
 create mode 100644 pywry/docs/docs/reference/auth-callback-server.md
 create mode 100644 pywry/docs/docs/reference/auth-deploy-routes.md
 create mode 100644 pywry/docs/docs/reference/auth-flow.md
 create mode 100644 pywry/docs/docs/reference/auth-pkce.md
 create mode 100644 pywry/docs/docs/reference/auth-providers.md
 create mode 100644 pywry/docs/docs/reference/auth-session.md
 create mode 100644 pywry/docs/docs/reference/auth-token-store.md
 create mode 100644 pywry/docs/docs/reference/auth.md

diff --git a/pywry/docs/docs/getting-started/why-pywry.md b/pywry/docs/docs/getting-started/why-pywry.md
index 5530ef0..408e1c7 100644
--- a/pywry/docs/docs/getting-started/why-pywry.md
+++ b/pywry/docs/docs/getting-started/why-pywry.md
@@ -70,6 +70,7 @@ Native windows open in under a second. There's no server to spin up, no browser
 PyWry isn't just for prototyping and single-user applications:
 
 - **Deploy Mode** with Redis backend for horizontal scaling and RBAC
+- **OAuth2** authentication system for both native and deploy modes
 - **Token authentication** and CSRF protection out of the box
 - **CSP headers** and security presets for production environments
 - **TOML-based configuration** with layered precedence (defaults → project → user → env vars)
diff --git a/pywry/docs/docs/guides/multi-widget.md b/pywry/docs/docs/guides/multi-widget.md
new file mode 100644
index 0000000..43c1e8c
--- /dev/null
+++ b/pywry/docs/docs/guides/multi-widget.md
@@ -0,0 +1,162 @@
+# Multi-Widget Pages
+
+`show_plotly()` and `show_dataframe()` each render a single widget. To combine multiple widgets — charts, grids, forms, tickers — in one window, use `build_html()` to generate each piece and compose them with `Div`.
+
+## The Pattern
+
+1. **Generate HTML snippets** — `build_html()` on any component returns a self-contained HTML string.
+2. **Compose with `Div`** — Nest `Div` objects to build your page tree. Style with CSS using `--pywry-*` theme variables.
+3. **Show** — Pass combined HTML as `HtmlContent` to `app.show()` with `include_plotly` / `include_aggrid` flags as needed.
+
+Every toolbar component (`Button`, `Select`, `Toggle`, `TextInput`, `Checkbox`, `RadioGroup`, `TabGroup`, `SliderInput`, `RangeInput`, `NumberInput`, `DateInput`, `SearchInput`, `SecretInput`, `TextArea`, `MultiSelect`, `Marquee`, `TickerItem`), plus `Toolbar`, `Modal`, and `Div` all expose `build_html()`. See the [Toolbar System](toolbars.md) and [Modals](modals.md) guides for their APIs.
+
+---
+
+## Widget Snippets
+
+### Plotly
+
+```python
+import json
+from pywry.templates import build_plotly_init_script
+
+fig_dict = json.loads(fig.to_json())  # must be a plain dict, not a Figure
+chart_html = build_plotly_init_script(figure=fig_dict, chart_id="my-chart")
+```
+
+Requires `include_plotly=True` on `app.show()`. Target later with `widget.emit("plotly:update-figure", {"figure": new_dict, "chartId": "my-chart"})`.
+
+### AG Grid
+
+```python
+from pywry.grid import build_grid_config, build_grid_html
+
+config = build_grid_config(df, grid_id="my-grid", row_selection=True)
+grid_html = build_grid_html(config)
+```
+
+Requires `include_aggrid=True` on `app.show()`. Target later with `widget.emit("grid:update-data", {"data": rows, "gridId": "my-grid"})`.
+
+Use unique `chart_id` / `grid_id` values when placing multiple charts or grids on the same page.
+
+---
+
+## Composing with `Div`
+
+`Div` is the layout primitive. Use `content` for raw HTML (widget snippets, headings, text) and `children` for nested component objects. Both render in order: `content` first, then `children`.
+
+```python
+from pywry import Div, Button, Toggle
+
+dashboard = Div(
+    class_name="dashboard",
+    children=[
+        Div(class_name="kpi-row", children=[
+            Div(class_name="kpi-card", content='<span class="label">Revenue</span><span class="value">$318K</span>'),
+            Div(class_name="kpi-card", content='<span class="label">Users</span><span class="value">1,247</span>'),
+        ]),
+        Div(class_name="content-row", children=[
+            Div(class_name="chart-panel", content=chart_html),
+            Div(class_name="grid-panel", content=grid_html),
+        ]),
+        Div(class_name="controls", children=[
+            Toggle(label="Live:", event="app:live", value=True),
+            Button(label="Export", event="app:export", variant="secondary"),
+        ]),
+    ],
+)
+
+page_html = dashboard.build_html()
+```
+
+- `class_name` is added alongside the automatic `pywry-div` class — target it in CSS
+- Nested `Div`s pass parent context via `data-parent-id` automatically
+
+### Scripts
+
+`Div` and `Toolbar` accept a `script` field (inline JS or file path). `build_html()` resolves it and emits a `<script>` tag inside the `<div>`:
+
+```python
+panel = Div(content="<p>Hello</p>", script="console.log('loaded');")
+# → <div class="pywry-div" ...><p>Hello</p><script>console.log('loaded');</script></div>
+
+panel = Div(content="<p>Chart</p>", script="static/chart_init.js")  # reads file
+```
+
+`collect_scripts()` is also available if you need raw script strings without HTML wrapping.
+
+---
+
+## Showing the Page
+
+```python
+from pywry import PyWry, HtmlContent
+
+app = PyWry(title="Dashboard", width=1200, height=780)
+
+content = HtmlContent(html=dashboard.build_html(), inline_css=css)
+
+widget = app.show(
+    content,
+    include_plotly=True,
+    include_aggrid=True,
+    toolbars=[toolbar],    # optional positioned toolbar bars
+    modals=[modal],        # optional modals
+    callbacks={
+        "plotly:click": on_chart_click,
+        "grid:row-selected": on_row_selected,
+        "app:export": on_export,
+    },
+)
+```
+
+- Components embedded directly in your HTML emit events via `window.pywry.emit()` without needing `toolbars=`
+- Toolbars passed via `toolbars=` are auto-positioned (top, bottom, left, right)
+- Modals passed via `modals=` are auto-injected with open/close wiring
+
+### Sizing Tips
+
+- Plotly: set `width: 100% !important; height: 100% !important` on `.pywry-plotly` and give its parent a flex layout
+- AG Grid: needs a parent with defined height — `flex: 1` inside a flex column works
+- Use `min-height: 0` on flex children that need to shrink below content size
+
+---
+
+## Cross-Widget Events
+
+With everything in one page, wire interactions through callbacks — no JavaScript needed:
+
+```python
+# Grid selection → update chart
+def on_row_selected(data, _event_type, _label):
+    rows = data.get("rows", [])
+    widget.emit("plotly:update-figure", {"figure": filtered_fig, "chartId": "my-chart"})
+
+# Chart click → update detail panel
+def on_chart_click(data, _event_type, _label):
+    point = data.get("points", [{}])[0]
+    widget.emit("pywry:set-content", {"id": "detail-panel", "html": f"<b>{point['x']}</b>"})
+
+# Export CSV
+def on_export(_data, _event_type, _label):
+    widget.emit("pywry:download", {"content": df.to_csv(index=False), "filename": "data.csv", "mimeType": "text/csv"})
+```
+
+See the [Event System guide](events.md) for the full list of system events (`pywry:set-content`, `pywry:download`, `plotly:update-figure`, `grid:update-data`, etc.).
+
+---
+
+## Complete Example
+
+See [`examples/pywry_demo_multi_widget.py`](https://github.com/deeleeramone/PyWry/blob/main/pywry/examples/pywry_demo_multi_widget.py) for a full working dashboard with KPI cards, Plotly chart, AG Grid, toolbar, cross-widget filtering, and CSV export.
+
+---
+
+## Related Guides
+
+- [Toolbar System](toolbars.md) — all toolbar component types and their APIs
+- [Modals](modals.md) — modal overlay components
+- [Event System](events.md) — event registration and dispatch
+- [Theming & CSS](theming.md) — `--pywry-*` variables and theme switching
+- [HtmlContent](html-content.md) — CSS files, script files, inline CSS, JSON data
+- [Content Assembly](content-assembly.md) — what PyWry injects into the document
diff --git a/pywry/docs/docs/guides/oauth2.md b/pywry/docs/docs/guides/oauth2.md
new file mode 100644
index 0000000..c69d2ad
--- /dev/null
+++ b/pywry/docs/docs/guides/oauth2.md
@@ -0,0 +1,481 @@
+# OAuth2 Authentication
+
+PyWry includes a full OAuth2 authentication system for both **native mode** (desktop apps) and **deploy mode** (multi-user web servers). It supports Google, GitHub, Microsoft, and any OpenID Connect provider out of the box.
+
+This guide uses two perspectives throughout:
+
+- **Developer** — the person writing the PyWry application
+- **User** — the person running the app and logging in
+
+---
+
+## How it works (overview)
+
+=== "Native mode"
+
+    The developer calls `app.login()`. PyWry starts an ephemeral HTTP server on a
+    random `localhost` port, opens the provider's login page in the user's system
+    browser, waits for the OAuth2 redirect to land on that server, exchanges the
+    authorization code for tokens, and hands the result back to the developer's code.
+
+    The user never interacts with PyWry directly — they log in at the provider's
+    own website (Google, GitHub, etc.) and are then redirected back automatically.
+
+=== "Deploy mode"
+
+    The developer mounts a FastAPI router (`/auth/*`) on the server. The user
+    navigates to `/auth/login`, gets redirected to the provider, authenticates,
+    and lands back at `/auth/callback` where PyWry creates a server session and
+    sets a cookie. The user is then redirected to the application root (`/`).
+
+---
+
+## Developer: one-time provider setup
+
+Before writing any code, register an OAuth2 application with your chosen provider.
+Each provider's developer console will give you a **client ID** and **client secret**.
+You must also register the **redirect URI** that PyWry will use.
+
+| Mode | Redirect URI to register |
+|:---|:---|
+| Native | `http://127.0.0.1` (any port, or use a wildcard if the provider supports it) |
+| Deploy | `https://your-domain.com/auth/callback` |
+
+!!! warning "Keep your client secret private"
+    Never commit `client_secret` to version control. Use environment variables or
+    a secrets manager.
+
+Provider registration links:
+
+- **Google**: [console.cloud.google.com](https://console.cloud.google.com/) → APIs & Services → Credentials
+- **GitHub**: [github.com/settings/developers](https://github.com/settings/developers) → OAuth Apps
+- **Microsoft**: [portal.azure.com](https://portal.azure.com/) → Azure Active Directory → App registrations
+
+---
+
+## Developer: configure the provider
+
+Set credentials via environment variables (recommended) or construct the provider
+in code. PyWry reads `PYWRY_OAUTH2__*` variables automatically when
+`PYWRY_OAUTH2__CLIENT_ID` is present.
+
+=== "Environment variables"
+
+    ```bash
+    # Choose one of: google, github, microsoft, oidc, custom
+    export PYWRY_OAUTH2__PROVIDER=github
+    export PYWRY_OAUTH2__CLIENT_ID=your-client-id
+    export PYWRY_OAUTH2__CLIENT_SECRET=your-client-secret
+    ```
+
+    Other available variables:
+
+    | Variable | Default | Description |
+    |:---|:---|:---|
+    | `PYWRY_OAUTH2__SCOPES` | `openid email profile` | Space-separated scopes |
+    | `PYWRY_OAUTH2__USE_PKCE` | `true` | Enable PKCE (recommended) |
+    | `PYWRY_OAUTH2__TOKEN_STORE_BACKEND` | `memory` | `memory`, `keyring`, or `redis` |
+    | `PYWRY_OAUTH2__AUTH_TIMEOUT_SECONDS` | `120` | Seconds to wait for user callback |
+    | `PYWRY_OAUTH2__REFRESH_BUFFER_SECONDS` | `60` | Seconds before expiry to refresh |
+    | `PYWRY_OAUTH2__ISSUER_URL` | *(empty)* | OIDC discovery URL (oidc provider) |
+    | `PYWRY_OAUTH2__TENANT_ID` | `common` | Azure AD tenant (microsoft provider) |
+    | `PYWRY_OAUTH2__AUTHORIZE_URL` | *(empty)* | Required for `custom` provider |
+    | `PYWRY_OAUTH2__TOKEN_URL` | *(empty)* | Required for `custom` provider |
+
+=== "Google"
+
+    ```python
+    from pywry.auth import GoogleProvider
+
+    provider = GoogleProvider(
+        client_id="…",
+        client_secret="…",
+        # Default scopes: openid email profile
+        # Always adds access_type=offline and prompt=consent
+        # so a refresh token is returned.
+    )
+    ```
+
+=== "GitHub"
+
+    ```python
+    from pywry.auth import GitHubProvider
+
+    provider = GitHubProvider(
+        client_id="…",
+        client_secret="…",
+        # Default scopes: read:user user:email
+        # client_secret is required for token revocation.
+    )
+    ```
+
+    GitHub is not a standard OIDC provider. Userinfo comes from
+    `https://api.github.com/user`. Token revocation uses
+    `DELETE /applications/{client_id}/token` with HTTP Basic auth.
+
+=== "Microsoft / Azure AD"
+
+    ```python
+    from pywry.auth import MicrosoftProvider
+
+    provider = MicrosoftProvider(
+        client_id="…",
+        client_secret="…",
+        tenant_id="common",  # or your specific tenant GUID
+        # Default scopes: openid email profile offline_access
+    )
+    ```
+
+    Use `tenant_id="common"` for multi-tenant apps. Microsoft does not implement
+    RFC 7009, so `revoke_token()` always returns `False`.
+
+=== "Generic OIDC"
+
+    ```python
+    from pywry.auth import GenericOIDCProvider
+
+    provider = GenericOIDCProvider(
+        client_id="…",
+        client_secret="…",
+        issuer_url="https://auth.example.com",
+        # Fetches /.well-known/openid-configuration on first use.
+        # Explicit URLs take precedence over discovered ones.
+        scopes=["openid", "profile"],
+    )
+    ```
+
+=== "From settings"
+
+    When settings are loaded from config or env vars:
+
+    ```python
+    from pywry.auth import create_provider_from_settings
+    from pywry.config import get_settings
+
+    provider = create_provider_from_settings(get_settings().oauth2)
+    # Returns GoogleProvider, GitHubProvider, MicrosoftProvider,
+    # or GenericOIDCProvider based on the 'provider' field.
+    # Raises AuthenticationError for unknown types or missing URLs.
+    ```
+
+---
+
+## Native mode
+
+### Developer: call `app.login()`
+
+`PyWry.login()` is the single entry point for native mode. It constructs the
+provider, token store, session manager, and flow manager from settings, runs the
+OAuth2 flow, and returns when the user has finished authenticating (or fails).
+
+```python
+from pywry import PyWry
+from pywry.exceptions import AuthFlowTimeout, AuthFlowCancelled, AuthenticationError
+
+app = PyWry()
+
+try:
+    result = app.login()  # blocks — see "User experience" below
+except AuthFlowTimeout:
+    print("User took too long to authenticate")
+except AuthFlowCancelled:
+    print("User closed the login window")
+except AuthenticationError as e:
+    print(f"Authentication failed: {e}")
+```
+
+After a successful login:
+
+```python
+if result.success:
+    user_id   = result.user_info.get("sub") or result.user_info.get("login")
+    email     = result.user_info.get("email")
+    token     = result.tokens.access_token  # valid access token
+    expires   = result.tokens.expires_at    # float timestamp, or None
+
+app.is_authenticated  # True after a successful login()
+app.logout()          # revokes token at provider, clears store
+```
+
+`result.user_info` is the raw dict returned by the provider's userinfo endpoint.
+The keys vary by provider:
+
+| Provider | Common keys |
+|:---|:---|
+| Google | `sub`, `email`, `name`, `picture` |
+| GitHub | `id`, `login`, `email`, `name`, `avatar_url` |
+| Microsoft | `sub`, `email`, `name` |
+
+### Developer: configure token persistence
+
+By default, tokens are stored in memory and lost when the process exits. For
+desktop apps that should remember the user across restarts, use the keyring backend:
+
+```python
+result = app.login(
+    # Pass a custom token store via the flow manager if needed,
+    # or set via environment variable:
+    # PYWRY_OAUTH2__TOKEN_STORE_BACKEND=keyring
+)
+```
+
+```bash
+export PYWRY_OAUTH2__TOKEN_STORE_BACKEND=keyring
+pip install pywry[auth]  # installs the keyring package
+```
+
+See [Token Storage](#token-storage) below for all backends.
+
+### Developer: keep the access token fresh
+
+`SessionManager` runs a background `threading.Timer` that refreshes the token
+before it expires, so `app.login()` does not need to be called again after the
+initial authentication:
+
+```python
+# Constructed automatically inside app.login() using settings:
+# PYWRY_OAUTH2__REFRESH_BUFFER_SECONDS=60
+
+# To access the token at any point after login:
+token = await app._session_manager.get_access_token()
+# Automatically refreshes if the token is within 60s of expiry.
+```
+
+When the refresh token itself expires (i.e. the user has been away too long),
+re-authentication is needed. Wire `on_reauth_required` to prompt the user:
+
+```python
+from pywry.auth import SessionManager
+
+mgr = SessionManager(
+    provider=provider,
+    token_store=store,
+    session_key="user@example.com",
+    refresh_buffer_seconds=60,
+    on_reauth_required=lambda: app.login(),  # re-authenticate automatically
+)
+```
+
+### User experience (native mode)
+
+1. The developer's app calls `app.login()`.
+2. The user's **system browser opens** to the provider's login page (e.g.
+   accounts.google.com, github.com/login). PyWry does not host or render this page.
+3. The user enters their credentials at the provider's site and approves the
+   requested scopes.
+4. The provider redirects the browser to `http://127.0.0.1:{port}/callback`.
+   PyWry's ephemeral callback server responds with a plain HTML page:
+   > ✅ **Authentication Complete** — You can close this window.
+5. Control returns to the developer's code with `AuthFlowResult`.
+
+The user never sees PyWry UI during login. If the provider is slow or the user
+takes too long, `AuthFlowTimeout` is raised after `auth_timeout_seconds` (default
+120 s).
+
+---
+
+## Deploy mode
+
+### Developer: register the OAuth2 app
+
+Register `https://your-domain.com/auth/callback` as the redirect URI with the
+provider (not a `localhost` URL).
+
+### Developer: configure environment variables
+
+```bash
+# OAuth2 provider
+PYWRY_OAUTH2__PROVIDER=google
+PYWRY_OAUTH2__CLIENT_ID=…
+PYWRY_OAUTH2__CLIENT_SECRET=…
+
+# Auth middleware
+PYWRY_DEPLOY__AUTH_ENABLED=true
+PYWRY_DEPLOY__AUTH_SESSION_COOKIE=pywry_session
+PYWRY_DEPLOY__DEFAULT_ROLES=viewer
+PYWRY_DEPLOY__ADMIN_USERS=admin@example.com
+
+# Session / state backend
+PYWRY_DEPLOY__STATE_BACKEND=redis
+PYWRY_DEPLOY__REDIS_URL=redis://localhost:6379/0
+```
+
+Any user whose ID or email matches `ADMIN_USERS` gets `"admin"` added to their
+session roles automatically when they log in.
+
+### Developer: mount the auth router
+
+```python
+from pywry.auth import create_provider_from_settings, get_token_store
+from pywry.auth.deploy_routes import create_auth_router
+from pywry.state import get_session_store
+from pywry.state.auth import AuthConfig
+
+provider = create_provider_from_settings(settings.oauth2)
+
+auth_router = create_auth_router(
+    provider=provider,
+    session_store=get_session_store(),
+    token_store=get_token_store("redis", redis_url="redis://localhost:6379/0"),
+    deploy_settings=settings.deploy,
+    auth_config=AuthConfig(
+        enabled=True,
+        token_secret="your-secret-key",
+        session_ttl=86400,  # 24 hours
+    ),
+    use_pkce=True,
+)
+
+fastapi_app.include_router(auth_router)
+```
+
+This exposes six endpoints:
+
+| Route | Method | Description |
+|:---|:---|:---|
+| `/auth/login` | `GET` | Redirects the user to the provider's login page |
+| `/auth/callback` | `GET` | Receives the redirect, creates a session, sets a cookie |
+| `/auth/refresh` | `POST` | Refreshes the access token (called by frontend JS) |
+| `/auth/logout` | `POST` | Revokes the token, deletes the session, clears the cookie |
+| `/auth/userinfo` | `GET` | Returns `user_id`, `roles`, and `user_info` for the session |
+| `/auth/status` | `GET` | Returns `{authenticated, user_id, roles, expires_at}` |
+
+### Developer: protect routes
+
+Check the session on each request using the auth middleware. The session is
+populated by the `pywry_session` cookie set at `/auth/callback`:
+
+```python
+from fastapi import Request
+
+@fastapi_app.get("/dashboard")
+async def dashboard(request: Request):
+    session = getattr(request.state, "session", None)
+    if not session:
+        return RedirectResponse("/auth/login")
+    return {"user": session.user_id, "roles": session.roles}
+```
+
+### Developer: prune stale CSRF nonces
+
+`/auth/login` stores a one-time state nonce server-side. Nonces older than
+`max_age` seconds can be pruned periodically (e.g. from a background task):
+
+```python
+from pywry.auth.deploy_routes import cleanup_expired_states
+
+removed = cleanup_expired_states(max_age=600.0)  # default 10 min
+```
+
+### User experience (deploy mode)
+
+1. The user navigates to `/auth/login` (e.g. by clicking a "Sign in" button in the
+   frontend).
+2. The server generates a PKCE challenge and a CSRF state nonce, then
+   **redirects the browser** to the provider's login page.
+3. The user logs in at the provider's site and approves the scopes.
+4. The provider redirects the browser to `/auth/callback?code=…&state=…`.
+5. PyWry validates the state nonce, exchanges the code for tokens, creates a
+   session, and sets an `HttpOnly Secure SameSite=Lax` cookie.
+6. The browser is **redirected to `/`** — the user lands in the application,
+   already authenticated.
+
+To check authentication status from frontend JavaScript:
+
+```javascript
+const res = await fetch('/auth/status');
+const { authenticated, user_id, roles, expires_at } = await res.json();
+```
+
+---
+
+## Token Storage
+
+All backends implement the same async interface (`save`, `load`, `delete`, `exists`,
+`list_keys`). Select one with `get_token_store()`:
+
+```python
+from pywry.auth import get_token_store
+
+store = get_token_store("memory")                                       # default
+store = get_token_store("keyring", service_name="my-app")              # pip install pywry[auth]
+store = get_token_store("redis", redis_url="redis://localhost:6379/0") # pip install redis
+```
+
+`get_token_store` is `@lru_cache(maxsize=1)` — the same `backend` argument always
+returns the same instance.
+
+| Backend | Persistence | Best for |
+|:---|:---|:---|
+| `memory` | Process lifetime | Development, single-process apps |
+| `keyring` | OS credential store | Desktop apps that remember the user |
+| `redis` | Redis TTL | Multi-worker deploy mode |
+
+For `redis`, the TTL is `expires_in + 300` seconds (5-minute buffer for refresh).
+Keys are namespaced as `{prefix}:oauth:tokens:{key}`.
+
+---
+
+## PKCE
+
+PKCE (Proof Key for Code Exchange, RFC 7636) is enabled by default and recommended
+for all clients, especially desktop apps where the OAuth2 redirect goes to
+`localhost`. It prevents authorization code interception attacks.
+
+`AuthFlowManager` and `create_auth_router` both handle PKCE automatically.
+`PKCEChallenge` is only needed if building a custom flow:
+
+```python
+from pywry.auth import PKCEChallenge
+
+pkce = PKCEChallenge.generate(length=64)
+pkce.verifier   # sent during token exchange (code_verifier)
+pkce.challenge  # sent during authorize (base64url SHA-256 of verifier)
+pkce.method     # always "S256"
+```
+
+---
+
+## Error Handling
+
+```python
+from pywry.exceptions import (
+    AuthenticationError,  # general auth failure or bad configuration
+    AuthFlowTimeout,      # user did not complete login within auth_timeout_seconds
+    AuthFlowCancelled,    # flow.cancel() was called (e.g. user closed the window)
+    TokenExpiredError,    # token is expired and no refresh token is available
+    TokenRefreshError,    # provider rejected the refresh token
+    TokenError,           # token exchange with provider failed
+)
+```
+
+All exceptions carry contextual fields (`provider`, `flow_id`, `timeout`) where
+applicable.
+
+---
+
+## Integration with State & RBAC
+
+OAuth2 authentication integrates with the PyWry session and RBAC system:
+
+1. **OAuth2 tokens** are stored in `TokenStore`, keyed by the user's ID from
+   `user_info` (`sub`, `id`, `login`, or `email` — first non-empty).
+2. **Sessions** are created in `SessionStore` with `auth_config.session_ttl` as TTL.
+3. **Roles** default to `deploy_settings.default_roles` (`viewer` by default).
+4. **Admin promotion**: if the user's ID or email appears in
+   `deploy_settings.admin_users`, `"admin"` is appended to their roles.
+5. **`user_info`** from the provider is stored in `session.metadata["user_info"]`
+   and returned verbatim from `/auth/userinfo`.
+
+For details on sessions, RBAC, and the session store, see
+[State, Redis & RBAC](state-and-auth.md).
+
+---
+
+## Next Steps
+
+- **[State, Redis & RBAC](state-and-auth.md)** — Session store, roles, and permissions
+- **[Deploy Mode](deploy-mode.md)** — Running PyWry as a production web server
+- **[Configuration](configuration.md)** — Full settings reference including `OAuth2Settings`
+- **[API Reference: Auth](../reference/auth.md)** — Full API docs for the auth package
+
diff --git a/pywry/docs/docs/reference/auth-callback-server.md b/pywry/docs/docs/reference/auth-callback-server.md
new file mode 100644
index 0000000..1da9dcc
--- /dev/null
+++ b/pywry/docs/docs/reference/auth-callback-server.md
@@ -0,0 +1,14 @@
+# pywry.auth.callback_server
+
+Local HTTP callback server for OAuth2 redirect handling in native mode.
+
+---
+
+## OAuthCallbackServer
+
+::: pywry.auth.callback_server.OAuthCallbackServer
+    options:
+      show_root_heading: true
+      heading_level: 2
+      members_order: source
+      show_source: false
diff --git a/pywry/docs/docs/reference/auth-deploy-routes.md b/pywry/docs/docs/reference/auth-deploy-routes.md
new file mode 100644
index 0000000..d8760ae
--- /dev/null
+++ b/pywry/docs/docs/reference/auth-deploy-routes.md
@@ -0,0 +1,23 @@
+# pywry.auth.deploy_routes
+
+FastAPI routes for OAuth2 authentication in deploy mode.
+
+---
+
+## create_auth_router
+
+::: pywry.auth.deploy_routes.create_auth_router
+    options:
+      show_root_heading: true
+      heading_level: 2
+      show_source: false
+
+---
+
+## cleanup_expired_states
+
+::: pywry.auth.deploy_routes.cleanup_expired_states
+    options:
+      show_root_heading: true
+      heading_level: 2
+      show_source: false
diff --git a/pywry/docs/docs/reference/auth-flow.md b/pywry/docs/docs/reference/auth-flow.md
new file mode 100644
index 0000000..c995cc8
--- /dev/null
+++ b/pywry/docs/docs/reference/auth-flow.md
@@ -0,0 +1,36 @@
+# pywry.auth.flow
+
+OAuth2 authentication flow orchestrator.
+
+---
+
+## AuthFlowManager
+
+::: pywry.auth.flow.AuthFlowManager
+    options:
+      show_root_heading: true
+      heading_level: 2
+      members_order: source
+      show_source: false
+
+---
+
+## AuthFlowResult
+
+::: pywry.auth.flow.AuthFlowResult
+    options:
+      show_root_heading: true
+      heading_level: 2
+      members_order: source
+      show_source: false
+
+---
+
+## AuthFlowState
+
+::: pywry.auth.flow.AuthFlowState
+    options:
+      show_root_heading: true
+      heading_level: 2
+      members_order: source
+      show_source: false
diff --git a/pywry/docs/docs/reference/auth-pkce.md b/pywry/docs/docs/reference/auth-pkce.md
new file mode 100644
index 0000000..f1bfcbb
--- /dev/null
+++ b/pywry/docs/docs/reference/auth-pkce.md
@@ -0,0 +1,14 @@
+# pywry.auth.pkce
+
+Proof Key for Code Exchange (PKCE) utilities for OAuth2 authorization code flow.
+
+---
+
+## PKCEChallenge
+
+::: pywry.auth.pkce.PKCEChallenge
+    options:
+      show_root_heading: true
+      heading_level: 2
+      members_order: source
+      show_source: false
diff --git a/pywry/docs/docs/reference/auth-providers.md b/pywry/docs/docs/reference/auth-providers.md
new file mode 100644
index 0000000..5da67ac
--- /dev/null
+++ b/pywry/docs/docs/reference/auth-providers.md
@@ -0,0 +1,67 @@
+# pywry.auth.providers
+
+OAuth2 provider abstractions and concrete implementations.
+
+---
+
+## OAuthProvider (ABC)
+
+::: pywry.auth.providers.OAuthProvider
+    options:
+      show_root_heading: true
+      heading_level: 2
+      members_order: source
+      show_source: false
+
+---
+
+## GenericOIDCProvider
+
+::: pywry.auth.providers.GenericOIDCProvider
+    options:
+      show_root_heading: true
+      heading_level: 2
+      members_order: source
+      show_source: false
+
+---
+
+## GoogleProvider
+
+::: pywry.auth.providers.GoogleProvider
+    options:
+      show_root_heading: true
+      heading_level: 2
+      members_order: source
+      show_source: false
+
+---
+
+## GitHubProvider
+
+::: pywry.auth.providers.GitHubProvider
+    options:
+      show_root_heading: true
+      heading_level: 2
+      members_order: source
+      show_source: false
+
+---
+
+## MicrosoftProvider
+
+::: pywry.auth.providers.MicrosoftProvider
+    options:
+      show_root_heading: true
+      heading_level: 2
+      members_order: source
+      show_source: false
+
+---
+
+## Factory
+
+::: pywry.auth.providers.create_provider_from_settings
+    options:
+      show_root_heading: true
+      heading_level: 2
diff --git a/pywry/docs/docs/reference/auth-session.md b/pywry/docs/docs/reference/auth-session.md
new file mode 100644
index 0000000..2cb2e73
--- /dev/null
+++ b/pywry/docs/docs/reference/auth-session.md
@@ -0,0 +1,14 @@
+# pywry.auth.session
+
+OAuth2 session manager with automatic token refresh.
+
+---
+
+## SessionManager
+
+::: pywry.auth.session.SessionManager
+    options:
+      show_root_heading: true
+      heading_level: 2
+      members_order: source
+      show_source: false
diff --git a/pywry/docs/docs/reference/auth-token-store.md b/pywry/docs/docs/reference/auth-token-store.md
new file mode 100644
index 0000000..3d7f074
--- /dev/null
+++ b/pywry/docs/docs/reference/auth-token-store.md
@@ -0,0 +1,56 @@
+# pywry.auth.token_store
+
+Pluggable token storage backends for OAuth2 tokens.
+
+---
+
+## TokenStore (ABC)
+
+::: pywry.auth.token_store.TokenStore
+    options:
+      show_root_heading: true
+      heading_level: 2
+      members_order: source
+      show_source: false
+
+---
+
+## MemoryTokenStore
+
+::: pywry.auth.token_store.MemoryTokenStore
+    options:
+      show_root_heading: true
+      heading_level: 2
+      members_order: source
+      show_source: false
+
+---
+
+## KeyringTokenStore
+
+::: pywry.auth.token_store.KeyringTokenStore
+    options:
+      show_root_heading: true
+      heading_level: 2
+      members_order: source
+      show_source: false
+
+---
+
+## RedisTokenStore
+
+::: pywry.auth.token_store.RedisTokenStore
+    options:
+      show_root_heading: true
+      heading_level: 2
+      members_order: source
+      show_source: false
+
+---
+
+## Factory
+
+::: pywry.auth.token_store.get_token_store
+    options:
+      show_root_heading: true
+      heading_level: 2
diff --git a/pywry/docs/docs/reference/auth.md b/pywry/docs/docs/reference/auth.md
new file mode 100644
index 0000000..09f0cf3
--- /dev/null
+++ b/pywry/docs/docs/reference/auth.md
@@ -0,0 +1,45 @@
+# pywry.auth
+
+OAuth2 authentication system — providers, token storage, session management, and flow orchestration.
+
+---
+
+## Package Exports
+
+::: pywry.auth
+    options:
+      show_root_heading: false
+      heading_level: 2
+      members:
+        - AuthFlowManager
+        - OAuthProvider
+        - GenericOIDCProvider
+        - GoogleProvider
+        - GitHubProvider
+        - MicrosoftProvider
+        - SessionManager
+        - TokenStore
+        - MemoryTokenStore
+        - RedisTokenStore
+        - PKCEChallenge
+        - create_provider_from_settings
+        - get_token_store
+      show_if_no_docstring: false
+      show_source: false
+      show_docstring_description: true
+      show_docstring_parameters: false
+      show_docstring_returns: false
+
+---
+
+## Submodules
+
+| Module | Description |
+|:---|:---|
+| [Providers](auth-providers.md) | `OAuthProvider` ABC and concrete implementations (Google, GitHub, Microsoft, OIDC) |
+| [Token Store](auth-token-store.md) | Pluggable token storage backends (memory, keyring, Redis) |
+| [Flow](auth-flow.md) | `AuthFlowManager` — orchestrates the full OAuth2 authorization code flow |
+| [Session](auth-session.md) | `SessionManager` — token lifecycle with automatic background refresh |
+| [Deploy Routes](auth-deploy-routes.md) | FastAPI router for server-side OAuth2 in deploy mode |
+| [Callback Server](auth-callback-server.md) | Ephemeral localhost server for capturing OAuth2 redirects |
+| [PKCE](auth-pkce.md) | RFC 7636 PKCE code challenge generation |
diff --git a/pywry/docs/mkdocs.yml b/pywry/docs/mkdocs.yml
index 9af8609..11b0814 100644
--- a/pywry/docs/mkdocs.yml
+++ b/pywry/docs/mkdocs.yml
@@ -167,6 +167,7 @@ nav:
       - JavaScript Bridge: guides/javascript-bridge.md
       - Configuration: guides/configuration.md
       - State, Redis & RBAC: guides/state-and-auth.md
+      - OAuth2 Authentication: guides/oauth2.md
       - Hot Reload: guides/hot-reload.md
     - UI:
       - Toolbar System: guides/toolbars.md
@@ -176,6 +177,7 @@ nav:
     - Integrations:
       - Plotly Charts: guides/plotly.md
       - AgGrid Tables: guides/aggrid.md
+      - Multi-Widget Pages: guides/multi-widget.md
     - Hosting:
       - Browser Mode: guides/browser-mode.md
       - Deploy Mode: guides/deploy-mode.md
@@ -205,6 +207,15 @@ nav:
       - Mixins: reference/state-mixins.md
       - Auth & RBAC: reference/state-auth.md
       - Redis: reference/state-redis.md
+    - OAuth2:
+      - Overview: reference/auth.md
+      - Providers: reference/auth-providers.md
+      - Token Store: reference/auth-token-store.md
+      - Flow Manager: reference/auth-flow.md
+      - Session Manager: reference/auth-session.md
+      - Deploy Routes: reference/auth-deploy-routes.md
+      - Callback Server: reference/auth-callback-server.md
+      - PKCE: reference/auth-pkce.md
     - UI:
       - reference/components/index.md
       - CSS: reference/css.md

From 85b0ba4e656b2ae901e87c46a751b61dd4b7a545 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sun, 22 Feb 2026 00:49:56 +0000
Subject: [PATCH 9/9] Add retry_on_subprocess_failure to test_set_always_on_top
 for flaky CI fix

Co-authored-by: deeleeramone <85772166+deeleeramone@users.noreply.github.com>
---
 pywry/.pylintrc                           |    2 +-
 pywry/AGENTS.md                           |   80 +-
 pywry/README.md                           | 7529 +--------------------
 pywry/docs/docs/guides/state-and-auth.md  |    2 +
 pywry/docs/docs/stylesheets/extra.css     |    2 +-
 pywry/examples/pywry_demo_multi_widget.py |  471 ++
 pywry/examples/pywry_demo_oauth2.py       |  340 +
 pywry/pyproject.toml                      |    6 +
 pywry/pytest.ini                          |    1 -
 pywry/pywry/__main__.py                   |   10 +-
 pywry/pywry/app.py                        |  125 +
 pywry/pywry/auth/__init__.py              |   44 +
 pywry/pywry/auth/callback_server.py       |  219 +
 pywry/pywry/auth/deploy_routes.py         |  590 ++
 pywry/pywry/auth/flow.py                  |  381 ++
 pywry/pywry/auth/pkce.py                  |   52 +
 pywry/pywry/auth/providers.py             |  811 +++
 pywry/pywry/auth/session.py               |  258 +
 pywry/pywry/auth/token_store.py           |  349 +
 pywry/pywry/cli.py                        |   81 +-
 pywry/pywry/commands/__init__.py          |   15 +
 pywry/pywry/config.py                     |  276 +-
 pywry/pywry/exceptions.py                 |   96 +
 pywry/pywry/frontend/src/auth-helpers.js  |  135 +
 pywry/pywry/inline.py                     |   92 +-
 pywry/pywry/mcp/skills/authentication.md  |  139 +
 pywry/pywry/runtime.py                    |    8 +
 pywry/pywry/state/auth.py                 |   14 +-
 pywry/pywry/state/sync_helpers.py         |   50 +
 pywry/pywry/state/types.py                |   83 +
 pywry/pywry/toolbar.py                    |  129 +-
 pywry/pywry/widget_protocol.py            |  130 -
 pywry/pywry/window_manager/lifecycle.py   |   13 +
 pywry/tests/conftest.py                   |   69 +
 pywry/tests/test_alerts.py                |   32 +-
 pywry/tests/test_auth_callback_server.py  |  205 +
 pywry/tests/test_auth_deploy_routes.py    |  423 ++
 pywry/tests/test_auth_flow_integration.py |  279 +
 pywry/tests/test_auth_providers.py        |  582 ++
 pywry/tests/test_auth_rbac_integration.py |    2 +-
 pywry/tests/test_auth_session.py          |  301 +
 pywry/tests/test_auth_token_store.py      |  174 +
 pywry/tests/test_inline_e2e.py            |    7 +
 pywry/tests/test_inline_ssl.py            |    8 +
 pywry/tests/test_toolbar.py               |    4 +-
 pywry/tests/test_widget_protocol.py       |  128 -
 pywry/tests/test_window_proxy.py          |   49 +-
 47 files changed, 6906 insertions(+), 7890 deletions(-)
 create mode 100644 pywry/examples/pywry_demo_multi_widget.py
 create mode 100644 pywry/examples/pywry_demo_oauth2.py
 create mode 100644 pywry/pywry/auth/__init__.py
 create mode 100644 pywry/pywry/auth/callback_server.py
 create mode 100644 pywry/pywry/auth/deploy_routes.py
 create mode 100644 pywry/pywry/auth/flow.py
 create mode 100644 pywry/pywry/auth/pkce.py
 create mode 100644 pywry/pywry/auth/providers.py
 create mode 100644 pywry/pywry/auth/session.py
 create mode 100644 pywry/pywry/auth/token_store.py
 create mode 100644 pywry/pywry/frontend/src/auth-helpers.js
 create mode 100644 pywry/pywry/mcp/skills/authentication.md
 create mode 100644 pywry/tests/test_auth_callback_server.py
 create mode 100644 pywry/tests/test_auth_deploy_routes.py
 create mode 100644 pywry/tests/test_auth_flow_integration.py
 create mode 100644 pywry/tests/test_auth_providers.py
 create mode 100644 pywry/tests/test_auth_session.py
 create mode 100644 pywry/tests/test_auth_token_store.py

diff --git a/pywry/.pylintrc b/pywry/.pylintrc
index 02ad9f3..53e38a1 100644
--- a/pywry/.pylintrc
+++ b/pywry/.pylintrc
@@ -27,7 +27,7 @@ disable=
 
 [FORMAT]
 max-line-length=100
-max-module-lines=1000
+max-module-lines=2500
 expected-line-ending-format=
 
 [BASIC]
diff --git a/pywry/AGENTS.md b/pywry/AGENTS.md
index 506596b..5de4100 100644
--- a/pywry/AGENTS.md
+++ b/pywry/AGENTS.md
@@ -144,8 +144,18 @@ pywry/
 │   ├── _factory.py      # Factory functions for store instantiation
 │   ├── memory.py        # In-memory state backends (default)
 │   ├── redis.py         # Redis-backed state backends
-│   ├── types.py         # Type definitions (StateBackend, WidgetData, etc.)
-│   └── auth.py          # Authentication and RBAC utilities
+│   ├── types.py         # Type definitions (StateBackend, WidgetData, OAuthTokenSet, etc.)
+│   ├── auth.py          # Authentication and RBAC utilities
+│   └── sync_helpers.py  # Sync↔async bridging (run_async, wait_for_event)
+├── auth/                # OAuth2 authentication system
+│   ├── __init__.py      # Public exports
+│   ├── pkce.py          # PKCE challenge generation (RFC 7636)
+│   ├── providers.py     # OAuthProvider ABC + Google, GitHub, Microsoft, OIDC implementations
+│   ├── token_store.py   # TokenStore ABC + Memory, Keyring, Redis backends
+│   ├── callback_server.py # Ephemeral localhost server for native auth redirects
+│   ├── deploy_routes.py # FastAPI /auth/* routes for deploy mode
+│   ├── flow.py          # AuthFlowManager orchestrator
+│   └── session.py       # SessionManager with automatic token refresh
 ├── utils/               # Utility helpers
 └── window_manager/      # Window mode implementations
     ├── controller.py
@@ -1134,6 +1144,72 @@ PYWRY_DEPLOY__DEFAULT_ROLE=viewer
 
 ---
 
+## Authentication & OAuth2
+
+PyWry includes a full OAuth2 authentication system that works in both native window mode and deploy mode.
+
+### Quick Start (Native Mode)
+
+```python
+from pywry import PyWry
+
+app = PyWry()
+
+# Login with Google (configure via environment variables)
+# PYWRY_OAUTH2__PROVIDER=google
+# PYWRY_OAUTH2__CLIENT_ID=your-client-id
+# PYWRY_OAUTH2__CLIENT_SECRET=your-secret
+result = app.login()
+
+if result.success:
+    print(f"Logged in! Tokens: {result.tokens.token_type}")
+    app.show("<h1>Welcome!</h1>")
+    app.block()
+```
+
+### Quick Start (Deploy Mode)
+
+```bash
+PYWRY_DEPLOY__AUTH_ENABLED=true
+PYWRY_DEPLOY__STATE_BACKEND=redis
+PYWRY_OAUTH2__PROVIDER=github
+PYWRY_OAUTH2__CLIENT_ID=your-client-id
+PYWRY_OAUTH2__CLIENT_SECRET=your-secret
+```
+
+Deploy mode automatically mounts `/auth/login`, `/auth/callback`, `/auth/logout`, `/auth/status` routes.
+
+### Architecture
+
+| Component | File | Purpose |
+|-----------|------|---------|
+| `OAuthProvider` | `auth/providers.py` | ABC for OAuth2 providers (Google, GitHub, Microsoft, OIDC, custom) |
+| `PKCEChallenge` | `auth/pkce.py` | PKCE code challenge generation (RFC 7636) |
+| `TokenStore` | `auth/token_store.py` | ABC for token persistence (Memory, Keyring, Redis) |
+| `OAuthCallbackServer` | `auth/callback_server.py` | Ephemeral localhost HTTP server for native redirect capture |
+| `AuthFlowManager` | `auth/flow.py` | Orchestrates the complete OAuth2 flow |
+| `SessionManager` | `auth/session.py` | Token lifecycle with automatic background refresh |
+| `deploy_routes` | `auth/deploy_routes.py` | FastAPI `/auth/*` routes for production deployments |
+
+### OAuth2Settings
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `provider` | `str` | `"custom"` | `google`, `github`, `microsoft`, `oidc`, or `custom` |
+| `client_id` | `str` | `""` | OAuth2 client ID |
+| `client_secret` | `str` | `""` | Client secret (empty for PKCE public clients) |
+| `scopes` | `str` | `"openid email profile"` | Space-separated scopes |
+| `use_pkce` | `bool` | `True` | Enable PKCE for public clients |
+| `token_store_backend` | `str` | `"memory"` | `memory`, `keyring`, or `redis` |
+| `auth_timeout_seconds` | `float` | `120.0` | Max wait for OAuth callback |
+| `refresh_buffer_seconds` | `int` | `60` | Pre-expiry refresh margin |
+
+### Frontend Integration
+
+When authenticated, `window.__PYWRY_AUTH__` contains `{ user_id, roles, token_type }`. Use `window.pywry.auth.isAuthenticated()`, `.getState()`, `.login()`, `.logout()`, `.onAuthStateChange(cb)`.
+
+---
+
 ## Key Classes Reference
 
 ### Core Classes
diff --git a/pywry/README.md b/pywry/README.md
index 20a27be..15ef952 100644
--- a/pywry/README.md
+++ b/pywry/README.md
@@ -1,9 +1,21 @@
+<div align="center">
+
 ![PyWry](./pywry/frontend/assets/PyWry.png)
 
-PyWry is a blazingly fast rendering library for generating and managing native desktop windows, iFrames, and Jupyter widgets - with full bidirectional Python ↔ JavaScript communication. Get started in minutes, not hours.
+**Blazingly fast rendering library for native desktop windows, Jupyter widgets, and browser tabs.**
+
+Full bidirectional Python ↔ JavaScript communication. Get started in minutes, not hours.
+
+[![PyPI](https://img.shields.io/pypi/v/pywry?color=blue)](https://pypi.org/project/pywry/)
+[![Python](https://img.shields.io/pypi/pyversions/pywry)](https://pypi.org/project/pywry/)
+[![License](https://img.shields.io/github/license/deeleeramone/PyWry)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-live-brightgreen)](https://deeleeramone.github.io/PyWry/)
+
+</div>
 
-Unlike other similar libraries, PyWry is **not** a web dashboard framework. It is a **rendering engine** that targets three output paths from one API:
+---
 
+PyWry is **not** a web dashboard framework. It is a **rendering engine** that targets three output paths from one unified API:
 
 | Mode | Where It Runs | Backend |
 |------|---------------|---------|
@@ -11,45 +23,38 @@ Unlike other similar libraries, PyWry is **not** a web dashboard framework. It i
 | `NOTEBOOK` | Jupyter / VS Code / Colab | anywidget or IFrame + FastAPI + WebSocket |
 | `BROWSER` | System browser tab | FastAPI server + WebSocket + Redis |
 
-It uses declarative Pydantic components that automatically wrap content in a nested structure that can be targeted with CSS selectors:
-
-HEADER → LEFT | TOP → CONTENT + INSIDE → BOTTOM | RIGHT → FOOTER
-
-Built on [PyTauri](https://pypi.org/project/pytauri/) (which uses Rust's [Tauri](https://tauri.app/) framework), it leverages the OS webview instead of bundling a browser engine — a few MBs versus Electron's 150MB+ overhead.
+Built on [PyTauri](https://pypi.org/project/pytauri/) (Rust's [Tauri](https://tauri.app/) framework), it uses the OS webview instead of bundling a browser engine — a few MBs versus Electron's 150MB+ overhead.
 
-Its unified API lets you build fast and use anywhere. Batteries included.
-
-<a id="features"></a>
 <details>
 <summary><strong>Features at a Glance</strong></summary>
 
 | Feature | What It Does |
 |---------|--------------|
 | **Native Windows** | Lightweight OS webview windows (not Electron) |
-| **Jupyter Widgets** | Works in notebooks with anywidget |
+| **Jupyter Widgets** | Works in notebooks via anywidget with traitlet sync |
 | **Browser Mode** | Deploy to web with FastAPI + WebSocket |
-| **Toolbar System** | 18 declarative Pydantic components with 7 layout positions — automatic nested flexbox structure |
-| **Two-Way Events** | Python ↔ JavaScript communication with pre-wired Plotly/AgGrid events and utility events for DOM manipulation |
-| **Marquee Ticker** | Scrolling text/content with dynamic updates |
-| **AgGrid Tables** | Best-in-class Pandas → AgGrid conversion, with pre-wired grid events, context menus, and practical default gridOptions |
-| **Plotly Charts** | Plotly rendering with pre-wired plot events for Dash-like functionality when combined with Toolbar components |
-| **Toast Notifications** | Built-in alert system with positioning |
-| **Theming & CSS** | Light/dark modes, 60+ CSS variables, component ID targeting, and dynamic styling via events (`pywry:set-style`, `pywry:inject-css`) |
-| **Secrets Handling** | Secure password inputs — values stored server-side, never rendered in HTML, configurable getter and setter methods |
-| **Security** | Scoped token auth enabled by default, CSP headers, internal API protection, production presets available |
-| **Configuration** | TOML files, env vars, security presets |
-| **Hot Reload** | Live CSS/JS updates during development |
-| **Deploy Mode** | Redis backend for horizontal scaling |
+| **Toolbar System** | 18 declarative Pydantic components with 7 layout positions |
+| **Two-Way Events** | Python ↔ JavaScript with pre-wired Plotly/AgGrid events |
+| **Modals** | Overlay dialogs with toolbar components inside |
+| **AgGrid Tables** | Pandas → AgGrid conversion with pre-wired grid events |
+| **Plotly Charts** | Plotly rendering with custom modebar buttons and plot events |
+| **Toast Notifications** | Built-in alert system with configurable positioning |
+| **Theming & CSS** | Light/dark modes, 60+ CSS variables, hot reload |
+| **Secrets Handling** | Server-side password storage, never rendered in HTML |
+| **Security** | Token auth, CSP headers, production presets |
+| **Configuration** | Layered TOML files, env vars, security presets |
+| **Hot Reload** | Live CSS injection and JS updates during development |
+| **Deploy Mode** | Redis state backend for horizontal scaling |
+| **MCP Server** | AI agent integration via Model Context Protocol |
 
 </details>
 
 ## Installation
 
-Install in a virtual environment with a version of Python between 3.10 and 3.14.
-
-### Linux
+Requires Python 3.10–3.14. Install in a virtual environment.
 
-Linux requires WebKitGTK and GTK3 development libraries:
+<details>
+<summary><strong>Linux Prerequisites</strong></summary>
 
 ```bash
 # Ubuntu/Debian
@@ -59,32 +64,25 @@ sudo apt-get install libwebkit2gtk-4.1-dev libgtk-3-dev libglib2.0-dev \
     libxcb-shape0 libgl1 libegl1
 ```
 
-### Basic Installation
+</details>
 
 ```bash
 pip install pywry
 ```
 
-### Optional Extras
-
 | Extra | Command | Description |
 |-------|---------|-------------|
-| **notebook** | `pip install 'pywry[notebook]'` | anywidget for Jupyter integration (recommended) |
+| **notebook** | `pip install 'pywry[notebook]'` | anywidget for Jupyter integration |
 | **mcp** | `pip install 'pywry[mcp]'` | Model Context Protocol server for AI agents |
 | **all** | `pip install 'pywry[all]'` | All optional dependencies |
-| **dev** | `pip install 'pywry[dev]'` | Development and testing tools |
-
-For AI agent integration with MCP:
 
-```bash
-pip install 'pywry[mcp]'
-```
+> See [Installation Guide](https://deeleeramone.github.io/PyWry/getting-started/installation/) for full details.
 
 ---
 
 ## Quick Start
 
-### Hello World!
+### Hello World
 
 ```python
 from pywry import PyWry
@@ -94,35 +92,31 @@ app = PyWry()
 app.show("Hello World!")
 
 app.block()  # block the main thread until the window closes
-
-app.show("Hello again, World!")
 ```
 
-### Button Updates Content
+### Interactive Toolbar
 
 ```python
 from pywry import PyWry, Toolbar, Button
 
-# Create instance
 app = PyWry()
 
 def on_click(data, event_type, label):
-    """Update the heading text and inject custom CSS."""
     app.emit("pywry:set-content", {"selector": "h1", "text": "Toolbar Works!"}, label)
 
-# Display HTML with an interactive toolbar
 toolbar = Toolbar(
     position="top",
     items=[Button(label="Update Text", event="app:click")]
 )
+
 handle = app.show(
-    "<h1 text>Hello, World!</h1>",
+    "<h1>Hello, World!</h1>",
     toolbars=[toolbar],
     callbacks={"app:click": on_click},
 )
 ```
 
-### DataFrame -> AgGrid
+### DataFrame → AgGrid
 
 ```python
 from pywry import PyWry
@@ -133,20 +127,14 @@ app = PyWry()
 df = pd.DataFrame({"name": ["Alice", "Bob", "Carol"], "age": [30, 25, 35]})
 
 def on_select(data, event_type, label):
-    """Print selected row names."""
     names = ", ".join(row["name"] for row in data["rows"])
     app.emit("pywry:alert", {"message": f"Selected: {names}" if names else "None selected"}, label)
 
-handle = app.show_dataframe(
-    df,
-    callbacks={"grid:row-selected": on_select},
-)
+handle = app.show_dataframe(df, callbacks={"grid:row-selected": on_select})
 ```
 
 ### Plotly Chart
 
-Install Plotly into the environment first (`pip install plotly`).
-
 ```python
 from pywry import PyWry, Toolbar, Button
 import plotly.express as px
@@ -155,7409 +143,76 @@ app = PyWry(theme="light")
 
 fig = px.scatter(px.data.iris(), x="sepal_width", y="sepal_length", color="species")
 
-def on_click(data, event_type, label):
-    """Update chart title when a point is clicked."""
-    point = data["points"][0]
-    app.emit(
-        "plotly:update-layout",
-        {
-            "layout": {
-                "title": f"Clicked: ({point['x']:.2f}, {point['y']:.2f})"
-            },
-        },
-        label
-    )
-
-def on_reset(data, event_type, label):
-    """Reset the chart zoom."""
-    app.emit("plotly:reset-zoom", {}, label)
-
 handle = app.show_plotly(
     fig,
     toolbars=[Toolbar(position="top", items=[Button(label="Reset Zoom", event="app:reset")])],
-    callbacks={
-        "plotly:click": on_click,
-        "app:reset": on_reset,
-    },
+    callbacks={"app:reset": lambda d, e, l: app.emit("plotly:reset-zoom", {}, l)},
 )
 ```
 
----
-
-## Table of Contents
-
-| Section | Description |
-|---------|-------------|
-| [Features](#features) | Overview of PyWry capabilities |
-| [Installation](#installation) | How to install PyWry |
-| [Quick Start](#quick-start) | Minimal working example |
-
-**Core Documentation**
-
-| Section | Description |
-|---------|-------------|
-| [Rendering Paths](#rendering-paths) | Native Window, Notebook, IFrame, Browser modes |
-| ↳ [Native Window](#rendering-paths) ・ [Notebook Widget](#rendering-paths) ・ [Inline IFrame](#rendering-paths) ・ [Browser Mode](#rendering-paths) | |
-| [Core API](#core-api) | PyWry class, imports, display & event methods |
-| ↳ [Imports](#core-api) ・ [PyWry Class](#core-api) ・ [Display Methods](#core-api) ・ [Widget Types](#widget-types) ・ [Event Methods](#core-api) | |
-| [HtmlContent Model](#htmlcontent-model) | Advanced content configuration |
-| [WindowConfig Model](#windowconfig-model) | Window property configuration |
-| [Configuration System](#configuration-system) | TOML files, environment variables, presets |
-| ↳ [pywry.toml](#configuration-system) ・ [pyproject.toml](#configuration-system) ・ [Environment Variables](#configuration-system) ・ [Security Presets](#configuration-system) | |
-| [Hot Reload](#hot-reload) | Live CSS/JS updates during development |
-
-**Event & Toolbar Systems**
-
-| Section | Description |
-|---------|-------------|
-| [Event System](#event-system) | Bidirectional Python ↔ JS communication |
-| ↳ [Event Naming](#event-system) ・ [Handler Signature](#event-system) ・ [Toast Notifications](#toast-notifications-pywryalert) ・ [Utility Events](#utility-events-python-to-js) | |
-| [Pre-Registered Events](#pre-registered-events-built-in) | Built-in system, Plotly, and AgGrid events |
-| [Toolbar System](#toolbar-system) | All 18 toolbar components with examples |
-| ↳ [Positions & Layout](#toolbar-system) ・ [Component Reference](#toolbar-system) ・ [State Management](#toolbar-system) | |
-| [CSS Selectors and Theming](#css-selectors-and-theming) | Styling with CSS variables and classes |
-| ↳ [Theme Classes](#css-selectors-and-theming) ・ [Layout Classes](#css-selectors-and-theming) ・ [Toast Classes](#toast-notification-classes) ・ [CSS Variables](#css-selectors-and-theming) | |
-
-**Advanced Topics**
-
-| Section | Description |
-|---------|-------------|
-| [JavaScript Bridge](#javascript-bridge) | `window.pywry` API reference |
-| ↳ [Available Methods](#javascript-bridge) ・ [Injected Globals](#javascript-bridge) ・ [Plotly/AgGrid APIs](#javascript-bridge) ・ [Toolbar API](#javascript-bridge) ・ [Toast Notifications](#javascript-bridge) | |
-| [Direct Tauri API Access](#direct-tauri-api-access) | Native filesystem, dialogs, clipboard |
-| ↳ [`__TAURI__` Global](#direct-tauri-api-access) ・ [PyTauri IPC](#direct-tauri-api-access) ・ [Tauri Events](#direct-tauri-api-access) | |
-| [Managing Multiple Windows/Widgets](#managing-multiple-windowswidgets) | Window lifecycle, widget references |
-| ↳ [Window Modes](#managing-multiple-windowswidgets) ・ [Native Windows](#managing-multiple-windowswidgets) ・ [Widget Methods](#managing-multiple-windowswidgets) | |
-| [Browser Mode & Server Configuration](#browser-mode--server-configuration) | Headless/web deployment, security settings |
-| ↳ [Server Config](#server-configuration) ・ [HTTPS](#https-configuration) ・ [WebSocket Security](#websocket--api-security) | |
-| [Deploy Mode & Scaling](#deploy-mode--scaling) | Redis backend, horizontal scaling, multi-worker |
-| ↳ [State Backends](#deploy-mode--scaling) ・ [Redis Configuration](#deploy-mode--scaling) ・ [Authentication](#deploy-mode--scaling) | |
-| [CLI Commands](#cli-commands) | Command-line tools |
-| [Debugging](#debugging) | DevTools, logging, troubleshooting |
-| [Building from Source](#building-from-source) | Development setup |
-
-**Integrations**
-
-| Section | Description |
-|---------|-------------|
-| [Plotly Integration](#plotly-integration) | Charts with custom modebar buttons |
-| [AgGrid Integration](#aggrid-integration) | DataFrames with column definitions |
-| [MCP Server (AI Agents)](#mcp-server-ai-agents) | Model Context Protocol for AI agent integration |
+> See [Quick Start Guide](https://deeleeramone.github.io/PyWry/getting-started/quickstart/) and [Examples](https://deeleeramone.github.io/PyWry/examples/) for more.
 
 ---
 
-## Rendering Paths
+## Components
 
-<details>
-<summary>Click to expand</summary>
+PyWry includes 18 declarative toolbar components, all Pydantic models with 7 layout positions (`header`, `footer`, `top`, `bottom`, `left`, `right`, `inside`):
 
-**In this section:** [Native Window](#native-window) · [Notebook Widget](#notebook-widget-anywidget) · [Inline IFrame](#inline-iframe) · [Browser Mode](#browser-mode)
+| Component | Description |
+|-----------|-------------|
+| **Button** | Clickable button — primary, secondary, neutral, ghost, outline, danger, warning, icon |
+| **Select** | Dropdown select with `Option` items |
+| **MultiSelect** | Multi-select dropdown with checkboxes |
+| **TextInput** | Text input with debounce support |
+| **SecretInput** | Secure password input — values stored server-side, never in HTML |
+| **TextArea** | Multi-line text area |
+| **SearchInput** | Search input with debounce |
+| **NumberInput** | Numeric input with min/max/step |
+| **DateInput** | Date picker |
+| **SliderInput** | Slider with optional value display |
+| **RangeInput** | Dual-handle range slider |
+| **Toggle** | Boolean toggle switch |
+| **Checkbox** | Boolean checkbox |
+| **RadioGroup** | Radio button group |
+| **TabGroup** | Tab navigation |
+| **Div** | Container element for content/HTML |
+| **Marquee** | Scrolling ticker — scroll, alternate, slide, static |
+| **Modal** | Overlay dialog supporting all toolbar components |
+
+> See [Components Documentation](https://deeleeramone.github.io/PyWry/components/) for live previews, attributes, and usage examples.
+
+---
+
+## Documentation
+
+Full documentation is available at **[deeleeramone.github.io/PyWry](https://deeleeramone.github.io/PyWry/)**.
+
+| Section | Topics |
+|---------|--------|
+| [Getting Started](https://deeleeramone.github.io/PyWry/getting-started/) | Installation, Quick Start, Rendering Paths |
+| [Concepts](https://deeleeramone.github.io/PyWry/getting-started/) | `app.show()`, HtmlContent, Events, Configuration, State & RBAC, Hot Reload |
+| [UI](https://deeleeramone.github.io/PyWry/getting-started/) | Toolbar System, Modals, Toasts & Alerts, Theming & CSS |
+| [Integrations](https://deeleeramone.github.io/PyWry/getting-started/) | Plotly Charts, AgGrid Tables |
+| [Hosting](https://deeleeramone.github.io/PyWry/getting-started/) | Browser Mode, Deploy Mode |
+| [Components](https://deeleeramone.github.io/PyWry/components/) | Live previews for all 18 toolbar components + Modal |
+| [API Reference](https://deeleeramone.github.io/PyWry/reference/) | Auto-generated API docs for every class and function |
+| [MCP Server](https://deeleeramone.github.io/PyWry/mcp/) | AI agent integration via Model Context Protocol |
 
 ---
 
-PyWry automatically selects the appropriate rendering path based on your environment:
-
-| Environment | Rendering Path | Module | Return Type |
-|-------------|----------------|--------|-------------|
-| Desktop (script/terminal) | Native Window | `pywry.app.PyWry` | `NativeWindowHandle` |
-| Jupyter/VS Code with anywidget | Notebook Widget | `pywry.widget` | `PyWryWidget` |
-| Jupyter/VS Code without anywidget | Inline IFrame | `pywry.inline` | `InlineWidget` |
-| Headless / Server / SSH | Browser Mode | `pywry.window_manager.modes.browser` | `InlineWidget` |
-
-<details>
-<summary><b>Rendering Path Diagram</b></summary>
-
-```
-┌───────────────────────────────────────────────────────────────────────┐
-│                         PyWry Rendering Paths                         │
-└───────────────────────────────────────────────────────────────────────┘
-
-                            ┌──────────────────┐
-                            │   PyWry.show()   │
-                            │  show_plotly()   │
-                            │ show_dataframe() │
-                            └────────┬─────────┘
-                                     │
-                       ┌─────────────┴─────────────┐
-                       ▼                           ▼
-            ┌────────────────────┐      ┌────────────────────┐
-            │  Desktop/Terminal  │      │  Notebook/Browser  │
-            │   (GUI Available)  │      │    Environment     │
-            └─────────┬──────────┘      └──────────┬─────────┘
-                      │                            │
-                      ▼                      ┌─────┴─────┐
-            ┌──────────────────┐             ▼           ▼
-            │   NATIVE WINDOW  │      ┌───────────┐ ┌───────────┐
-            │                  │      │ Notebook? │ │ Headless/ │
-            │  PyTauri + Rust  │      │           │ │  Server   │
-            │  WebView2/WebKit │      └─────┬─────┘ └─────┬─────┘
-            │                  │            │             │
-            │  ┌────────────┐  │      ┌─────┴─────┐       ▼
-            │  │ OS WebView │  │      ▼           ▼  ┌─────────┐
-            │  │            │  │  ┌───────┐ ┌─────┐  │ BROWSER │
-            │  │ HTML/JS/CSS│  │  │ any-  │ │Falls│  │  MODE   │
-            │  └────────────┘  │  │widget │ │back │  │         │
-            │                  │  │ avail?│ │     │  │ FastAPI │
-            │  Returns: Native │  └───┬───┘ └──┬──┘  │ Server  │
-            │  WindowHandle    │      │        │     │         │
-            └──────────────────┘      ▼        │     │Opens in │
-                      │         ┌─────────┐    │     │ Browser │
-                      │         │NOTEBOOK │    │     └────┬────┘
-                      │         │ WIDGET  │    │          │
-                      │         │         │    ▼          ▼
-                      │         │anywidget│ ┌─────────┐ Returns:
-                      │         │ comms   │ │ INLINE  │ widget_id
-                      │         │         │ │ IFRAME  │ (str)
-                      │         │ Returns:│ │         │
-                      │         │PyWry-   │ │ FastAPI │
-                      │         │ Widget  │ │ Server  │
-                      │         └─────────┘ │         │
-                      │              │      │ Returns:│
-                      │              │      │ Inline- │
-                      │              │      │ Widget  │
-                      │              │      └─────────┘
-                      │              │           │
-                      ▼              ▼           ▼
-            ┌─────────────────────────────────────────────────┐
-            │              Bidirectional Events               │
-            │         Python ◄────────────► JavaScript        │
-            │                                                 │
-            │  • widget.emit("event:name", data)  (Python→JS) │
-            │  • window.pywry.emit("event:name")  (JS→Python) │
-            │  • callbacks={"event:name": handler}            │
-            └─────────────────────────────────────────────────┘
-```
-
-**Decision Flow:**
-
-1. **Desktop/Terminal with GUI** → Native Window (PyTauri + WebView)
-2. **Jupyter/VS Code + anywidget installed** → Notebook Widget (anywidget comms)
-3. **Jupyter/VS Code without anywidget** → Inline IFrame (FastAPI server)
-4. **Headless/SSH/Server** → Browser Mode (FastAPI + system browser)
-
-</details>
-
-### Native Window
-
-Uses PyTauri/Tauri to create native OS windows with WebView2 (Windows), WebKit (macOS/Linux).
-
-```python
-from pywry import PyWry, WindowMode, ThemeMode
-
-app = PyWry(
-    mode=WindowMode.SINGLE_WINDOW,  # or NEW_WINDOW, MULTI_WINDOW
-    theme=ThemeMode.DARK,
-    title="My App",
-    width=1280,
-    height=720,
-)
-
-# Display content - returns NativeWindowHandle (implements BaseWidget protocol)
-handle = app.show("<h1 id='greeting'>Hello</h1>")
-
-# Update content using built-in utility event
-# NativeWindowHandle has emit() method and .label property
-handle.emit("pywry:set-content", {"id": "greeting", "text": "Hello from Python!"})
-```
-
-> **Note:** For low-level access to the PyTauri runtime, use `from pywry import runtime` and call `runtime.emit_event(handle.label, ...)` directly. The `runtime` module is not re-exported in `__all__` but is importable from the pywry package.
-
-**Window Modes:**
-
-| Mode | Behavior |
-|------|----------|
-| `NEW_WINDOW` | Creates new window for each `show()` call |
-| `SINGLE_WINDOW` | Reuses one window, replaces content |
-| `MULTI_WINDOW` | Multiple labeled windows, update by label |
-| `NOTEBOOK` | Inline rendering in Jupyter notebooks (auto-detected) |
-| `BROWSER` | Opens in system browser, uses FastAPI server (headless/SSH) |
-
-### Notebook Widget (anywidget)
-
-When `anywidget` is installed, PyWry uses it for tighter Jupyter integration with bidirectional communication without a local server.
-
-```python
-from pywry.inline import show_plotly, show_dataframe
-
-# Returns PyWryPlotlyWidget or PyWryAgGridWidget
-widget = show_plotly(fig, callbacks={"plotly:click": my_handler})
-
-# Update theme using built-in utility event
-widget.emit("pywry:update-theme", {"theme": "plotly_white"})
-```
-
-### Inline IFrame
-
-Fallback when `anywidget` is not available. Uses FastAPI server running in background thread.
-
-```python
-from pywry.inline import show_plotly, show_dataframe
-
-# Returns InlineWidget (IFrame-based)
-widget = show_plotly(fig, callbacks={"plotly:click": my_handler})
-
-# Update theme using built-in utility event
-widget.emit("pywry:update-theme", {"theme": "plotly_white"})
-```
-
-### Browser Mode
-
-For headless environments (servers, SSH sessions, containers), use `BROWSER` mode to open content in the system's default browser:
-
-```python
-from pywry import PyWry, WindowMode
-
-app = PyWry(mode=WindowMode.BROWSER)
+## MCP Server
 
-# Opens in default browser, returns InlineWidget
-widget = app.show("<h1>Hello from Browser</h1>")
+PyWry includes a built-in [Model Context Protocol](https://modelcontextprotocol.io/) server for AI agent integration — 25 tools, 8 skills, and 20+ resources.
 
-# Block until browser tab is closed
-app.block()
+```bash
+pip install 'pywry[mcp]'
+pywry mcp --transport stdio
 ```
 
-Browser mode starts a FastAPI server and opens the widget URL in the browser. Use `app.block()` to keep the server running after your script completes.
-
-</details>
-
----
-
-## Core API
-
-<details>
-<summary>Click to expand</summary>
-
-**In this section:** [Imports](#imports) · [PyWry Class](#pywry-class) · [Display Methods](#display-methods) · [Widget Types](#widget-types) · [Event Methods](#event-methods) · [Other Methods](#other-methods) · [Window Management](#window-management)
+> See [MCP Documentation](https://deeleeramone.github.io/PyWry/mcp/) for setup with Claude Desktop, tool reference, and examples.
 
 ---
 
-### Imports
-
-```python
-# Main class
-from pywry import PyWry
-
-# Enums
-from pywry import WindowMode, ThemeMode
-
-# Models
-from pywry import HtmlContent, WindowConfig
-
-# Toolbar components
-from pywry import (
-    Toolbar, Button, Select, MultiSelect, TextInput, TextArea, SearchInput,
-    SecretInput, NumberInput, DateInput, SliderInput, RangeInput, Toggle,
-    Checkbox, RadioGroup, TabGroup, Div, Marquee, TickerItem, Option, ToolbarItem
-)
-
-# Plotly configuration (for customizing modebar, icons, buttons)
-from pywry import PlotlyConfig, PlotlyIconName, ModeBarButton, ModeBarConfig, SvgIcon, StandardButton
-
-# Grid models (for AgGrid customization)
-from pywry.grid import ColDef, ColGroupDef, DefaultColDef, RowSelection, GridOptions, GridConfig, GridData, build_grid_config, to_js_grid_config
-
-# State mixins (for extending custom widgets)
-from pywry import GridStateMixin, PlotlyStateMixin, ToolbarStateMixin
-
-# Inline functions (for notebooks)
-from pywry.inline import show_plotly, show_dataframe, block, stop_server
-
-# Notebook detection
-from pywry import NotebookEnvironment, detect_notebook_environment, is_anywidget_available, should_use_inline_rendering
-
-# Widget classes (PyWryWidget for notebooks)
-from pywry import PyWryWidget, PyWryPlotlyWidget, PyWryAgGridWidget
-
-# Widget protocol (for type checking and custom implementations)
-from pywry.widget_protocol import BaseWidget, NativeWindowHandle, is_base_widget
-
-# Window manager
-from pywry import BrowserMode, get_lifecycle
-
-# Settings (exported from pywry)
-from pywry import PyWrySettings, SecuritySettings, WindowSettings, ThemeSettings, HotReloadSettings, TimeoutSettings, AssetSettings, LogSettings
-
-# Settings (require full path import)
-from pywry.config import ServerSettings, DeploySettings
-
-# Asset loading
-from pywry import AssetLoader, get_asset_loader
-
-# Callback registry
-from pywry import CallbackFunc, WidgetType, get_registry
-
-# State management (for deploy mode / horizontal scaling)
-from pywry.state import (
-    get_widget_store,
-    get_event_bus,
-    get_connection_router,
-    get_session_store,
-    is_deploy_mode,
-    get_worker_id,
-    get_state_backend,
-    WidgetData,
-    EventMessage,
-    ConnectionInfo,
-    UserSession,
-    StateBackend,
-)
-```
-
-### PyWry Class
-
-```python
-PyWry(
-    mode: WindowMode = WindowMode.NEW_WINDOW,
-    theme: ThemeMode = ThemeMode.DARK,
-    title: str = "PyWry",
-    width: int = 800,
-    height: int = 600,
-    settings: PyWrySettings | None = None,
-    hot_reload: bool = False,
-)
-```
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `mode` | `WindowMode` | `NEW_WINDOW` | Window management mode |
-| `theme` | `ThemeMode` | `DARK` | Theme mode (DARK, LIGHT, SYSTEM) |
-| `title` | `str` | `"PyWry"` | Default window title |
-| `width` | `int` | `800` | Default window width |
-| `height` | `int` | `600` | Default window height |
-| `settings` | `PyWrySettings` | `None` | Configuration settings |
-| `hot_reload` | `bool` | `False` | Enable hot reload |
-
-### Display Methods
-
-**`show(content, ...) -> NativeWindowHandle | BaseWidget`**
-
-```python
-handle = app.show(
-    content,                    # str or HtmlContent
-    title=None,                 # Window title override
-    width=None,                 # Window width override (int for pixels, str for CSS like "60%")
-    height=None,                # Window height override
-    callbacks=None,             # Dict of event handlers {"event:name": handler}
-    include_plotly=False,       # Include Plotly.js
-    include_aggrid=False,       # Include AgGrid
-    aggrid_theme="alpine",      # quartz, alpine, balham, material
-    label=None,                 # Window label (auto-generated if None)
-    watch=None,                 # Enable file watching for hot reload
-    toolbars=None,              # List of Toolbar objects
-)
-```
-
-**`show_plotly(figure, ...) -> NativeWindowHandle | BaseWidget`**
-
-```python
-handle = app.show_plotly(
-    figure,                     # Plotly Figure or dict
-    title=None,
-    width=None,
-    height=None,
-    callbacks=None,
-    label=None,
-    inline_css=None,
-    on_click=None,              # Click callback (notebook mode)
-    on_hover=None,              # Hover callback (notebook mode)
-    on_select=None,             # Selection callback (notebook mode)
-    toolbars=None,
-    config=None,                # PlotlyConfig or dict
-)
-```
-
-**`show_dataframe(data, ...) -> NativeWindowHandle | BaseWidget`**
-
-```python
-handle = app.show_dataframe(
-    data,                       # pandas DataFrame or dict
-    title=None,
-    width=None,
-    height=None,
-    callbacks=None,
-    label=None,
-    column_defs=None,           # List of ColDef objects
-    aggrid_theme="alpine",      # quartz, alpine, balham, material
-    grid_options=None,          # GridOptions dict
-    toolbars=None,
-    inline_css=None,
-    on_cell_click=None,         # Cell click callback (notebook mode)
-    on_row_selected=None,       # Row selection callback (notebook mode)
-    server_side=False,          # Use server-side mode for large datasets (>10K rows)
-)
-```
-
-### Event Methods
-
-**Callback Signature:**
-
-```python
-def my_handler(data: dict, event_type: str, label: str) -> None:
-    """
-    data: Event payload from JavaScript
-    event_type: The event name (e.g., "app:click")
-    label: Window label that triggered the event
-    """
-    pass
-```
-
-**Sending Events to JavaScript:**
-
-> **Which `emit()` to use?**
-> - **Native mode** (`NEW_WINDOW`, `SINGLE_WINDOW`, `MULTI_WINDOW`): `show_*()` returns a `NativeWindowHandle` → use `handle.emit(event, data)` or `app.emit(event, data, handle.label)`
-> - **Notebook/Browser mode** (`NOTEBOOK`, `BROWSER`): `show_*()` returns a widget → use `widget.emit(event, data)`
->
-> The `callbacks={}` parameter in `show_*()` works identically in all modes.
-
-```python
-from pywry import PyWry
-
-app = PyWry()
-handle = app.show("<h1 id='title'>Hello</h1>")
-
-# For native mode: use handle.emit() or app.emit() with handle.label
-handle.emit("pywry:set-content", {"id": "title", "text": "Updated!"})
-# Or: app.emit("pywry:set-content", {"id": "title", "text": "Updated!"}, handle.label)
-
-# For notebook mode: show_*() returns a widget with .emit()
-# widget.emit("pywry:set-content", {"id": "title", "text": "Updated!"})
-```
-
-### Other Methods
-
-| Method | Description |
-|--------|-------------|
-| `emit(event_type, data, label=None)` | Send event to JavaScript in window(s) |
-| `alert(message, alert_type, ...)` | Show toast notification |
-| `on(event_type, handler, ...)` | Register event handler |
-| `on_grid(event_type, handler, ...)` | Register grid-specific event handler |
-| `on_chart(event_type, handler, ...)` | Register chart-specific event handler |
-| `on_toolbar(event_type, handler, ...)` | Register toolbar-specific event handler |
-| `on_html(event_type, handler, ...)` | Register HTML element event handler |
-| `on_window(event_type, handler, ...)` | Register window lifecycle event handler |
-| `eval_js(script, label=None)` | Execute JavaScript in window(s) |
-| `update_content(html, label=None)` | Update window HTML content |
-| `refresh(label=None)` | Refresh window content |
-| `refresh_css(label=None)` | Hot-reload CSS without page refresh |
-| `enable_hot_reload()` | Enable hot reload |
-| `disable_hot_reload()` | Disable hot reload |
-| `get_lifecycle()` | Get WindowLifecycle manager |
-
-### Widget Types
-
-All `show_*()` methods return a widget object that implements the `BaseWidget` protocol. The specific type depends on the rendering environment:
-
-| Type | Environment | Description |
-|------|-------------|-------------|
-| [NativeWindowHandle](#nativewindowhandle) | Desktop/Terminal | Handle for native OS windows |
-| [WindowProxy](#windowproxy) | via `handle.proxy` | Full WebviewWindow API access |
-| [PyWryWidget](#pywrywidget) | Jupyter with anywidget | anywidget-based notebook widget |
-| [InlineWidget](#inlinewidget) | Jupyter fallback / Browser | FastAPI server + IFrame widget |
-
-All widget types share a common API defined by the `BaseWidget` protocol:
-
-| Method | Description |
-|--------|-------------|
-| `emit(event_type, data)` | Send event from Python → JavaScript |
-| `on(event_type, callback)` | Register callback for JS → Python events |
-| `update(html)` | Update widget HTML content |
-| `display()` | Display widget (notebooks only) |
-| `label` | Property: unique widget/window identifier |
-
-#### NativeWindowHandle
-
-Handle for native desktop windows. Returned by `show_*()` methods when running in desktop/terminal mode. Wraps native window resources and provides the same API as notebook widgets.
-
-<details>
-<summary><strong>Usage Example</strong></summary>
-
-```python
-from pywry import PyWry
-
-app = PyWry()
-handle = app.show("<h1>Hello</h1>", title="My Window")
-
-# BaseWidget protocol methods
-handle.emit("update", {"value": 42})        # Send event to JS
-handle.on("click", my_handler)              # Register callback
-handle.update("<h1>New content</h1>")       # Update HTML
-print(handle.label)                         # Window label identifier
-
-# Window control methods
-handle.close()                              # Close/destroy window
-handle.hide()                               # Hide (keep alive)
-handle.show_window()                        # Show hidden window
-handle.eval_js("console.log('Hi')")         # Execute JavaScript
-
-# Window state methods
-handle.maximize()                           # Maximize window
-handle.minimize()                           # Minimize window
-handle.center()                             # Center on screen
-handle.set_title("New Title")               # Change title
-handle.set_size(1024, 768)                  # Resize window
-
-# Advanced: WindowProxy access
-handle.proxy.set_always_on_top(True)        # Full WebviewWindow API
-handle.proxy.open_devtools()                # Open developer tools
-handle.proxy.set_zoom(1.5)                  # Set zoom level
-
-# Metadata access
-print(handle.resources.created_at)          # Window creation time
-print(handle.resources.config.title)        # Window configuration
-```
-
-</details>
-
-**Properties:**
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `label` | `str` | Window label identifier |
-| `resources` | `WindowResources` | Window metadata (config, creation time, watched files) |
-| `proxy` | `WindowProxy` | Full WebviewWindow API access |
-
-**Window Control Methods:**
-
-| Method | Description |
-|--------|-------------|
-| `close()` | Close and destroy the window |
-| `hide()` | Hide window without destroying |
-| `show_window()` | Show a hidden window |
-| `eval_js(script)` | Execute JavaScript in window |
-| `maximize()` | Maximize window |
-| `minimize()` | Minimize window |
-| `center()` | Center window on screen |
-| `set_title(title)` | Set window title |
-| `set_size(width, height)` | Set window dimensions |
-
-#### WindowProxy
-
-Full WebviewWindow API access for native windows. Accessed via `handle.proxy` property on `NativeWindowHandle`. Provides direct IPC to the pytauri subprocess for complete window control.
-
-```python
-proxy = handle.proxy  # Get WindowProxy from NativeWindowHandle
-
-# State queries
-print(proxy.is_maximized)       # bool
-print(proxy.is_fullscreen)      # bool
-print(proxy.title)              # str
-print(proxy.scale_factor)       # float
-
-# Window actions
-proxy.maximize()
-proxy.center()
-proxy.set_always_on_top(True)
-
-# Appearance
-proxy.set_background_color((30, 30, 30, 255))  # RGBA tuple
-proxy.set_theme(Theme.DARK)
-proxy.set_decorations(False)
-
-# Webview operations
-proxy.navigate("https://example.com")
-proxy.set_zoom(1.5)
-proxy.open_devtools()
-```
-
-<details>
-<summary><strong>State Properties (Read-Only)</strong></summary>
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `label` | `str` | Window label |
-| `title` | `str` | Window title |
-| `url` | `str` | Current URL |
-| `theme` | `Theme` | Current theme |
-| `scale_factor` | `float` | Display scale factor |
-| `inner_position` | `PhysicalPosition` | Inner position (x, y) |
-| `outer_position` | `PhysicalPosition` | Outer position (x, y) |
-| `inner_size` | `PhysicalSize` | Inner dimensions (width, height) |
-| `outer_size` | `PhysicalSize` | Outer dimensions (width, height) |
-| `cursor_position` | `PhysicalPosition` | Cursor position relative to window |
-| `current_monitor` | `Monitor \| None` | Current monitor info |
-| `primary_monitor` | `Monitor \| None` | Primary monitor info |
-| `available_monitors` | `list[Monitor]` | All available monitors |
-
-</details>
-
-<details>
-<summary><strong>Boolean State Properties</strong></summary>
-
-| Property | Description |
-|----------|-------------|
-| `is_fullscreen` | Window is in fullscreen mode |
-| `is_minimized` | Window is minimized |
-| `is_maximized` | Window is maximized |
-| `is_focused` | Window has focus |
-| `is_decorated` | Window has decorations (title bar, borders) |
-| `is_resizable` | Window can be resized |
-| `is_enabled` | Window is enabled |
-| `is_visible` | Window is visible |
-| `is_closable` | Window can be closed |
-| `is_maximizable` | Window can be maximized |
-| `is_minimizable` | Window can be minimized |
-| `is_always_on_top` | Window stays above others |
-| `is_devtools_open` | DevTools is open |
-
-</details>
-
-<details>
-<summary><strong>Window Actions (No Parameters)</strong></summary>
-
-| Method | Description |
-|--------|-------------|
-| `show()` | Show the window |
-| `hide()` | Hide the window |
-| `close()` | Close the window |
-| `destroy()` | Destroy the window |
-| `maximize()` | Maximize the window |
-| `unmaximize()` | Restore from maximized |
-| `minimize()` | Minimize the window |
-| `unminimize()` | Restore from minimized |
-| `center()` | Center window on screen |
-| `set_focus()` | Set focus to window |
-| `reload()` | Reload the webview |
-| `print_page()` | Print the page |
-| `open_devtools()` | Open DevTools |
-| `close_devtools()` | Close DevTools |
-| `clear_all_browsing_data()` | Clear all browsing data |
-| `start_dragging()` | Start window dragging |
-
-</details>
-
-<details>
-<summary><strong>Window Actions (With Parameters)</strong></summary>
-
-| Method | Parameters | Description | Platform |
-|--------|------------|-------------|----------|
-| `request_user_attention(type)` | `UserAttentionType \| None` | Flash/bounce window | All |
-| `set_title(title)` | `str` | Set window title | All |
-| `set_size(size)` | `SizeType` | Set window size | All |
-| `set_min_size(size)` | `SizeType \| None` | Set minimum size | All |
-| `set_max_size(size)` | `SizeType \| None` | Set maximum size | All |
-| `set_position(pos)` | `PositionType` | Set window position | All |
-| `set_fullscreen(enable)` | `bool` | Toggle fullscreen | All |
-| `set_decorations(enable)` | `bool` | Toggle decorations | All |
-| `set_always_on_top(enable)` | `bool` | Toggle always-on-top | All |
-| `set_resizable(enable)` | `bool` | Toggle resizable | All |
-| `set_enabled(enable)` | `bool` | Toggle enabled | Windows |
-| `set_closable(enable)` | `bool` | Toggle closable | macOS |
-| `set_maximizable(enable)` | `bool` | Toggle maximizable | macOS |
-| `set_minimizable(enable)` | `bool` | Toggle minimizable | macOS |
-| `set_visible_on_all_workspaces(enable)` | `bool` | Toggle multi-workspace visibility | macOS, Linux |
-| `set_skip_taskbar(skip)` | `bool` | Toggle taskbar visibility | Windows, Linux |
-| `set_cursor_icon(icon)` | `CursorIcon` | Set cursor icon | All |
-| `set_cursor_position(pos)` | `PositionType` | Set cursor position | All |
-| `set_cursor_visible(visible)` | `bool` | Toggle cursor visibility | All |
-| `set_cursor_grab(grab)` | `bool` | Toggle cursor grab | All |
-| `set_icon(icon)` | `bytes \| None` | Set window icon (PNG bytes) | Windows, Linux |
-| `set_shadow(enable)` | `bool` | Toggle window shadow | Windows, macOS |
-| `set_title_bar_style(style)` | `TitleBarStyle` | Set title bar style | macOS |
-| `set_theme(theme)` | `Theme \| None` | Set window theme | All |
-
-</details>
-
-<details>
-<summary><strong>Webview Operations</strong></summary>
-
-| Method | Parameters | Description |
-|--------|------------|-------------|
-| `eval(script)` | `str` | Execute JavaScript (fire-and-forget) |
-| `eval_with_result(script, timeout)` | `str`, `float` | Execute JavaScript and return result |
-| `navigate(url)` | `str` | Navigate to URL |
-| `set_zoom(scale)` | `float` | Set zoom level |
-| `set_background_color(color)` | `Color` | Set background color (r, g, b, a) |
-
-</details>
-
-<details>
-<summary><strong>Visual Effects & Progress (Platform-Specific)</strong></summary>
-
-| Method | Parameters | Description | Platform |
-|--------|------------|-------------|----------|
-| `set_effects(effects)` | `Effects` | Set window visual effects | Windows, macOS |
-| `set_progress_bar(state)` | `ProgressBarState` | Set progress indicator | Windows (taskbar), macOS (dock) |
-| `set_badge_count(count)` | `int \| None` | Set badge count | macOS (dock), Linux (some DEs) |
-| `set_overlay_icon(icon)` | `bytes \| None` | Set overlay icon on taskbar | Windows only |
-
-**EffectState Values (for `Effects.effects` list):**
-
-| Value | Platform | Description |
-|-------|----------|-------------|
-| `BLUR` | Windows | Standard blur effect |
-| `ACRYLIC` | Windows | Acrylic blur (Windows 10+) |
-| `MICA` | Windows | Mica material (Windows 11+) |
-| `MICA_DARK` | Windows | Mica dark variant |
-| `MICA_LIGHT` | Windows | Mica light variant |
-| `TABBED` | Windows | Tabbed Mica variant |
-| `TABBED_DARK` | Windows | Tabbed dark variant |
-| `TABBED_LIGHT` | Windows | Tabbed light variant |
-| `UNDER_WINDOW_BACKGROUND` | macOS | Behind window vibrancy |
-| `CONTENT_BACKGROUND` | macOS | Content area vibrancy |
-| `SIDEBAR` | macOS | Sidebar vibrancy |
-| `HEADER_VIEW` | macOS | Header vibrancy |
-| `SHEET` | macOS | Sheet vibrancy |
-| `WINDOW_BACKGROUND` | macOS | Window background vibrancy |
-| `HUD_WINDOW` | macOS | HUD overlay vibrancy |
-| `FULLSCREEN_UI` | macOS | Fullscreen UI vibrancy |
-| `TOOLTIP` | macOS | Tooltip vibrancy |
-| `MENU` | macOS | Menu vibrancy |
-| `POPOVER` | macOS | Popover vibrancy |
-| `SELECTION` | macOS | Selection vibrancy |
-
-**ProgressBarState Fields:**
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `progress` | `float \| None` | Progress value (0.0 - 1.0), or None for indeterminate |
-| `status` | `ProgressBarStatus` | Status indicator: `NONE`, `NORMAL`, `INDETERMINATE`, `PAUSED`, `ERROR` |
-
-</details>
-
-<details>
-<summary><strong>Cookie Management</strong></summary>
-
-| Method | Parameters | Description |
-|--------|------------|-------------|
-| `cookies()` | — | Get all cookies |
-| `set_cookie(cookie)` | `Cookie` | Set a cookie |
-| `delete_cookie(name)` | `str` | Delete cookie by name |
-
-</details>
-
-#### PyWryWidget
-
-> **Requires:** `pip install 'pywry[notebook]'` (installs anywidget)
-
-anywidget-based notebook widget. Returned by `show_*()` methods when running in Jupyter with anywidget installed. Provides real-time bidirectional communication via traitlet sync. **Best performance for notebooks.**
-
-If anywidget is not installed, PyWry automatically falls back to [InlineWidget](#inlinewidget).
-
-<details>
-<summary><strong>Usage Example</strong></summary>
-
-```python
-from pywry import PyWry
-
-app = PyWry()
-widget = app.show("<h1>Hello</h1>")
-
-# BaseWidget protocol methods
-widget.emit("update", {"value": 42})
-widget.on("click", my_handler)
-widget.update("<h1>New content</h1>")
-widget.display()  # Show in notebook cell
-
-# Access widget properties
-print(widget.label)   # Widget ID
-print(widget.content) # Current HTML content
-print(widget.theme)   # 'dark' or 'light'
-```
-
-</details>
-
-**Traitlet Properties (synced with frontend):**
-
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `content` | `str` | `""` | HTML content to render |
-| `theme` | `str` | `"dark"` | Color theme |
-| `width` | `str` | `"100%"` | Widget width (CSS value) |
-| `height` | `str` | `"500px"` | Widget height (CSS value) |
-
-**Methods:**
-
-| Method | Description |
-|--------|-------------|
-| `emit(event_type, data)` | Send event to JavaScript |
-| `on(event_type, callback)` | Register event callback |
-| `update(html)` | Update HTML content |
-| `set_content(content)` | Alias for `update()` |
-| `display()` | Display widget in notebook cell |
-| `from_html(content, callbacks, ...)` | Class method to create widget from HTML |
-
-**Factory Method:**
-
-```python
-# Create widget directly with callbacks
-widget = PyWryWidget.from_html(
-    content="<h1>Hello</h1>",
-    callbacks={"button:click": my_handler},
-    theme="dark",
-    width="100%",
-    height="500px",
-    toolbars=[...],  # Optional toolbar configs
-)
-```
-
-#### InlineWidget
-
-FastAPI + IFrame widget. Returned when anywidget is not available or in browser mode. Uses FastAPI server with WebSocket communication.
-
-<details>
-<summary><strong>Usage Example</strong></summary>
+## License
 
-```python
-from pywry import PyWry
-
-app = PyWry()
-widget = app.show("<h1>Hello</h1>")
-
-# BaseWidget protocol methods
-widget.emit("update", {"value": 42})
-widget.on("click", my_handler)
-widget.update("<h1>New content</h1>")
-widget.display()  # Show IFrame in notebook
-
-# Widget properties
-print(widget.label)      # Widget ID
-print(widget.widget_id)  # Same as label
-print(widget.url)        # http://localhost:8765/widget/{id}
-
-# Open in browser
-widget.open_in_browser()
-
-# Toast notifications
-widget.alert("Success!", alert_type="success")
-```
-
-</details>
-
-**Properties:**
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `widget_id` | `str` | Unique widget identifier |
-| `label` | `str` | Alias for `widget_id` (BaseWidget protocol) |
-| `url` | `str` | Full URL to access widget |
-| `output` | `Output` | IPython Output widget for callback messages |
-
-**Methods:**
-
-| Method | Description |
-|--------|-------------|
-| `emit(event_type, data)` | Send event to JavaScript |
-| `send(event_type, data)` | Alias for `emit()` |
-| `on(event_type, callback)` | Register event callback |
-| `update(html)` | Update HTML content |
-| `update_html(html)` | Alias for `update()` |
-| `display()` | Display IFrame and output widget in notebook |
-| `open_in_browser()` | Open widget URL in system browser |
-| `alert(message, ...)` | Show toast notification |
-
-<details>
-<summary><strong>Toast Notifications</strong></summary>
-
-```python
-# Basic alerts
-widget.alert("Operation complete", alert_type="success")
-widget.alert("Something went wrong", alert_type="error")
-widget.alert("Please confirm", alert_type="warning")
-
-# With options
-widget.alert(
-    message="File saved successfully",
-    alert_type="success",
-    title="Save Complete",
-    duration=5000,           # Auto-dismiss after 5 seconds
-    position="bottom-right", # top-right, top-left, bottom-right, bottom-left
-)
-
-# Confirmation dialog
-widget.alert(
-    message="Delete this item?",
-    alert_type="confirm",
-    callback_event="confirm:delete",  # Emits event with user response
-)
-```
-
-</details>
-
-<details>
-<summary><strong>Constructor Parameters</strong></summary>
-
-```python
-InlineWidget(
-    html: str,                        # HTML content to render
-    callbacks: dict | None = None,    # Event callbacks
-    width: str = "100%",              # Widget width
-    height: int = 500,                # Widget height in pixels
-    port: int | None = None,          # Server port (default from settings)
-    widget_id: str | None = None,     # Custom widget ID
-    headers: dict | None = None,      # Custom HTTP headers
-    auth: Any | None = None,          # Authentication config
-    browser_only: bool = False,       # Skip IPython requirement
-    token: str | None = None,         # Widget access token
-)
-```
-
-</details>
-
-Used as fallback when anywidget unavailable, or for browser mode deployment.
-
-### Window Management
-
-> **See also:** [Managing Multiple Windows/Widgets](#managing-multiple-windowswidgets) for comprehensive coverage of both native windows and notebook widgets, including return types, widget properties, and lifecycle management.
-
-PyWry provides fine-grained control over window visibility and lifecycle through [NativeWindowHandle](#nativewindowhandle) methods and `PyWry` app methods. Windows can be shown, hidden, and closed independently.
-
-**App-Level Methods (operate on labels):**
-
-| Method | Description |
-|--------|-------------|
-| `show_window(label)` | Show a hidden window (brings to front) |
-| `hide_window(label)` | Hide a window (keeps it alive, not destroyed) |
-| `close(label)` | Close/destroy a specific window permanently |
-| `close()` | Close/destroy all windows |
-| `get_labels()` | Get list of currently visible window labels |
-| `block(label=None)` | Block until specific window or all windows close |
-
-**Handle-Level Methods (via NativeWindowHandle):**
-
-You can also control windows directly through the [NativeWindowHandle](#nativewindowhandle) returned by `show_*()`:
-
-```python
-handle = app.show("<h1>Hello</h1>")
-handle.hide()         # Same as app.hide_window(handle.label)
-handle.show_window()  # Same as app.show_window(handle.label)
-handle.close()        # Same as app.close(handle.label)
-```
-
-See [NativeWindowHandle](#nativewindowhandle) for the full API including `maximize()`, `minimize()`, `center()`, `set_title()`, and `proxy` access.
-
-**Window Lifecycle:**
-
-```
-Created → Visible → Hidden → Visible → Closed
-             ↑         │                  ↑
-             └─────────┘                  │
-          (show_window)                (close)
-```
-
-**X Button Behavior by Mode:**
-
-| Mode | X Button | Behavior |
-|------|----------|----------|
-| `SINGLE_WINDOW` | Always hides | Window reused on next `show()` |
-| `NEW_WINDOW` | Always closes | Window destroyed, cannot recover |
-| `MULTI_WINDOW` | Configurable | Uses `on_window_close` setting |
-
-For `MULTI_WINDOW`, use `on_window_close` to control whether clicking X hides or destroys windows:
-
-```python
-from pywry import PyWry, PyWrySettings, WindowMode
-
-# X button hides windows (default) - can recover with show_window()
-app = PyWry(mode=WindowMode.MULTI_WINDOW)
-
-# X button destroys windows - cannot recover
-settings = PyWrySettings()
-settings.window.on_window_close = "close"
-app = PyWry(mode=WindowMode.MULTI_WINDOW, settings=settings)
-```
-
-**Example: Managing Multiple Windows**
-
-```python
-from pywry import PyWry, WindowMode
-
-app = PyWry(mode=WindowMode.MULTI_WINDOW)
-
-# Create windows with labels
-app.show("<h1>Dashboard</h1>", label="dashboard")
-app.show("<h1>Settings</h1>", label="settings")
-app.show("<h1>Help</h1>", label="help")
-
-# Check visible windows
-print(app.get_labels())  # ['dashboard', 'settings', 'help']
-
-# Hide the settings window
-app.hide_window("settings")
-print(app.get_labels())  # ['dashboard', 'help']
-
-# Bring it back
-app.show_window("settings")
-print(app.get_labels())  # ['dashboard', 'settings', 'help']
-
-# Close the help window permanently
-app.close("help")
-print(app.get_labels())  # ['dashboard', 'settings']
-
-# Block until specific window closes
-app.block("dashboard")  # Waits only for dashboard to close
-
-print(app.get_labels())
-# Or block until all windows close
-app.block()  # Waits for all remaining windows
-```
-
-**SINGLE_WINDOW Mode Behavior:**
-
-In `SINGLE_WINDOW` mode, calling `show()` multiple times reuses the same window without destroying it. If the window was hidden, it will be shown again with the new content:
-
-```python
-from pywry import PyWry, WindowMode
-
-app = PyWry(mode=WindowMode.SINGLE_WINDOW)
-
-# First show - creates window
-app.show("<h1>Page 1</h1>")
-
-# User hides window (clicks X)...
-
-# Second show - reuses window, shows it again
-app.show("<h1>Page 2</h1>")  # No "destroying" - just updates content
-
-app.block()
-```
-
-</details>
-
----
-
-## HtmlContent Model
-
-<details>
-<summary>Click to expand</summary>
-
-For advanced content configuration, use the `HtmlContent` model:
-
-```python
-from pywry import PyWry, HtmlContent
-
-app = PyWry()
-
-content = HtmlContent(
-    html="<div id='app'></div>",
-    json_data={"key": "value"},
-    init_script="console.log('ready');",
-    css_files=["styles/main.css"],
-    script_files=["js/app.js"],
-    inline_css="body { margin: 0; }",
-    watch=True,
-)
-
-app.show(content)
-```
-
-**Fields:**
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `html` | `str` | Required | HTML content |
-| `json_data` | `dict` | `None` | Injected as `window.json_data` |
-| `init_script` | `str` | `None` | Custom initialization JavaScript |
-| `css_files` | `list[Path \| str]` | `None` | CSS files to include |
-| `script_files` | `list[Path \| str]` | `None` | JS files to include |
-| `inline_css` | `str` | `None` | Inline CSS styles |
-| `watch` | `bool` | `False` | Enable hot reload for these files |
-
-</details>
-
----
-
-## WindowConfig Model
-
-<details>
-<summary>Click to expand</summary>
-
-The `WindowConfig` model controls window properties:
-
-```python
-from pywry import WindowConfig, ThemeMode
-
-config = WindowConfig(
-    title="My Window",
-    width=1280,
-    height=720,
-    theme=ThemeMode.DARK,
-)
-```
-
-**Fields:**
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `title` | `str` | `"PyWry"` | Window title |
-| `width` | `int` | `1280` | Window width (min: 200) |
-| `height` | `int` | `720` | Window height (min: 150) |
-| `min_width` | `int` | `400` | Minimum width (min: 100) |
-| `min_height` | `int` | `300` | Minimum height (min: 100) |
-| `theme` | `ThemeMode` | `DARK` | Theme mode |
-| `center` | `bool` | `True` | Center window on screen |
-| `resizable` | `bool` | `True` | Allow window resizing |
-| `decorations` | `bool` | `True` | Show window decorations |
-| `always_on_top` | `bool` | `False` | Keep window above others |
-| `devtools` | `bool` | `False` | Open developer tools |
-| `allow_network` | `bool` | `True` | Allow network requests |
-| `enable_plotly` | `bool` | `False` | Include Plotly.js library |
-| `enable_aggrid` | `bool` | `False` | Include AgGrid library |
-| `plotly_theme` | `str` | `"plotly_dark"` | Plotly theme |
-| `aggrid_theme` | `str` | `"alpine"` | AgGrid theme |
-
-</details>
-
----
-
-## Configuration System
-
-<details>
-<summary>Click to expand</summary>
-
-**In this section:** [pywry.toml](#configuration-file-pywrytoml) · [pyproject.toml](#pyprojecttoml) · [Environment Variables](#environment-variables) · [Configuration Sections](#configuration-sections) · [Programmatic Config](#programmatic-configuration) · [Security Presets](#security-presets)
-
----
-
-PyWry uses a layered configuration system. Settings are merged in this order (highest priority last):
-
-1. **Built-in defaults**
-2. **pyproject.toml**: `[tool.pywry]` section
-3. **Project config**: `./pywry.toml`
-4. **User config**: `~/.config/pywry/config.toml` (Linux/macOS) or `%APPDATA%\pywry\config.toml` (Windows)
-5. **Environment variables**: `PYWRY_*` prefix
-
-User config overrides project-level settings, allowing personal preferences across all projects.
-
-### Configuration File (pywry.toml)
-
-```toml
-[theme]
-# Optional: Path to custom CSS file for styling overrides
-# css_file = "/path/to/custom.css"
-
-[window]
-title = "My Application"
-width = 1280
-height = 720
-center = true
-resizable = true
-devtools = false
-on_window_close = "hide"  # "hide" or "close" (MULTI_WINDOW only)
-
-[timeout]
-startup = 10.0
-response = 5.0
-create_window = 5.0
-set_content = 5.0
-shutdown = 2.0
-
-[hot_reload]
-enabled = true
-debounce_ms = 100
-css_reload = "inject"
-preserve_scroll = true
-watch_directories = ["./src", "./styles"]
-
-[csp]
-default_src = "'self' 'unsafe-inline' 'unsafe-eval' data: blob:"
-connect_src = "'self' http://*:* https://*:* ws://*:* wss://*:*"
-script_src = "'self' 'unsafe-inline' 'unsafe-eval'"
-style_src = "'self' 'unsafe-inline'"
-img_src = "'self' http://*:* https://*:* data: blob:"
-font_src = "'self' data:"
-
-[asset]
-plotly_version = "3.3.1"
-aggrid_version = "35.0.0"
-
-[log]
-level = "WARNING"
-format = "%(name)s - %(levelname)s - %(message)s"
-
-[deploy]
-state_backend = "redis"  # "memory" or "redis"
-redis_url = "redis://localhost:6379/0"
-redis_prefix = "pywry:"
-widget_ttl = 86400  # 24 hours in seconds
-connection_ttl = 300  # 5 minutes
-auto_cleanup = true
-enable_auth = false
-# auth_secret = "your-secret-key"  # Required if enable_auth = true
-# rbac_enabled = false
-# default_role = "viewer"
-```
-
-### pyproject.toml
-
-Add configuration to your existing `pyproject.toml`:
-
-```toml
-[tool.pywry]
-[tool.pywry.window]
-title = "My App"
-width = 1280
-
-[tool.pywry.log]
-level = "DEBUG"
-```
-
-### Environment Variables
-
-Override any setting with environment variables using the pattern `PYWRY_{SECTION}__{KEY}`:
-
-```bash
-export PYWRY_WINDOW__TITLE="Production App"
-export PYWRY_WINDOW__WIDTH=1920
-export PYWRY_WINDOW__ON_WINDOW_CLOSE="close"  # "hide" or "close" (MULTI_WINDOW only)
-export PYWRY_THEME__CSS_FILE="/path/to/custom.css"
-export PYWRY_HOT_RELOAD__ENABLED=true
-export PYWRY_LOG__LEVEL=DEBUG
-```
-
-### Configuration Sections
-
-| Section | Env Prefix | Description |
-|---------|------------|-------------|
-| `csp` | `PYWRY_CSP__` | Content Security Policy directives |
-| `theme` | `PYWRY_THEME__` | Custom CSS file path |
-| `timeout` | `PYWRY_TIMEOUT__` | Timeout values in seconds |
-| `asset` | `PYWRY_ASSET__` | Library versions and asset paths |
-| `log` | `PYWRY_LOG__` | Log level and format |
-| `window` | `PYWRY_WINDOW__` | Default window properties |
-| `hot_reload` | `PYWRY_HOT_RELOAD__` | Hot reload behavior |
-| `server` | `PYWRY_SERVER__` | Inline server settings (host, port, CORS, security) |
-| `deploy` | `PYWRY_DEPLOY__` | Deploy mode settings (Redis, scaling, auth) |
-
-#### Server Security Settings
-
-| Setting | Env Variable | Default | Description |
-|---------|--------------|---------|-------------|
-| `websocket_allowed_origins` | `PYWRY_SERVER__WEBSOCKET_ALLOWED_ORIGINS` | `[]` | Allowed WebSocket origins (empty = any) |
-| `websocket_require_token` | `PYWRY_SERVER__WEBSOCKET_REQUIRE_TOKEN` | `true` | Require per-widget token |
-| `internal_api_header` | `PYWRY_SERVER__INTERNAL_API_HEADER` | `X-PyWry-Token` | Internal API auth header |
-| `internal_api_token` | `PYWRY_SERVER__INTERNAL_API_TOKEN` | auto-generated | Internal API token |
-| `strict_widget_auth` | `PYWRY_SERVER__STRICT_WIDGET_AUTH` | `false` | Strict widget endpoint auth |
-
-#### Deploy Mode Settings
-
-| Setting | Env Variable | Default | Description |
-|---------|--------------|---------|-------------|
-| `state_backend` | `PYWRY_DEPLOY__STATE_BACKEND` | `memory` | State storage backend (`memory` or `redis`) |
-| `redis_url` | `PYWRY_DEPLOY__REDIS_URL` | `redis://localhost:6379/0` | Redis connection URL |
-| `redis_prefix` | `PYWRY_DEPLOY__REDIS_PREFIX` | `pywry` | Key prefix for Redis keys |
-| `widget_ttl` | `PYWRY_DEPLOY__WIDGET_TTL` | `86400` | Widget data TTL (seconds) |
-| `auth_enabled` | `PYWRY_DEPLOY__AUTH_ENABLED` | `false` | Enable authentication |
-
-See the [Deploy Mode & Scaling](#deploy-mode--scaling) section for complete documentation.
-
-### Programmatic Configuration
-
-Pass settings directly to PyWry:
-
-```python
-from pywry import PyWry, PyWrySettings, WindowSettings
-
-settings = PyWrySettings(
-    window=WindowSettings(
-        title="My App",
-        width=1920,
-        height=1080,
-    )
-)
-
-pywry = PyWry(settings=settings)
-```
-
-### Security Presets
-
-PyWry provides CSP (Content Security Policy) factory methods:
-
-```python
-from pywry import SecuritySettings
-
-# Permissive - allows unsafe-inline/eval (default, good for development)
-permissive = SecuritySettings.permissive()
-
-# Strict - removes unsafe-eval, restricts to self and specific CDNs
-strict = SecuritySettings.strict()
-
-# Localhost - allows only localhost connections
-localhost = SecuritySettings.localhost()
-
-# Localhost with specific ports
-localhost_ports = SecuritySettings.localhost(ports=[8000, 8080])
-```
-
-</details>
-
----
-
-## Hot Reload
-
-<details>
-<summary>Click to expand</summary>
-
-**In this section:** [Enable Hot Reload](#enable-hot-reload) · [Behavior](#behavior) · [Watch Files](#watch-files) · [Manual CSS Reload](#manual-css-reload) · [Configuration](#configuration)
-
----
-
-Hot reload enables live updates during development without restarting.
-
-### Enable Hot Reload
-
-```python
-# Via constructor
-pywry = PyWry(hot_reload=True)
-
-# Or enable/disable at runtime
-pywry.enable_hot_reload()
-pywry.disable_hot_reload()
-```
-
-### Behavior
-
-| File Type | Behavior |
-|-----------|----------|
-| **CSS** | Injected without page reload |
-| **JS/HTML** | Full page refresh with scroll preservation |
-
-### Watch Files
-
-Use the `watch` parameter in `HtmlContent` or `show()`:
-
-```python
-from pywry import PyWry, HtmlContent
-
-pywry = PyWry(hot_reload=True)
-
-content = HtmlContent(
-    html="<div id='app'></div>",
-    css_files=["styles/main.css", "styles/theme.css"],
-    script_files=["js/app.js"],
-    watch=True,
-)
-
-pywry.show(content)
-# Editing main.css will inject new styles instantly
-```
-
-Or pass `watch=True` directly to `show()`:
-
-```python
-pywry.show("<h1>Hello</h1>", watch=True)
-```
-
-### Manual CSS Reload
-
-```python
-# Reload CSS for all windows
-pywry.refresh_css()
-
-# Reload CSS for specific window
-pywry.refresh_css(label="main-window")
-```
-
-### Configuration
-
-```toml
-[hot_reload]
-enabled = true
-debounce_ms = 100        # Wait before reloading (milliseconds)
-css_reload = "inject"    # "inject" or "refresh"
-preserve_scroll = true   # Keep scroll position on JS refresh
-watch_directories = ["./src", "./styles"]
-```
-
-</details>
-
----
-
-## Event System
-
-<a id="utility-events-python-to-js"></a>
-
-<details>
-<summary>Click to expand</summary>
-
-**In this section:** [What is an Event?](#what-is-an-event) · [Event Naming](#event-naming-format) · [Reserved Namespaces](#reserved-namespaces) · [Handler Signature](#handler-signature) · [Registering Handlers](#registering-handlers) · [Wildcard Handlers](#wildcard-handlers)
-
----
-
-PyWry provides bidirectional communication between Python and JavaScript through a **namespace-based event system**. This allows your Python code to respond to user interactions in the browser (clicks, selections, form inputs) and to send updates back to the browser UI.
-
-### What is an Event?
-
-An **event** is a message with a name and optional data. Events flow in two directions:
-
-1. **JS → Python**: User does something in the browser (clicks a chart, selects a row) → JavaScript sends an event → Python callback is triggered
-2. **Python → JS**: Your Python code wants to update the UI → Python sends an event → JavaScript handler updates the display
-
-### Event Naming Format
-
-All events follow the pattern: `namespace:event-name`
-
-| Part | Rules | Examples |
-|------|-------|----------|
-| **namespace** | Starts with letter, alphanumeric only | `app`, `plotly`, `grid`, `myapp` |
-| **event-name** | Starts with letter, alphanumeric + hyphens + underscores | `click`, `row-select`, `update_data` |
-
-**Valid examples:** `app:save`, `plotly:click`, `grid:row-select`, `myapp:refresh`
-
-**Invalid examples:** `save` (no namespace), `:click` (empty namespace), `123:event` (starts with number)
-
-> **Note:** JavaScript validation is stricter (lowercase only) than Python validation. For maximum compatibility, use **lowercase with hyphens** (e.g., `app:my-action`).
-
-#### Compound Event IDs (Advanced)
-
-Events can optionally include a third component for targeting specific widgets: `namespace:event-name:component-id`
-
-```python
-# Handle clicks from ANY chart
-app.on("plotly:click", handle_all_charts)
-
-# Handle clicks from a SPECIFIC chart
-app.on("plotly:click:sales-chart", handle_sales_chart)
-```
-
-### Reserved Namespaces
-
-These namespaces are used by PyWry internally. **Do not use them for custom events:**
-
-| Namespace | Purpose |
-|-----------|---------|
-| `pywry:*` | System events (initialization, results) |
-| `plotly:*` | Plotly chart events |
-| `grid:*` | AgGrid table events |
-
-> **Tip:** Use a namespace that makes sense for your app (e.g., `app:`, `data:`, `view:`, `myapp:`).
-
-### Handler Signature
-
-All event handlers receive three arguments:
-
-```python
-def handler(data: dict, event_type: str, label: str) -> None:
-    """
-    Parameters
-    ----------
-    data : dict
-        Event payload from JavaScript (e.g., clicked point, selected rows)
-    event_type : str
-        The event that was triggered (e.g., "plotly:click", "app:export")
-    label : str
-        Window/widget identifier (e.g., "main", "chart-1")
-    """
-    pass
-```
-
-PyWry inspects your function signature and supports shorter versions for convenience:
-
-```python
-from pywry import PyWry, Toolbar, Button
-
-app = PyWry()
-
-# Full signature (recommended) - access all context
-def on_action1(data, event_type, label):
-    app.emit("pywry:set-content", {"id": "log", "text": f"[{label}] {event_type}: {data}"}, label)
-
-# Two parameters - when you don't need the widget label
-def on_action2(data, event_type):
-    print(f"{event_type} received")
-
-# One parameter - simplest, just the data
-def on_action3(data):
-    print(str(data))
-
-handle = app.show(
-    '<div id="log" style="padding:20px;">Click a button...</div>',
-    toolbars=[Toolbar(position="top", items=[
-        Button(label="Action 1", event="app:action1"),
-        Button(label="Action 2", event="app:action2"),
-        Button(label="Action 3", event="app:action3"),
-    ])],
-    callbacks={
-        "app:action1": on_action1,
-        "app:action2": on_action2,
-        "app:action3": on_action3,
-    }
-)
-```
-
-### Registering Handlers
-
-**All modes support the `callbacks={}` parameter in `show()` methods.** This is the most portable approach.
-
-| Mode | `callbacks={}` | `app.on()` | `widget.on()` | Returns |
-|------|----------------|------------|---------------|---------|
-| Native Window | ✅ | ✅ | ✅ | `NativeWindowHandle` |
-| Notebook (anywidget) | ✅ | ❌ | ✅ | `PyWryWidget` |
-| Browser Mode | ✅ | ❌ | ✅ | `InlineWidget` |
-
-#### Option 1: `callbacks={}` in show() — Works Everywhere
-
-```python
-from pywry import PyWry, Toolbar, Button
-import plotly.express as px
-
-app = PyWry()
-
-# Create a Plotly figure
-fig = px.scatter(px.data.iris(), x="sepal_width", y="sepal_length", color="species")
-
-def on_click(data, event_type, label):
-    """When user clicks a point, print the coordinates."""
-    point = data["points"][0]
-    print(f"Clicked: ({point['x']:.2f}, {point['y']:.2f})")
-
-def on_export(data, event_type, label):
-    """When export is clicked, save CSV."""
-    csv_content = px.data.iris().to_csv(index=False)
-    print(f"Exporting {len(csv_content)} bytes...")
-
-# Works in ALL modes (native returns NativeWindowHandle, notebook returns widget)
-handle = app.show_plotly(
-    fig,
-    toolbars=[Toolbar(position="top", items=[Button(label="Export CSV", event="app:export")])],
-    callbacks={
-        "plotly:click": on_click,
-        "app:export": on_export,
-    }
-)
-```
-
-#### Option 2: `app.on()` — Native Windows Only
-
-For native desktop windows, you can register handlers separately using `app.on()`. **Important:** You must use the same `label` when registering handlers and showing content:
-
-```python
-from pywry import PyWry, Toolbar, Button
-import plotly.express as px
-
-app = PyWry()
-
-fig = px.scatter(px.data.iris(), x="sepal_width", y="sepal_length", color="species")
-
-def on_click(data, event_type, label):
-    """When user clicks a point, update the chart title."""
-    point = data["points"][0]
-    app.emit("plotly:update-layout", {
-        "layout": {"title": f"Selected: ({point['x']:.2f}, {point['y']:.2f})"}
-    }, label)
-
-def on_zoom_reset(data, event_type, label):
-    """Reset chart zoom when button is clicked."""
-    app.emit("plotly:reset-zoom", {}, label)
-
-# Register handlers with explicit label BEFORE calling show()
-app.on("plotly:click", on_click, label="my-chart")
-app.on("app:zoom-reset", on_zoom_reset, label="my-chart")
-
-# Use the SAME label when showing content
-handle = app.show_plotly(
-    fig,
-    title="Click points to select them",
-    toolbars=[Toolbar(position="top", items=[Button(label="Reset Zoom", event="app:zoom-reset")])],
-    label="my-chart",  # Must match the label used in app.on()
-)
-```
-
-> **Note:** If you omit the `label` parameter, `show()` generates a random label and `app.on()` registers to `"main"`, causing a mismatch. For simpler code, prefer `callbacks={}` in `show()` (Option 1).
-```
-
-#### Option 3: `widget.on()` — All Modes
-
-All widgets (native and notebook) support chaining handlers after `show()`. This is useful for adding handlers dynamically:
-
-```python
-from pywry import PyWry, Toolbar, Button
-import plotly.express as px
-
-app = PyWry()
-
-fig = px.scatter(px.data.iris(), x="sepal_width", y="sepal_length", color="species")
-
-def on_click(data, event_type, label):
-    """When user clicks a point, update the chart title."""
-    point = data["points"][0]
-    app.emit("plotly:update-layout", {
-        "layout": {"title": f"Last clicked: ({point['x']:.2f}, {point['y']:.2f})"}
-    }, label)
-
-def on_theme_toggle(data, event_type, label):
-    """Toggle to dark theme."""
-    app.emit("pywry:update-theme", {"theme": "plotly_dark"}, label)
-
-# Using callbacks={} is recommended for most cases
-handle = app.show_plotly(
-    fig,
-    title="Click points to annotate",
-    toolbars=[Toolbar(position="top", items=[Button(label="Dark Mode", event="app:theme")])],
-    callbacks={
-        "plotly:click": on_click,
-        "app:theme": on_theme_toggle,
-    }
-)
-
-# handle.on() can add additional handlers after show()
-# handle.on("plotly:hover", on_hover)
-```
-
-### Wildcard Handlers
-
-Wildcard handlers receive ALL events — useful for debugging during development:
-
-```python
-from pywry import PyWry, Toolbar, Button
-
-app = PyWry()
-
-def log_event(data, event_type, label):
-    """Log the event to console."""
-    print(f"[{event_type}] {data}")
-
-# Show content with toolbar buttons
-handle = app.show(
-    '<div id="log" style="padding:20px; font-family:monospace;">Click a button above...</div>',
-    toolbars=[
-        Toolbar(position="top", items=[
-            Button(label="Action 1", event="app:action1"),
-            Button(label="Action 2", event="app:action2"),
-        ])
-    ],
-    # Use callbacks for each event - no race condition
-    callbacks={
-        "app:action1": log_event,
-        "app:action2": log_event,
-    }
-)
-```
-
-> **Note:** For true wildcard logging in native mode, use `app.on("*", handler)` but be aware that events firing before `handle` is assigned (like `window:ready`) will need a guard check.
-
----
-
-## Pre-Registered Events (Built-in)
-
-PyWry automatically hooks into Plotly and AgGrid event systems. These **pre-registered events** are emitted automatically when users interact with charts and grids — **no JavaScript required**.
-
-**In this section:** [What "Pre-Registered" Means](#what-pre-registered-means) · [Understanding IDs](#understanding-ids-label-vs-chartidgrididcomponentid) · [System Events](#system-events-pywry) · [Toast Notifications](#toast-notifications-pywryalert) · [Plotly Events](#plotly-events-plotly) · [AgGrid Events](#aggrid-events-grid) · [Toolbar Events](#toolbar-events-toolbar)
-
-### What "Pre-Registered" Means
-
-When you create a Plotly chart or AgGrid table, PyWry injects JavaScript that:
-1. Listens for native library events (e.g., Plotly's `plotly_click`)
-2. Transforms the raw event data into a standardized payload
-3. Emits a PyWry event (e.g., `plotly:click`) that triggers your Python callback
-
-**You just register a Python handler; PyWry handles the JavaScript wiring.**
-
-### Understanding IDs: label vs. chartId/gridId/componentId
-
-PyWry uses a hierarchy of identifiers:
-
-| ID Type | Scope | Purpose | Example |
-|---------|-------|---------|---------|
-| `label` | Window/Widget | Identifies a window (native) or widget (notebook/browser) | `"pywry-abc123"`, `"w-def456"` |
-| `chartId` | Component | Identifies a specific Plotly chart within a window | `"sales-chart"` |
-| `gridId` | Component | Identifies a specific AgGrid table within a window | `"users-grid"` |
-| `componentId` | Toolbar Item | Identifies a specific toolbar control | `"theme-select"`, `"export-btn"` |
-
-**Event Payloads Include IDs:**
-- **Plotly events** (`plotly:click`, `plotly:hover`, etc.) include `chartId` and `widget_type: "chart"` in the payload.
-- **AgGrid events** (`grid:row-selected`, `grid:cell-click`, `grid:cell-edit`, etc.) include `gridId` and `widget_type: "grid"` in the payload.
-- **Toolbar components** always include `componentId` in their payloads.
-- **Python → JS events** support targeting via `chartId`/`gridId` when using widget methods like `widget.update_figure(fig, chart_id="my-chart")`.
-
-### System Events (`pywry:*`)
-
-These are internal events for window/widget lifecycle and utility operations.
-
-#### Lifecycle Events (JS → Python)
-
-| Event | Payload | Description |
-|-------|---------|-------------|
-| `pywry:ready` | `{}` | Window/widget has finished initializing |
-| `pywry:result` | `any` | Data sent via `window.pywry.result(data)` |
-| `pywry:content-request` | `{ widget_type, window_label, reason }` | Window requests content (initial load or reload) |
-| `pywry:disconnect` | `{}` | Widget disconnected (inline/browser mode only) |
-
-#### Utility Events (Python → JS)
-
-These events trigger built-in browser behaviors. They are handled automatically by PyWry's JavaScript bridge — **no custom JavaScript required**:
-
-| Event | Payload | Description |
-|-------|---------|-------------|
-| `pywry:update-theme` | `{ theme: str }` | Update theme dynamically (e.g., `"plotly_dark"`, `"plotly_white"`) |
-| `pywry:inject-css` | `{ css: str, id?: str }` | Inject CSS dynamically; optional `id` for replacing existing styles |
-| `pywry:remove-css` | `{ id: str }` | Remove a previously injected CSS style element by ID |
-| `pywry:set-style` | `{ id?: str, selector?: str, styles: {} }` | Update inline styles on element(s) by id or CSS selector |
-| `pywry:set-content` | `{ id?: str, selector?: str, html?: str, text?: str }` | Update innerHTML or textContent on element(s) |
-| `pywry:update-html` | `{ html: str }` | Replace entire widget/window HTML content |
-| `pywry:download` | `{ content: str, filename: str, mimeType?: str }` | Trigger a file download |
-| `pywry:download-csv` | `{ csv: str, filename: str }` | Trigger a CSV file download (Jupyter widget mode) |
-| `pywry:navigate` | `{ url: str }` | Navigate to a URL (SPA-style navigation) |
-| `pywry:alert` | `{ message, type?, title?, duration?, position? }` | Show a toast notification (info, success, warning, error, confirm) |
-| `pywry:refresh` | `{}` | Request fresh content from Python (triggers content re-send) |
-
-**Example: DOM Manipulation Without Custom JavaScript**
-
-```python
-from pywry import PyWry
-import time
-
-app = PyWry()
-
-# Show HTML with elements we'll manipulate
-html = """
-<div style="padding: 20px; font-family: sans-serif;">
-    <h1 id="title">Dashboard</h1>
-    <span id="status-badge" style="padding: 4px 8px; border-radius: 4px; background: gray; color: white;">
-        Loading...
-    </span>
-    <div class="data-row" style="margin: 10px 0; padding: 10px; border: 1px solid #ccc;">
-        Row 1: <span class="status-text">Pending</span>
-    </div>
-    <div class="data-row" style="margin: 10px 0; padding: 10px; border: 1px solid #ccc;">
-        Row 2: <span class="status-text">Pending</span>
-    </div>
-    <p id="values-display">Waiting for data...</p>
-</div>
-"""
-
-handle = app.show(html, title="DOM Manipulation Demo")
-
-# Update the status badge style
-handle.emit("pywry:set-style", {
-    "id": "status-badge",
-    "styles": {"backgroundColor": "green", "color": "white"}
-})
-
-time.sleep(1)
-# Update all rows with a highlight (by CSS selector)
-handle.emit("pywry:set-style", {
-    "selector": ".data-row",
-    "styles": {"borderColor": "#3b82f6", "borderWidth": "2px"}  # Blue border
-})
-
-time.sleep(1)
-# Update content by ID (with HTML)
-handle.emit("pywry:set-content", {
-    "id": "values-display",
-    "html": "<strong>Updated!</strong> 42 items loaded"
-})
-time.sleep(1)
-# Update all status-text elements (plain text, safer)
-handle.emit("pywry:set-content", {
-    "selector": ".status-text",
-    "text": "Complete"
-})
-
-# Update the badge text
-handle.emit("pywry:set-content", {
-    "id": "status-badge",
-    "text": "Ready"
-})
-time.sleep(1)
-# Inject custom CSS dynamically
-handle.emit("pywry:inject-css", {
-    "css": "#title { color: #2563eb; }",
-    "id": "my-styles"
-})
-time.sleep(2)
-
-handle.close()
-```
-
-> **Note:** For notebook mode, use `widget.emit("pywry:...", {...})` on the returned widget instead.
-> `pywry:set-style` and `pywry:set-content` support either `id` (for a single element by ID) or `selector` (for multiple elements via CSS selector). If both are provided, `id` takes precedence.
-
-### Toast Notifications (`pywry:alert`)
-
-<details>
-<summary>Alert System</summary>
-
-PyWry provides a unified toast notification system that works consistently across all rendering paths (native window, notebook, and browser). Toast notifications are non-blocking (except `confirm` type) and support multiple types with automatic dismiss behavior.
-
-#### Alert Types
-
-| Type | Icon | Default Behavior | Use Case |
-|------|------|------------------|----------|
-| `info` | ℹ️ | Auto-dismiss 5s | Status updates, general information |
-| `success` | ✅ | Auto-dismiss 3s | Completed actions, confirmations |
-| `warning` | ⚠️ | Persist until clicked | Important notices requiring attention |
-| `error` | ⛔ | Persist until clicked | Errors requiring acknowledgment |
-| `confirm` | ❓ | Blocks UI until response | User confirmation needed before action |
-
-#### Example
-
-```python
-from pywry import PyWry, Toolbar, Button
-
-app = PyWry()
-
-# Create a toolbar with buttons for each alert type
-toolbar = Toolbar(
-    position="top",
-    items=[
-        Button(label="ℹ️ Info", event="alert:info"),
-        Button(label="✅ Success", event="alert:success"),
-        Button(label="⚠️ Warning", event="alert:warning"),
-        Button(label="⛔ Error", event="alert:error"),
-        Button(label="❓ Confirm", event="alert:confirm"),
-    ]
-)
-
-def show_info(data, event_type, label):
-    app.alert("Data refreshed successfully", alert_type="info", label=label)
-
-def show_success(data, event_type, label):
-    app.alert("Export complete!", alert_type="success", title="Done", label=label)
-
-def show_warning(data, event_type, label):
-    app.alert("No items selected.", alert_type="warning", title="Selection Required", label=label)
-
-def show_error(data, event_type, label):
-    app.alert("Failed to connect to server.", alert_type="error", title="Connection Error", label=label)
-
-def show_confirm(data, event_type, label):
-    app.alert(
-        "Are you sure you want to delete these items?",
-        alert_type="confirm",
-        title="Confirm Delete",
-        callback_event="alert:confirm-response",
-        label=label
-    )
-
-def handle_confirm_response(data, event_type, label):
-    if data.get("confirmed"):
-        app.alert("Items deleted successfully", alert_type="success", label=label)
-    else:
-        app.alert("Deletion cancelled", alert_type="info", label=label)
-
-handle = app.show(
-    "<h1>Alert Demo</h1><p>Click the toolbar buttons to see different alert types.</p>",
-    title="Toast Notifications",
-    toolbars=[toolbar],
-    callbacks={
-        "alert:info": show_info,
-        "alert:success": show_success,
-        "alert:warning": show_warning,
-        "alert:error": show_error,
-        "alert:confirm": show_confirm,
-        "alert:confirm-response": handle_confirm_response,
-    }
-)
-```
-
-> **Note:** The `callback_event` parameter specifies which event to emit when the user clicks Confirm or Cancel. Register a handler for that event in your `callbacks={}` dict to process the response.
-
-#### Using emit() Directly
-
-```python
-# Same as app.alert() but with explicit event emission
-handle.emit("pywry:alert", {
-    "message": "Processing complete",
-    "type": "success",
-    "title": "Done",
-    "duration": 4000,  # Override auto-dismiss time (ms)
-    "position": "bottom-right"  # top-right, top-left, bottom-right, bottom-left
-})
-```
-
-#### Toast Positions
-
-Toasts can be positioned in any corner of the widget container:
-
-| Position | Description |
-|----------|-------------|
-| `top-right` | Top-right corner (default) |
-| `top-left` | Top-left corner |
-| `bottom-right` | Bottom-right corner |
-| `bottom-left` | Bottom-left corner |
-
-```python
-# Position toast in different corners
-handle.emit("pywry:alert", {"message": "Top right", "position": "top-right"})
-handle.emit("pywry:alert", {"message": "Bottom left", "position": "bottom-left"})
-```
-
-#### Multiple Toasts and Stacking
-
-Multiple toasts stack vertically in their position container. New toasts appear at the top of the stack. When a toast is dismissed, remaining toasts stay in position without animation to prevent jarring visual effects.
-
-```python
-# Show multiple toasts - they stack
-app.alert("First message", alert_type="info", label=handle.label)
-app.alert("Second message", alert_type="success", label=handle.label)
-app.alert("Third message", alert_type="warning", label=handle.label)
-```
-
-#### Keyboard Shortcuts
-
-| Key | Action |
-|-----|--------|
-| `Escape` | Dismiss all visible toasts in the widget |
-
-#### JavaScript API (Advanced)
-
-The toast system exposes a global `PYWRY_TOAST` object for custom JavaScript integrations:
-
-```javascript
-// Show a toast programmatically
-window.PYWRY_TOAST.show({
-    message: "Hello from JS",
-    type: "info",
-    title: "Custom Title",
-    duration: 5000,
-    position: "top-right",
-    container: document.querySelector('.pywry-widget')
-});
-
-// Show a confirm dialog
-window.PYWRY_TOAST.confirm({
-    message: "Are you sure?",
-    title: "Confirm",
-    position: "top-right",
-    container: document.querySelector('.pywry-widget'),
-    onConfirm: function() { console.log("Confirmed"); },
-    onCancel: function() { console.log("Cancelled"); }
-});
-
-// Dismiss a specific toast by ID
-window.PYWRY_TOAST.dismiss(toastId);
-
-// Dismiss all toasts in a widget
-window.PYWRY_TOAST.dismissAllInWidget(container);
-```
-
-</details>
-
-### Plotly Events (`plotly:*`)
-
-#### Events from JavaScript → Python (User Interactions)
-
-These events fire automatically when users interact with Plotly charts:
-
-| Event | Trigger | Payload |
-|-------|---------|---------|
-| `plotly:click` | User clicks a data point | `{ chartId, widget_type, points: [...], point_indices: [...], curve_number, event }` |
-| `plotly:hover` | User hovers over a point | `{ chartId, widget_type, points: [...], point_indices: [...], curve_number }` |
-| `plotly:selected` | User selects with box/lasso | `{ chartId, widget_type, points: [...], point_indices: [...], range, lassoPoints }` |
-| `plotly:relayout` | User zooms, pans, or resizes | `{ chartId, widget_type, relayout_data: {...} }` |
-| `plotly:state-response` | Response to state request | `{ chartId, layout: {...}, data: [...] }` |
-
-> **Note:** All Plotly events include `chartId` and `widget_type: "chart"` in the payload for identifying which chart triggered the event.
-
-**`plotly:click` payload structure:**
-```python
-{
-    "chartId": "chart_abc123",      # Unique chart identifier
-    "widget_type": "chart",         # Always "chart" for Plotly events
-    "points": [
-        {
-            "curveNumber": 0,       # Which trace (0-indexed)
-            "pointNumber": 5,       # Which point in the trace (0-indexed)
-            "pointIndex": 5,        # Same as pointNumber (Plotly alias)
-            "x": 2.5,               # X value
-            "y": 10.3,              # Y value
-            "z": None,              # Z value (for 3D charts)
-            "text": "label",        # Point text label (if any)
-            "customdata": {...},    # Custom data attached to point
-            "data": {...},          # Full trace data object
-            "trace_name": "Series A"  # Name of the trace
-        }
-    ],
-    "point_indices": [5],           # List of all pointNumber values
-    "curve_number": 0,              # curveNumber of first point (convenience)
-    "event": {...}                  # Original browser event
-}
-```
-
-**Example:**
-
-```python
-from pywry import PyWry
-import plotly.express as px
-
-app = PyWry()
-
-fig = px.scatter(px.data.iris(), x="sepal_width", y="sepal_length", color="species")
-
-def on_chart_click(data, event_type, label):
-    """Display clicked point coordinates in the chart title."""
-    point = data["points"][0]
-    app.emit("plotly:update-layout", {
-        "layout": {"title": f"Clicked: ({point['x']:.2f}, {point['y']:.2f})"}
-    }, label)
-
-handle = app.show_plotly(fig, title="Click any point", callbacks={"plotly:click": on_chart_click})
-```
-
-#### Events from Python → JavaScript (Update Chart)
-
-Use these to update the chart programmatically. These methods support optional `chart_id` targeting:
-
-| Event | Method | Payload |
-|-------|--------|---------|
-| `plotly:update-figure` | `widget.update_figure(fig, chart_id=...)` | `{ figure: {...}, chartId?, config?: {...}, animate?: bool }` |
-| `plotly:update-layout` | `widget.update_layout({...})` | `{ layout: {...} }` |
-| `plotly:update-traces` | `widget.update_traces({...}, indices)` | `{ update: {...}, indices: [int, ...] or null }` |
-| `plotly:reset-zoom` | `widget.reset_zoom()` | `{}` |
-| `plotly:request-state` | `widget.request_plotly_state(chart_id=...)` | `{ chartId? }` |
-| `plotly:export-data` | `app.emit("plotly:export-data", {chartId?}, label)` | `{ chartId? }` |
-
-> **Note:** `plotly:export-data` triggers `plotly:export-response` (JS → Python) with payload `{ data: [{ traceIndex, name, x, y, type }, ...] }` containing extracted trace data.
-
-### AgGrid Events (`grid:*`)
-
-#### Events from JavaScript → Python (User Interactions)
-
-These events fire automatically when users interact with AgGrid tables:
-
-| Event | Trigger | Payload |
-|-------|---------|---------|
-| `grid:row-selected` | Row selection changes | `{ gridId, widget_type, rows: [...] }` |
-| `grid:cell-click` | User clicks a cell | `{ gridId, widget_type, rowIndex, colId, value, data }` |
-| `grid:cell-edit` | User edits a cell | `{ gridId, widget_type, rowIndex, rowId, colId, oldValue, newValue, data }` |
-| `grid:filter-changed` | Filter applied | `{ gridId, widget_type, filterModel }` |
-| `grid:data-truncated` | Dataset truncated (client-side) | `{ gridId, widget_type, displayedRows, truncatedRows, message }` |
-| `grid:mode` | Grid mode info (server-side) | `{ gridId, widget_type, mode, serverSide, totalRows, blockSize, message }` |
-| `grid:request-page` | Server-side requests data block | `{ gridId, widget_type, startRow, endRow, sortModel, filterModel }` |
-| `grid:state-response` | Response to state request | `{ gridId, columnState, filterModel, sortModel, context? }` |
-
-> **Note:** All AgGrid events include `gridId` and `widget_type: "grid"` in the payload for identifying which grid triggered the event.
-
-**`grid:row-selected` payload structure:**
-```python
-{
-    "gridId": "grid_def456",      # Unique grid identifier
-    "widget_type": "grid",        # Always "grid" for AgGrid events
-    "rows": [
-        {"name": "Alice", "age": 30, "city": "NYC"},
-        {"name": "Bob", "age": 25, "city": "LA"}
-    ]
-}
-```
-
-**Example:**
-
-```python
-from pywry import PyWry
-import pandas as pd
-
-app = PyWry()
-
-df = pd.DataFrame({"name": ["Alice", "Bob", "Carol"], "age": [30, 25, 35], "city": ["NYC", "LA", "SF"]})
-
-def on_row_select(data, event_type, label):
-    """Print selected row names."""
-    rows = data["rows"]
-    names = ", ".join(row["name"] for row in rows)
-    print(f"Selected: {names}" if names else "No selection")
-
-handle = app.show_dataframe(
-    df,
-    callbacks={"grid:row-selected": on_row_select}
-)
-```
-
-#### Events from Python → JavaScript (Update Grid)
-
-Use these to update the grid programmatically. These methods support optional `grid_id` targeting:
-
-| Event | Method | Payload |
-|-------|--------|---------|
-| `grid:page-response` | (server-side callback) | `{ gridId, rows: [...], totalRows, isLastPage, requestId }` |
-| `grid:update-data` | `widget.update_data(rows, grid_id=...)` | `{ data: [...], gridId?, strategy? }` |
-| `grid:update-columns` | `widget.update_columns(col_defs, grid_id=...)` | `{ columnDefs: [...], gridId? }` |
-| `grid:update-cell` | `widget.update_cell(row_id, col, value, grid_id=...)` | `{ rowId, colId, value, gridId? }` |
-| `grid:update-grid` | `widget.update_grid(options, grid_id=...)` | `{ data?, columnDefs?, restoreState?, gridId? }` |
-| `grid:request-state` | `widget.request_grid_state(grid_id=...)` | `{ gridId?, context? }` |
-| `grid:restore-state` | `widget.restore_state(state, grid_id=...)` | `{ state: {...}, gridId? }` |
-| `grid:reset-state` | `widget.reset_state(grid_id=...)` | `{ gridId?, hard?: bool }` |
-| `grid:update-theme` | `widget.update_theme(theme, grid_id=...)` | `{ theme, gridId? }` |
-| `grid:show-notification` | (internal) | `{ message, duration?, gridId? }` |
-
-### Toolbar Events (`toolbar:*`)
-
-Toolbar events are used for state management (querying and setting component values).
-
-#### System Toolbar Events (Automatic)
-
-These events are emitted automatically when users interact with toolbar chrome:
-
-| Event | Direction | Payload | Description |
-|-------|-----------|---------|-------------|
-| `toolbar:collapse` | JS → Python | `{ componentId, collapsed: true }` | User collapsed a toolbar |
-| `toolbar:expand` | JS → Python | `{ componentId, collapsed: false }` | User expanded a toolbar |
-| `toolbar:resize` | JS → Python | `{ componentId, position, width, height }` | User resized a toolbar |
-
-#### State Management Events
-
-| Event | Direction | Payload | Description |
-|-------|-----------|---------|-------------|
-| `toolbar:state-response` | JS → Python | `{ toolbars, components, timestamp, context? }` | Response to state request |
-| `toolbar:request-state` | Python → JS | `{ toolbarId?, componentId?, context? }` | Request current state |
-| `toolbar:set-value` | Python → JS | `{ componentId, value?, label?, disabled?, ...attrs }` | Set component value and/or attributes |
-| `toolbar:set-values` | Python → JS | `{ values: { id: value, ... }, toolbarId? }` | Set multiple component values |
-
-#### Marquee Events
-
-| Event | Direction | Payload | Description |
-|-------|-----------|---------|-------------|
-| `toolbar:marquee-set-content` | Python → JS | `{ id, text?, html?, speed?, paused?, separator? }` | Update marquee content or settings |
-| `toolbar:marquee-set-item` | Python → JS | `{ ticker, text?, html?, styles?, class_add?, class_remove? }` | Update individual ticker item by `data-ticker` |
-
-> **Note:** Toolbar *components* (Button, Select, etc.) emit their own custom events that you define via the `event` parameter. All component events automatically include `componentId` in their payload. See the Toolbar System section.
-
----
-
-## Custom Events
-
-Custom events are events **you define** for your application. Unlike pre-registered events, custom events require you to either:
-
-1. Use toolbar components (which emit events automatically), or
-2. Write JavaScript that calls `window.pywry.emit()`
-
-**In this section:** [Event Direction Overview](#event-direction-overview) · [JS → Python](#js--python-receiving-events-from-javascript) · [Python → JS](#python--js-sending-events-to-javascript) · [Two-Way Communication](#complete-two-way-communication-example)
-
-### Event Direction Overview
-
-| Direction | How to Send | How to Receive | Use Case |
-|-----------|-------------|----------------|----------|
-| **JS → Python** | `window.pywry.emit(event, data)` | `callbacks={}`, `app.on()`, `widget.on()` | User interactions |
-| **Python → JS** | `app.emit(event, data, label=...)` or `widget.emit(event, data)` | `window.pywry.on(event, handler)` | Update UI |
-
-### JS → Python: Receiving Events from JavaScript
-
-#### Toolbar Component Events (Easiest)
-
-Toolbar components automatically emit events — you just specify the event name:
-
-```python
-from pywry import PyWry, Toolbar, Button, Select, Option
-import pandas as pd
-
-app = PyWry()
-
-# Sample data to export
-data = pd.DataFrame({"name": ["Alice", "Bob"], "score": [95, 87]})
-
-toolbar = Toolbar(
-    position="top",
-    items=[
-        Button(label="Export CSV", event="app:export-csv"),
-        Button(label="Refresh", event="app:refresh"),
-        Select(
-            label="Theme:",
-            event="app:theme-change",
-            options=[Option(label="Light", value="light"), Option(label="Dark", value="dark")],
-            selected="dark"
-        ),
-    ]
-)
-
-def on_export(data_evt, event_type, label):
-    """Trigger a CSV download when export button is clicked."""
-    app.emit("pywry:download", {
-        "content": data.to_csv(index=False),
-        "filename": "export.csv",
-        "mimeType": "text/csv"
-    }, label)
-
-def on_theme_change(data_evt, event_type, label):
-    """Apply the selected theme to the chart."""
-    theme = "plotly_dark" if data_evt["value"] == "dark" else "plotly_white"
-    app.emit("pywry:update-theme", {"theme": theme}, label)
-
-handle = app.show(
-    "<h1>Dashboard</h1><p>Select a theme or export data.</p>",
-    toolbars=[toolbar],
-    callbacks={
-        "app:export-csv": on_export,
-        "app:theme-change": on_theme_change,
-    }
-)
-```
-
-**Toolbar component payloads:**
-
-All toolbar components include `componentId` in their event payload for identification. Component IDs are auto-generated in the format `{type}-{uuid8}` (e.g., `button-a1b2c3d4`, `select-f099cfba`).
-
-| Component | Payload |
-|-----------|---------|
-| `Button` | `{ componentId, ...data }` (merges `Button(data={...})` with componentId) |
-| `Select` | `{ value: str, componentId }` |
-| `MultiSelect` | `{ values: [str, ...], componentId }` |
-| `TextInput` | `{ value: str, componentId }` |
-| `NumberInput` | `{ value: number, componentId }` |
-| `DateInput` | `{ value: "YYYY-MM-DD", componentId }` |
-| `SliderInput` | `{ value: number, componentId }` |
-| `RangeInput` | `{ start: number, end: number, componentId }` |
-| `Toggle` | `{ value: bool, componentId }` |
-| `Checkbox` | `{ value: bool, componentId }` |
-| `RadioGroup` | `{ value: str, componentId }` |
-| `TabGroup` | `{ value: str, componentId }` |
-
-**Using componentId to identify which button was clicked:**
-
-```python
-from pywry import PyWry, Toolbar, Button
-import pandas as pd
-
-app = PyWry()
-
-# Sample data
-data = pd.DataFrame({"name": ["Alice", "Bob"], "score": [95, 87]})
-
-def on_action(evt_data, event_type, label):
-    """Handle export button clicks - different buttons trigger different formats."""
-    fmt = evt_data.get("format", "csv")
-    if fmt == "csv":
-        content = data.to_csv(index=False)
-        mime = "text/csv"
-    else:
-        content = data.to_json(orient="records")
-        mime = "application/json"
-
-    # Trigger download in the browser
-    app.emit("pywry:download", {
-        "content": content,
-        "filename": f"data.{fmt}",
-        "mimeType": mime
-    }, label)
-
-toolbar = Toolbar(
-    position="top",
-    items=[
-        Button(label="Export CSV", event="app:export", data={"format": "csv"}),
-        Button(label="Export JSON", event="app:export", data={"format": "json"}),
-    ]
-)
-
-handle = app.show(
-    "<h1>Data Export</h1><p>Click a button to download.</p>",
-    toolbars=[toolbar],
-    callbacks={"app:export": on_action}
-)
-```
-
-#### Custom JavaScript Events
-
-Emit events from your own JavaScript code:
-
-```python
-from pywry import PyWry
-
-app = PyWry()
-
-def on_action(data, event_type, label):
-    """Respond to button click by updating the UI."""
-    received = data.get("value", 0)
-    doubled = received * 2
-    app.emit("pywry:set-content", {
-        "id": "result",
-        "text": f"Received {received}, doubled = {doubled}"
-    }, label)
-
-handle = app.show("""
-<button onclick="window.pywry.emit('app:my-action', {value: 42})">
-    Click Me
-</button>
-<div id="result" style="margin-top:10px;">Click the button...</div>
-""", callbacks={"app:my-action": on_action})
-```
-
-### Python → JS: Sending Events to JavaScript
-
-To update the browser UI from Python, use `app.emit()` for native mode or `widget.emit()` for notebooks.
-
-**Using Built-in Utility Events (recommended):**
-
-```python
-from pywry import PyWry
-
-app = PyWry()
-handle = app.show("<div id='msg'>Hello</div>")
-
-# Update content without any custom JavaScript
-handle.emit("pywry:set-content", {"id": "msg", "text": "Updated!"})
-
-# Notebook mode: widget.emit() on the returned widget
-# widget.emit("pywry:set-content", {"id": "msg", "text": "Updated!"})
-```
-
-**Using Custom Events (requires JavaScript handler):**
-
-```python
-from pywry import PyWry
-
-app = PyWry()
-handle = app.show("""
-<div id='msg'>Hello</div>
-<script>
-window.pywry.on('app:update-message', function(data) {
-    document.getElementById('msg').textContent = data.text;
-});
-</script>
-""")
-
-# Now your custom event has a handler
-handle.emit("app:update-message", {"text": "Updated!"})
-```
-
-### Complete Two-Way Communication Example
-
-```python
-from pywry import PyWry
-
-app = PyWry()
-
-def handle_request(data, event_type, label):
-    """Handle request from JavaScript and send response back."""
-    result = {"items": [1, 2, 3], "total": 3}
-    # Use app.emit() to send response back to JavaScript
-    app.emit("app:response", result, label)
-
-handle = app.show("""
-<button onclick="requestData()">Fetch Data</button>
-<div id="result">Click the button to fetch data...</div>
-<script>
-function requestData() {
-    window.pywry.emit('app:request-data', {});
-}
-window.pywry.on('app:response', function(data) {
-    document.getElementById('result').textContent =
-        'Received ' + data.total + ' items: ' + JSON.stringify(data.items);
-});
-</script>
-""", callbacks={"app:request-data": handle_request})
-```
-
-</details>
-
----
-
-## Toolbar System
-
-<details>
-<summary>Click to expand</summary>
-
-**In this section:** [Quick Start](#quick-start) · [Imports](#imports-1) · [Positions & Layout](#toolbar-positions--layout) · [Common Properties](#common-properties) · [Component Reference](#component-reference) · [Toolbar Container](#toolbar-container) · [Examples](#examples) · [State Management](#state-management)
-
----
-
-PyWry provides a flexible toolbar system for adding interactive controls to any window. The toolbar system uses Pydantic models for type-safe configuration with auto-generated component IDs for state tracking.
-
-### Quick Start
-
-```python
-from pywry import PyWry, Toolbar, Button, Select, Option
-
-app = PyWry()
-
-def on_save(data, event_type, label):
-    """Flash a success message when save is clicked."""
-    app.emit("pywry:set-style", {
-        "id": "status",
-        "styles": {"backgroundColor": "#22c55e", "color": "#fff"}
-    }, label)
-    app.emit("pywry:set-content", {"id": "status", "text": "Saved!"}, label)
-
-def on_view_change(data, event_type, label):
-    """Update heading to show current view mode."""
-    view = data["value"]
-    app.emit("pywry:set-content", {"id": "heading", "text": f"Current View: {view}"}, label)
-
-toolbar = Toolbar(
-    position="top",
-    items=[
-        Button(label="Save", event="app:save"),
-        Select(
-            label="View:",
-            event="view:change",
-            options=["Table", "Chart", "Map"],
-            selected="Table",
-        ),
-    ],
-)
-
-handle = app.show(
-    '<h1 id="heading">Current View: Table</h1><div id="status" style="padding:8px;">Ready</div>',
-    toolbars=[toolbar],
-    callbacks={"app:save": on_save, "view:change": on_view_change},
-)
-```
-
-### Imports
-
-```python
-from pywry import (
-    Toolbar,           # Container for toolbar items
-    Button,            # Clickable button
-    Select,            # Single-select dropdown
-    MultiSelect,       # Multi-select dropdown with checkboxes
-    TextInput,         # Text input with debounce
-    TextArea,          # Multi-line text area with resize
-    SearchInput,       # Search input with magnifying glass icon
-    SecretInput,       # Password/secret input with visibility toggle
-    NumberInput,       # Numeric input with min/max/step
-    DateInput,         # Date picker (YYYY-MM-DD)
-    SliderInput,       # Single-value slider
-    RangeInput,        # Dual-handle range slider
-    Toggle,            # Boolean switch (on/off)
-    Checkbox,          # Boolean checkbox
-    RadioGroup,        # Radio button group
-    TabGroup,          # Tab-style selection
-    Div,               # Container for custom HTML/nested items
-    Marquee,           # Scrolling text/content ticker
-    TickerItem,        # Helper for updatable items within Marquee
-    Option,            # Option for Select/MultiSelect/RadioGroup/TabGroup
-)
-```
-
-### Toolbar Positions & Layout
-
-PyWry supports **7 toolbar positions** that combine to create a flexible layout system:
-
-| Position | Description |
-|----------|-------------|
-| `"header"` | Full-width bar at the very top (outermost) |
-| `"footer"` | Full-width bar at the very bottom (outermost) |
-| `"left"` | Vertical bar on the left, extends between header/footer |
-| `"right"` | Vertical bar on the right, extends between header/footer |
-| `"top"` | Horizontal bar above content, inside left/right sidebars |
-| `"bottom"` | Horizontal bar below content, inside left/right sidebars |
-| `"inside"` | Floating overlay in the top-right corner of content |
-
-<details>
-<summary><strong>Layout Diagram</strong> — How positions nest together</summary>
-
-When you use multiple toolbars, they are layered from outside in:
-
-```
-┌─────────────────────────────────────────────────────────┐
-│                       HEADER                            │ ← Full width, outermost
-├───────┬─────────────────────────────────────────┬───────┤
-│       │                  TOP                    │       │
-│       ├─────────────────────────────────────────┤       │
-│ LEFT  │                                         │ RIGHT │ ← Extend full height
-│       │               CONTENT                   │       │   between header/footer
-│       │          ┌─────────────┐                │       │
-│       │          │   INSIDE    │  (overlay)     │       │
-│       │          └─────────────┘                │       │
-│       ├─────────────────────────────────────────┤       │
-│       │                 BOTTOM                  │       │
-├───────┴─────────────────────────────────────────┴───────┤
-│                       FOOTER                            │ ← Full width, outermost
-└─────────────────────────────────────────────────────────┘
-```
-
-**Nesting order (outside → inside):**
-1. `header` / `footer` — Span full width at very top/bottom
-2. `left` / `right` — Extend full height between header and footer
-3. `top` / `bottom` — Inside left/right columns, above/below content
-4. `inside` — Floating overlay on top of content
-5. Content — Your actual HTML/chart/grid
-
-</details>
-
-<details>
-<summary><strong>Multi-Toolbar Example</strong></summary>
-
-```python
-from pywry import PyWry, Toolbar, Button, Select, Toggle
-
-app = PyWry()
-
-# Header: App-wide navigation
-header = Toolbar(
-    position="header",
-    items=[
-        Button(label="Home", event="nav:home"),
-        Button(label="Settings", event="nav:settings", style="margin-left: auto;"),
-    ],
-)
-
-# Left sidebar: View controls
-sidebar = Toolbar(
-    position="left",
-    items=[
-        Button(label="📊", event="view:chart", variant="icon"),
-        Button(label="📋", event="view:table", variant="icon"),
-        Button(label="🗺️", event="view:map", variant="icon"),
-    ],
-)
-
-# Top: Context-specific controls
-top_bar = Toolbar(
-    position="top",
-    items=[
-        Select(label="Period:", event="filter:period", options=["1D", "1W", "1M", "1Y"]),
-        Toggle(label="Live:", event="data:live", value=True),
-    ],
-)
-
-# Inside: Quick actions overlay
-overlay = Toolbar(
-    position="inside",
-    items=[
-        Button(label="⟳", event="data:refresh", variant="icon"),
-    ],
-)
-
-# Footer: Status bar
-footer = Toolbar(
-    position="footer",
-    items=[
-        Button(label="Last updated: 12:34:56", event="status:info", variant="ghost", disabled=True),
-    ],
-)
-
-app.show(
-    "<h1>Dashboard</h1>",
-    toolbars=[header, sidebar, top_bar, overlay, footer],
-    callbacks={...},
-)
-```
-
-</details>
-
-### Common Properties
-
-All toolbar items share these properties:
-
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `event` | `str` | `"toolbar:input"` | Event name in `namespace:event-name` format |
-| `component_id` | `str` | auto-generated | Unique ID (format: `{type}-{uuid8}`, e.g., `button-a1b2c3d4`) |
-| `label` | `str` | `""` | Label text displayed next to the control |
-| `description` | `str` | `""` | Tooltip text shown on hover |
-| `disabled` | `bool` | `False` | Whether the control is disabled |
-| `style` | `str` | `""` | Inline CSS styles |
-
----
-
-### Component Reference
-
-PyWry provides **18 toolbar components** for building interactive UIs. Expand the details below for each component's full documentation.
-
-| Input Components | Selection Components | Container/Display |
-|------------------|---------------------|-------------------|
-| Button | Select | Div |
-| TextInput | MultiSelect | Marquee |
-| TextArea | RadioGroup | TickerItem |
-| SearchInput | TabGroup | Option |
-| SecretInput | Toggle | |
-| NumberInput | Checkbox | |
-| DateInput | | |
-| SliderInput | | |
-| RangeInput | | |
-
-<details>
-<summary><strong>Button</strong> — Clickable button with optional data payload</summary>
-
-```python
-Button(
-    label="Export",
-    event="app:export",
-    data={"format": "csv"},     # Optional payload merged into event data
-    variant="primary",          # Style: primary|secondary|neutral|ghost|outline|danger|warning|icon
-    size=None,                  # Size: None|xs|sm|lg|xl
-)
-```
-
-**Emits:** `{ componentId, ...data }` — The `data` dict merged with `componentId`.
-
-**Variants:**
-- `"primary"` — Theme-aware (light bg in dark mode, accent in light mode)
-- `"secondary"` — Subtle background, theme-aware
-- `"neutral"` — Always blue accent (for primary actions)
-- `"ghost"` — Transparent background
-- `"outline"` — Bordered, transparent fill
-- `"danger"` — Red accent for destructive actions
-- `"warning"` — Orange accent for caution
-- `"icon"` — Square aspect ratio for icon-only buttons
-
-</details>
-
-<details>
-<summary><strong>Select</strong> — Single-select dropdown</summary>
-
-```python
-Select(
-    label="Theme:",
-    event="theme:change",
-    options=[
-        Option(label="Dark", value="dark"),
-        Option(label="Light", value="light"),
-    ],
-    selected="dark",
-)
-
-# Shorthand: strings auto-convert to Option(label=s, value=s)
-Select(event="view:change", options=["Table", "Chart", "Map"], selected="Table")
-```
-
-**Emits:** `{ value: str, componentId: str }`
-
-</details>
-
-<details>
-<summary><strong>MultiSelect</strong> — Multi-select dropdown with checkboxes</summary>
-
-```python
-MultiSelect(
-    label="Columns:",
-    event="columns:filter",
-    options=["Name", "Age", "City", "Country"],
-    selected=["Name", "Age"],   # Initially selected values
-)
-```
-
-Features a search box and "All" / "None" quick-select buttons. Selected items appear at the top.
-
-**Emits:** `{ values: [str, ...], componentId: str }`
-
-</details>
-
-<details>
-<summary><strong>TextInput</strong> — Text input with debounce</summary>
-
-```python
-TextInput(
-    label="Search:",
-    event="search:query",
-    value="",                   # Initial value
-    placeholder="Type...",      # Placeholder text
-    debounce=300,               # Delay in ms before emitting (default: 300)
-)
-```
-
-**Emits:** `{ value: str, componentId: str }` after debounce delay.
-
-</details>
-
-<details>
-<summary><strong>TextArea</strong> — Multi-line text area with resize</summary>
-
-```python
-TextArea(
-    label="Notes:",
-    event="notes:update",
-    value="",                   # Initial text content
-    placeholder="Enter notes...",
-    debounce=300,               # Delay in ms before emitting (default: 300)
-    rows=3,                     # Initial visible text rows (default: 3)
-    cols=40,                    # Initial visible columns (default: 40)
-    resize="vertical",          # both|horizontal|vertical|none (default: both)
-    min_height="50px",          # Minimum height CSS value
-    max_height="500px",         # Maximum height CSS value
-)
-```
-
-The textarea is resizable by default. Use `resize` to control behavior.
-
-**Emits:** `{ value: str, componentId: str }` after debounce delay.
-
-</details>
-
-<details>
-<summary><strong>SearchInput</strong> — Search input with magnifying glass icon</summary>
-
-```python
-SearchInput(
-    label="Filter:",
-    event="filter:search",
-    value="",                   # Current search text
-    placeholder="Search...",    # Default placeholder
-    debounce=300,               # Delay in ms before emitting (default: 300)
-    spellcheck=False,           # Browser spell checking (default: False)
-    autocomplete="off",         # Browser autocomplete (default: "off")
-)
-```
-
-Includes a theme-aware magnifying glass icon on the left. Browser behaviors (spellcheck, autocomplete, autocorrect, autocapitalize) are disabled by default for cleaner search/filter UX.
-
-**Emits:** `{ value: str, componentId: str }` after debounce delay.
-
-</details>
-
-<details>
-<summary><strong>SecretInput</strong> — Password/secret input with visibility toggle</summary>
-
-**In this section:** [Security Model](#security-model) · [How It Works](#how-it-works-full-chain) · [Default Behavior](#default-behavior-no-handler) · [Pre-populated Value](#pre-populated-value-from-database) · [Custom Handler](#custom-handler-external-vault-database-etc) · [Events Emitted](#events-emitted) · [Utility Functions](#utility-functions)
-
-```python
-SecretInput(
-    label="API Key:",
-    event="settings:api_key",
-    value="my-secret",          # Stored as SecretStr (NEVER rendered in HTML)
-    placeholder="Enter key...",
-    show_toggle=True,           # Show visibility toggle button (default: True)
-    show_copy=True,             # Show copy to clipboard button (default: True)
-    value_exists=None,          # Override has_value detection (for external vaults)
-    handler=my_handler,         # Optional custom handler for external storage
-)
-```
-
-#### Security Model
-
-**The secret value is NEVER rendered in HTML.** When a value exists, the input displays a fixed mask (`••••••••••••`). The show/copy buttons emit events that request the secret from the Python backend — secrets are only transmitted on explicit user action and never embedded in the DOM.
-
-Values are base64-encoded in transit for obfuscation (not encryption — use HTTPS for security).
-
-#### How It Works (Full Chain)
-
-<details>
-<summary><strong>Event Flow Diagram</strong></summary>
-
-**1. Initialization — Setting a value:**
-
-When you create a `SecretInput` with a `value`, it's stored as a Pydantic `SecretStr` and registered in an internal `_SECRET_REGISTRY` keyed by `component_id`. The HTML only contains a mask.
-
-```python
-# Value stored internally, mask shown in UI
-SecretInput(label="API Key:", event="key:change", value="sk-abc123")
-```
-
-**2. User clicks Show (👁) button:**
-
-```
-Frontend                                        Backend
-────────                                        ───────
-    │                                               │
-    ├─── emit("{event}:reveal", {componentId}) ────►│
-    │                                               │ Looks up secret
-    │                                               │ from registry/handler
-    │                                               │
-    │◄── emit("{event}:reveal-response") ───────────┤
-    │         {value: "base64...", encoded: true}   │
-    │                                               │
-    └─── Decode & display in input                  │
-```
-
-**3. User clicks Copy (📋) button:**
-
-Same flow as reveal, but copies to clipboard instead of displaying.
-
-**4. User edits the value:**
-
-Clicking the Edit (✏) button opens a textarea. On confirm (blur or Ctrl+Enter), the new value is base64-encoded and emitted:
-
-```python
-# Backend receives: {value: "c2stbmV3a2V5MTIz", encoded: True, componentId: "secret-a1b2c3d4"}
-```
-
-</details>
-
-#### Default Behavior (No Handler)
-
-Without a custom `handler`, SecretInput uses an internal in-memory registry:
-
-```python
-from pywry.toolbar import register_secret, get_secret, clear_secret
-
-# Automatic on render:
-register_secret("secret-a1b2c3d4", SecretStr("my-value"))
-
-# On reveal/copy:
-value = get_secret("secret-a1b2c3d4")  # Returns "my-value"
-```
-
-The reveal/copy events are automatically handled by PyWry's callback system.
-
-#### Pre-populated Value from Database
-
-To display a SecretInput with a value that exists externally (database, vault, env var), use `value_exists=True` to show the mask without providing the actual secret:
-
-```python
-SecretInput(
-    label="Database Password:",
-    event="db:password",
-    value_exists=True,  # Shows mask, handler provides actual value on reveal
-    handler=db_password_handler,
-)
-```
-
-When `value_exists=True`:
-- The mask (••••••••••••) is displayed
-- No secret is stored in Python memory
-- Your `handler` must provide the value on reveal/copy
-
-#### Custom Handler (External Vault, Database, etc.)
-
-The `handler` is called for **both** get and set operations:
-
-```python
-def handler(
-    value: str | None,      # None = get, string = set
-    *,
-    component_id: str,      # Unique ID like "secret-a1b2c3d4"
-    event: str,             # Event name like "settings:api_key"
-    label: str | None,      # Label text if provided
-    **metadata,             # Additional context
-) -> str | None:
-    """Return secret on get, store and return on set."""
-```
-
-<details>
-<summary><strong>Database Handler Example</strong></summary>
-
-```python
-from pywry import PyWry, Toolbar, SecretInput
-import database  # Your database module
-
-app = PyWry()
-
-def api_key_handler(
-    value: str | None,
-    *,
-    component_id: str,
-    event: str,
-    label: str | None = None,
-    **metadata,
-) -> str | None:
-    """Fetch from or store to database."""
-    user_id = get_current_user_id()
-
-    if value is None:
-        # GET: User clicked show/copy — fetch from database
-        row = database.query(
-            "SELECT api_key FROM user_settings WHERE user_id = ?",
-            user_id
-        )
-        return row["api_key"] if row else None
-    else:
-        # SET: User edited the value — store to database
-        database.execute(
-            "INSERT OR REPLACE INTO user_settings (user_id, api_key) VALUES (?, ?)",
-            user_id, value
-        )
-        return value
-
-# Check if user already has a key set
-has_existing_key = database.query(
-    "SELECT 1 FROM user_settings WHERE user_id = ?", user_id
-) is not None
-
-toolbar = Toolbar(
-    position="top",
-    items=[
-        SecretInput(
-            label="API Key:",
-            event="settings:api_key",
-            value_exists=has_existing_key,  # Show mask if key exists
-            handler=api_key_handler,
-        ),
-    ],
-)
-
-app.show("<h1>Settings</h1>", toolbars=[toolbar])
-```
-
-</details>
-
-<details>
-<summary><strong>Environment Variable Example</strong></summary>
-
-```python
-import os
-
-def env_handler(value: str | None, *, component_id: str, **_) -> str | None:
-    """Read from environment, warn on write attempts."""
-    if value is None:
-        return os.environ.get("MY_API_KEY")
-    else:
-        print("Warning: Cannot write to environment variables at runtime")
-        return None
-
-SecretInput(
-    label="API Key (from env):",
-    event="env:api_key",
-    value_exists="MY_API_KEY" in os.environ,
-    handler=env_handler,
-    disabled=True,  # Read-only since we can't write to env
-)
-```
-
-</details>
-
-#### Events Emitted
-
-| Event | Direction | Payload | Description |
-|-------|-----------|---------|-------------|
-| `{event}` | JS → Python | `{ value, componentId, encoded: true }` | User edited value (base64) |
-| `{event}:reveal` | JS → Python | `{ componentId }` | User clicked show button |
-| `{event}:reveal-response` | Python → JS | `{ componentId, value, encoded: true }` | Backend response with secret |
-| `{event}:copy` | JS → Python | `{ componentId }` | User clicked copy button |
-| `{event}:copy-response` | Python → JS | `{ componentId, value, encoded: true }` | Backend response for clipboard |
-
-#### Utility Functions
-
-```python
-from pywry.toolbar import (
-    register_secret,    # Store secret: register_secret(component_id, SecretStr("..."))
-    get_secret,         # Retrieve secret: get_secret(component_id) -> str | None
-    clear_secret,       # Remove secret: clear_secret(component_id)
-    encode_secret,      # Base64 encode: encode_secret("value") -> "dmFsdWU="
-    decode_secret,      # Base64 decode: decode_secret("dmFsdWU=") -> "value"
-    set_secret_handler, # Set custom handler for specific event
-    get_secret_handler, # Get custom handler for event
-)
-```
-
-</details>
-
-<details>
-<summary><strong>NumberInput</strong> — Numeric input with constraints</summary>
-
-```python
-NumberInput(
-    label="Limit:",
-    event="filter:limit",
-    value=10,
-    min=1,
-    max=100,
-    step=1,
-)
-```
-
-Includes up/down spinner buttons.
-
-**Emits:** `{ value: number, componentId: str }`
-
-</details>
-
-<details>
-<summary><strong>DateInput</strong> — Date picker</summary>
-
-```python
-DateInput(
-    label="Start Date:",
-    event="filter:date",
-    value="2025-01-01",         # YYYY-MM-DD format
-    min="2020-01-01",           # Optional minimum
-    max="2030-12-31",           # Optional maximum
-)
-```
-
-**Emits:** `{ value: "YYYY-MM-DD", componentId: str }`
-
-</details>
-
-<details>
-<summary><strong>SliderInput</strong> — Single-value slider</summary>
-
-```python
-SliderInput(
-    label="Zoom:",
-    event="zoom:level",
-    value=50,
-    min=0,
-    max=100,
-    step=5,
-    show_value=True,            # Display current value (default: True)
-    debounce=50,                # Delay in ms (default: 50)
-)
-```
-
-**Emits:** `{ value: number, componentId: str }`
-
-</details>
-
-<details>
-<summary><strong>RangeInput</strong> — Dual-handle range slider</summary>
-
-```python
-RangeInput(
-    label="Price Range:",
-    event="filter:price",
-    start=100,                  # Initial start value
-    end=500,                    # Initial end value
-    min=0,
-    max=1000,
-    step=10,
-    show_value=True,            # Display start/end values
-    debounce=50,
-)
-```
-
-Two handles on a single track for selecting a value range.
-
-**Emits:** `{ start: number, end: number, componentId: str }`
-
-</details>
-
-<details>
-<summary><strong>Toggle</strong> — Boolean switch</summary>
-
-```python
-Toggle(
-    label="Dark Mode:",
-    event="theme:toggle",
-    value=True,                 # Initial state (default: False)
-)
-```
-
-A sliding on/off switch.
-
-**Emits:** `{ value: bool, componentId: str }`
-
-</details>
-
-<details>
-<summary><strong>Checkbox</strong> — Boolean checkbox</summary>
-
-```python
-Checkbox(
-    label="Enable notifications",
-    event="settings:notify",
-    value=True,                 # Initial checked state
-)
-```
-
-A standard checkbox with label.
-
-**Emits:** `{ value: bool, componentId: str }`
-
-</details>
-
-<details>
-<summary><strong>RadioGroup</strong> — Radio button group</summary>
-
-```python
-RadioGroup(
-    label="View:",
-    event="view:change",
-    options=["List", "Grid", "Cards"],
-    selected="List",
-    direction="horizontal",     # horizontal|vertical (default: horizontal)
-)
-```
-
-Mutually exclusive radio buttons.
-
-**Emits:** `{ value: str, componentId: str }`
-
-</details>
-
-<details>
-<summary><strong>TabGroup</strong> — Tab-style selection</summary>
-
-```python
-TabGroup(
-    label="View:",
-    event="view:change",
-    options=[
-        Option(label="Table", value="table"),
-        Option(label="Chart", value="chart"),
-        Option(label="Map", value="map"),
-    ],
-    selected="table",
-    size="md",                  # sm|md|lg (default: md)
-)
-```
-
-Similar to RadioGroup but styled as tabs. Ideal for view switching.
-
-**Emits:** `{ value: str, componentId: str }`
-
-</details>
-
-<details>
-<summary><strong>Div</strong> — Container for custom HTML and nested items</summary>
-
-```python
-Div(
-    content="<h3>Controls</h3>",          # Custom HTML
-    class_name="my-controls",             # CSS class (added to pywry-div)
-    children=[                            # Nested toolbar items
-        Button(label="Action", event="app:action"),
-        Div(content="<span>Nested</span>"),
-    ],
-    script="console.log('Div loaded');",  # JS file path or inline script
-)
-```
-
-Container for grouping items or injecting custom HTML. Supports unlimited nesting.
-
-**Emits:** No automatic events (children emit their own events).
-
-</details>
-
-<details>
-<summary><strong>Marquee</strong> — Scrolling text/content ticker</summary>
-
-**In this section:** [Content Types](#content-types) · [Behavior & Direction](#behavior--direction-options) · [Dynamic Updates](#dynamic-updates-python--js) · [Events](#events)
-
-```python
-Marquee(
-    text="Breaking News: Stock prices are up 5% today!",
-    event="ticker:click",           # Emitted when clicked (if clickable=True)
-    speed=15,                       # Seconds per scroll cycle (default: 15, lower = faster)
-    direction="left",               # left|right|up|down (default: left)
-    behavior="scroll",              # scroll|alternate|slide (default: scroll)
-    pause_on_hover=True,            # Pause animation on hover (default: True)
-    gap=50,                         # Gap in pixels between repeated content (default: 50)
-    clickable=False,                # Emit event when clicked (default: False)
-    separator=" • ",                # Optional separator between repeated content
-    children=[...],                 # Nested toolbar items (alternative to text)
-)
-```
-
-Uses pure CSS animations for smooth, performant scrolling. Content is automatically duplicated internally to create seamless looping without any JavaScript animation.
-
-#### Content Types
-
-| Type | Parameter | Use Case |
-|------|-----------|----------|
-| **Plain Text** | `text="..."` | Simple scrolling text, auto-escaped |
-| **HTML Content** | `text="<b>...</b>"` | Rich text (detected by `<` and `>` chars) |
-| **Nested Components** | `children=[...]` | Toolbar items (Button, Div, etc.) |
-
-#### Behavior & Direction Options
-
-| Behavior | Description |
-|----------|-------------|
-| `"scroll"` | Continuous seamless loop (default) |
-| `"alternate"` | Bounces back and forth |
-| `"slide"` | Scrolls once and stops |
-
-| Direction | Description |
-|-----------|-------------|
-| `"left"` | Content moves right → left (default) |
-| `"right"` | Content moves left → right |
-| `"up"` | Content moves bottom → top |
-| `"down"` | Content moves top → bottom |
-
-<details>
-<summary><strong>How Seamless Scrolling Works</strong></summary>
-
-Marquee automatically duplicates content for seamless looping:
-
-```
-┌────────────────────────────────────────────────────────────────┐
-│                        Marquee Container                       │
-│ ┌────────────────────────────────────────────────────────────┐ │
-│ │ [Content A] [sep] [Content A] [sep] [Content A] [sep] ...  │ │
-│ │     ▲                  ▲                                   │ │
-│ │   Copy 1             Copy 2 (duplicate for seamless loop)  │ │
-│ └────────────────────────────────────────────────────────────┘ │
-│                  ◄──────────────────────────                   │
-│                     Animation scrolls left                     │
-└────────────────────────────────────────────────────────────────┘
-```
-
-When you update content via `toolbar:marquee-set-content`, **both copies are updated** automatically to maintain the seamless effect.
-
-</details>
-
-#### Dynamic Updates (Python → JS)
-
-```python
-# Update text content
-widget.emit("toolbar:marquee-set-content", {
-    "id": marquee.component_id,
-    "text": "New scrolling text!"
-})
-
-# Change speed and pause
-widget.emit("toolbar:marquee-set-content", {
-    "id": marquee.component_id,
-    "speed": 10,      # seconds per cycle
-    "paused": False   # or True to pause
-})
-```
-
-<details>
-<summary><strong>All Update Options</strong></summary>
-
-```python
-# Update with plain text (auto-escaped)
-widget.emit("toolbar:marquee-set-content", {
-    "id": marquee.component_id,
-    "text": "New scrolling text!"
-})
-
-# Update with HTML content
-widget.emit("toolbar:marquee-set-content", {
-    "id": marquee.component_id,
-    "html": "<b>Breaking:</b> Market update"
-})
-
-# Change animation speed
-widget.emit("toolbar:marquee-set-content", {
-    "id": marquee.component_id,
-    "speed": 10  # Faster: 10 seconds per cycle
-})
-
-# Pause/resume animation
-widget.emit("toolbar:marquee-set-content", {
-    "id": marquee.component_id,
-    "paused": True  # or False to resume
-})
-
-# Update separator
-widget.emit("toolbar:marquee-set-content", {
-    "id": marquee.component_id,
-    "separator": " ★ "
-})
-
-# Combine multiple updates
-widget.emit("toolbar:marquee-set-content", {
-    "id": marquee.component_id,
-    "text": "Alert: System maintenance",
-    "speed": 8,
-    "separator": " ⚠️ "
-})
-
-# Alternative: Use Python helper method
-event, data = marquee.update_payload(text="Breaking news!", speed=10)
-widget.emit(event, data)  # event = "toolbar:marquee-set-content"
-```
-
-</details>
-
-#### Events
-
-| Event | Direction | Payload |
-|-------|-----------|---------|
-| `{event}` | JS → Python | `{ value, componentId }` — when clicked |
-| `toolbar:marquee-set-content` | Python → JS | `{ id, text?, html?, speed?, paused?, separator? }` |
-| `toolbar:marquee-set-item` | Python → JS | `{ ticker, text?, html?, styles?, class_add?, class_remove? }` |
-
-<details>
-<summary><strong>CSS Classes & Custom Properties</strong></summary>
-
-| Class | Description |
-|-------|-------------|
-| `.pywry-marquee` | Base marquee container |
-| `.pywry-marquee-left` / `-right` / `-up` / `-down` | Direction modifier |
-| `.pywry-marquee-scroll` / `-alternate` / `-slide` | Behavior modifier |
-| `.pywry-marquee-horizontal` / `-vertical` | Axis modifier |
-| `.pywry-marquee-pause` | Added when `pause_on_hover=True` |
-| `.pywry-marquee-clickable` | Added when `clickable=True` |
-| `.pywry-marquee-track` | Inner scrolling track |
-| `.pywry-marquee-content` | Content wrapper (duplicated) |
-| `.pywry-marquee-separator` | Separator between copies |
-
-```css
-/* Control via CSS or inline style */
---pywry-marquee-speed: 15s;   /* Animation duration */
---pywry-marquee-gap: 50px;    /* Gap between content copies */
-```
-
-</details>
-
-<details>
-<summary><strong>Complete Example: News Ticker</strong></summary>
-
-```python
-from pywry import PyWry, Toolbar, Marquee
-
-app = PyWry()
-
-# Create marquee with initial content
-news_ticker = Marquee(
-    text="Loading latest news...",
-    speed=20,
-    pause_on_hover=True,
-    component_id="news-ticker",  # Explicit ID for targeting
-)
-
-toolbar = Toolbar(position="header", items=[news_ticker])
-
-widget = app.show("<h1>Dashboard</h1>", toolbars=[toolbar])
-
-# Later, update from Python (e.g., after API call)
-def update_news(headlines: list[str]):
-    widget.emit("toolbar:marquee-set-content", {
-        "id": "news-ticker",
-        "text": " • ".join(headlines),
-        "speed": 25  # Slow down for more content
-    })
-
-update_news(["Market up 2%", "Tech earnings beat", "Fed holds rates"])
-```
-
-</details>
-
-</details>
-
-<details>
-<summary><strong>TickerItem</strong> — Helper for updatable items within Marquee</summary>
-
-TickerItem creates individually-updatable spans within a Marquee. Each item has a `data-ticker` attribute that allows targeting specific items for dynamic updates without replacing the entire content.
-
-**In this section:** [Basic Usage](#basic-usage-1) · [Parameters](#tickeritem-parameters) · [Dynamic Updates](#dynamic-updates) · [Update Payload Options](#update-payload-options)
-
-#### Basic Usage
-
-```python
-from pywry import Marquee, TickerItem
-
-items = [
-    TickerItem(ticker="AAPL", text="AAPL $185.50", class_name="stock-up"),
-    TickerItem(ticker="GOOGL", text="GOOGL $142.20"),
-    TickerItem(ticker="MSFT", text="MSFT $415.80"),
-]
-
-marquee = Marquee(
-    text=" • ".join(item.build_html() for item in items),
-    speed=20,
-)
-```
-
-**Generated HTML:** `<span data-ticker="AAPL" class="pywry-ticker-item stock-up">AAPL $185.50</span>`
-
-<details>
-<summary><strong>How It Works</strong></summary>
-
-```
-┌─────────────────────────────────────────────────────────────────────────┐
-│                           Marquee Container                             │
-│  ┌───────────────────────────────────────────────────────────────────┐  │
-│  │ [AAPL $185] • [GOOGL $142] • [MSFT $415] │ [AAPL $185] • [...]    │  │
-│  │      ▲             ▲             ▲       │      ▲                 │  │
-│  │  data-ticker   data-ticker   data-ticker │  (duplicate copy)      │  │
-│  └───────────────────────────────────────────────────────────────────┘  │
-└─────────────────────────────────────────────────────────────────────────┘
-                                    │
-   widget.emit("toolbar:marquee-set-item", {ticker: "AAPL", text: "$186"})
-                                    │
-                                    ▼
-              Updates ALL elements with data-ticker="AAPL"
-                  (both copies for seamless scrolling)
-```
-
-</details>
-
-#### TickerItem Parameters
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `ticker` | `str` | **Required.** Unique ID for targeting updates |
-| `text` | `str` | Plain text content (auto-escaped) |
-| `html` | `str` | HTML content (alternative to text) |
-| `class_name` | `str` | Additional CSS classes |
-| `style` | `str` | Inline CSS styles |
-
-#### Dynamic Updates
-
-```python
-# Update individual item
-widget.emit("toolbar:marquee-set-item", {
-    "ticker": "AAPL",
-    "text": "AAPL $186.25 ▲",
-    "styles": {"color": "#22c55e"}
-})
-
-# Or use helper method
-event, data = items[0].update_payload(
-    text="AAPL $186.25 ▲",
-    styles={"color": "#22c55e"},
-    class_add="stock-up",
-    class_remove="stock-down"
-)
-widget.emit(event, data)
-```
-
-#### Update Payload Options
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `ticker` | `str` | **Required.** Target elements with `data-ticker="{ticker}"` |
-| `selector` | `str` | Alternative: CSS selector to match elements |
-| `text` | `str` | New plain text content |
-| `html` | `str` | New HTML content (overrides text) |
-| `styles` | `dict` | Inline styles to apply (camelCase keys) |
-| `class_add` | `str \| list` | CSS class(es) to add |
-| `class_remove` | `str \| list` | CSS class(es) to remove |
-
-<details>
-<summary><strong>Complete Example: Real-Time Stock Ticker</strong></summary>
-
-```python
-from pywry import PyWry, Toolbar, Marquee, TickerItem
-import random
-
-app = PyWry()
-
-# Define stocks with initial prices
-stocks = {
-    "AAPL": {"price": 185.50, "item": None},
-    "GOOGL": {"price": 142.20, "item": None},
-    "MSFT": {"price": 415.80, "item": None},
-    "AMZN": {"price": 178.25, "item": None},
-}
-
-# Create TickerItems
-for symbol, data in stocks.items():
-    data["item"] = TickerItem(
-        ticker=symbol,
-        text=f"{symbol} ${data['price']:.2f}",
-    )
-
-# Build marquee
-stock_ticker = Marquee(
-    text=" • ".join(data["item"].build_html() for data in stocks.values()),
-    speed=25,
-    pause_on_hover=True,
-)
-
-toolbar = Toolbar(position="header", items=[stock_ticker])
-
-def simulate_price_update(data, event_type, label):
-    """Simulate random price changes."""
-    for symbol, stock in stocks.items():
-        change = random.uniform(-2, 2)
-        new_price = stock["price"] + change
-        stock["price"] = new_price
-
-        arrow = "▲" if change >= 0 else "▼"
-        color = "#22c55e" if change >= 0 else "#ef4444"
-
-        widget.emit("toolbar:marquee-set-item", {
-            "ticker": symbol,
-            "text": f"{symbol} ${new_price:.2f} {arrow}",
-            "styles": {"color": color},
-        })
-
-widget = app.show(
-    '<button onclick="window.pywry.emit(\'stock:update\', {})">Update</button>',
-    toolbars=[toolbar],
-    callbacks={"stock:update": simulate_price_update},
-)
-```
-
-</details>
-
-**Note:** TickerItem is NOT a ToolbarItem — it's a content helper. Updates target ALL matching `data-ticker` elements (both duplicated copies).
-
-</details>
-
-<details>
-<summary><strong>Option</strong> — Choice for Select/MultiSelect/RadioGroup/TabGroup</summary>
-
-```python
-Option(
-    label="Display Text",       # Text shown in UI
-    value="internal_value",     # Value sent in event (defaults to label)
-)
-
-# Shorthand: strings auto-convert
-options=["A", "B", "C"]  # → [Option(label="A", value="A"), ...]
-```
-
-</details>
-
----
-
-### Toolbar Container
-
-```python
-Toolbar(
-    position="top",                     # top|bottom|left|right|inside
-    items=[...],                        # List of toolbar items
-    component_id="my-toolbar",          # Optional custom ID (auto-generated if omitted)
-    class_name="my-toolbar-class",      # Custom CSS class
-    style="gap: 12px;",                 # Inline CSS for the content wrapper
-    collapsible=False,                  # Enable collapse/expand toggle button
-    resizable=False,                    # Enable drag-to-resize edge handle
-    script="console.log('loaded');",    # JS file path or inline script
-)
-```
-
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `position` | `str` | `"top"` | Toolbar placement |
-| `items` | `list` | `[]` | List of toolbar items |
-| `component_id` | `str` | `"toolbar-{uuid8}"` | Unique toolbar ID |
-| `class_name` | `str` | `""` | Additional CSS class |
-| `style` | `str` | `""` | Inline CSS for content area |
-| `collapsible` | `bool` | `False` | Show collapse/expand toggle |
-| `resizable` | `bool` | `False` | Enable drag-to-resize |
-| `script` | `str\|Path` | `None` | Custom JavaScript to inject |
-
----
-
-### Examples
-
-<details>
-<summary><strong>Complete Example with Multiple Components</strong></summary>
-
-```python
-from pywry import PyWry, Toolbar, Button, Select, TextInput, Toggle, Option
-
-app = PyWry()
-
-def on_save(data, event_type, label):
-    app.eval_js("document.getElementById('status').textContent = 'Saved!'", label)
-
-def on_export(data, event_type, label):
-    app.eval_js("document.getElementById('status').textContent = 'Exported!'", label)
-
-def on_theme(data, event_type, label):
-    is_dark = data["value"]
-    app.eval_js(f"document.documentElement.classList.toggle('light', {str(not is_dark).lower()})", label)
-
-def on_search(data, event_type, label):
-    app.eval_js(f"document.getElementById('status').textContent = 'Searching: {data['value']}'", label)
-
-toolbar = Toolbar(
-    position="top",
-    items=[
-        Button(label="Save", event="app:save"),
-        Button(label="Export", event="app:export", variant="secondary"),
-        Select(
-            label="View:",
-            event="view:change",
-            options=["Table", "Chart"],
-            selected="Table",
-        ),
-        TextInput(label="Search:", event="search:query", placeholder="Type..."),
-        Toggle(label="Dark:", event="theme:toggle", value=True, style="margin-left: auto;"),
-    ],
-)
-
-app.show(
-    "<h1>My App</h1><p id='status'>Ready</p>",
-    toolbars=[toolbar],
-    callbacks={
-        "app:save": on_save,
-        "app:export": on_export,
-        "theme:toggle": on_theme,
-        "search:query": on_search,
-    },
-)
-```
-
-</details>
-
-<details>
-<summary><strong>Styling Buttons</strong></summary>
-
-```python
-from pywry import PyWry, HtmlContent, Toolbar, Button
-
-content = HtmlContent(
-    html="<h1>Styled Buttons</h1>",
-    inline_css="""
-        .pywry-btn {
-            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
-            border-radius: 20px;
-            padding: 8px 20px;
-        }
-        .pywry-btn:hover { transform: scale(1.05); }
-        .pywry-toolbar { justify-content: center; gap: 12px; }
-    """
-)
-
-toolbar = Toolbar(
-    position="top",
-    items=[
-        Button(label="Primary", event="app:primary"),
-        Button(label="Secondary", event="app:secondary", variant="secondary"),
-        Button(label="Danger", event="app:danger", variant="danger"),
-    ],
-)
-
-app.show(content, toolbars=[toolbar])
-```
-
-</details>
-
-<details>
-<summary><strong>Toolbar with Plotly/AgGrid</strong></summary>
-
-```python
-from pywry import PyWry, Toolbar, Button
-
-app = PyWry()
-
-# Plotly with toolbar
-def on_reset(data, event_type, label):
-    app.eval_js(
-        "Plotly.relayout(window.__PYWRY_PLOTLY_DIV__, "
-        "{xaxis: {autorange: true}, yaxis: {autorange: true}})"
-    )
-
-toolbar = Toolbar(
-    position="bottom",
-    items=[Button(label="Reset Zoom", event="app:reset")],
-)
-
-app.show_plotly(fig, toolbars=[toolbar], callbacks={"app:reset": on_reset})
-
-# AgGrid with toolbar
-def on_export(data, event_type, label):
-    app.eval_js("window.__PYWRY_GRID_API__.exportDataAsCsv()")
-
-toolbar = Toolbar(
-    position="top",
-    items=[Button(label="Export CSV", event="app:export")],
-)
-
-app.show_dataframe(df, toolbars=[toolbar], callbacks={"app:export": on_export})
-```
-
-</details>
-
-<details>
-<summary><strong>All Toolbar Inputs - No Javascript Required</strong></summary>
-
-```python
-from pywry import (
-    PyWry,
-    Toolbar,
-    Button,
-    Select,
-    MultiSelect,
-    TextInput,
-    NumberInput,
-    SliderInput,
-    DateInput,
-    RangeInput,
-    Toggle,
-    Checkbox,
-    RadioGroup,
-    TabGroup,
-    Option,
-    Div,
-)
-
-
-app = PyWry()
-
-# State to display current values
-component_values = {}
-current_theme = "dark"  # Track current theme
-
-def make_handler(name):
-    """Create a handler that updates the display with the component's value."""
-    def handler(data, event_type, label):
-        # Extract the relevant value(s) from the event data
-        if "value" in data:
-            component_values[name] = data["value"]
-        elif "values" in data:
-            component_values[name] = data["values"]
-        elif "start" in data and "end" in data:
-            component_values[name] = f"{data['start']} - {data['end']}"
-        elif "btn" in data:
-            component_values[name] = data["btn"]
-        else:
-            component_values[name] = "clicked"
-
-        # Build display text for footer using built-in pywry:set-content
-        parts = [f"<strong>{k}:</strong> {v}" for k, v in component_values.items()]
-        app.emit("pywry:set-content", {
-            "id": "values-display",
-            "html": " | ".join(parts)
-        }, label)
-    return handler
-
-def on_theme_toggle(data, event_type, label):
-    """Toggle between dark and light mode using built-in pywry event."""
-    global current_theme
-    current_theme = "light" if current_theme == "dark" else "dark"
-    app.emit("pywry:update-theme", {"theme": current_theme}, label)
-
-def on_title_size(data, event_type, label):
-    """Change the title size using built-in pywry:set-style event."""
-    sizes = {"sm": "16px", "md": "20px", "lg": "26px"}
-    size = data.get("value", "md")
-    # Use built-in pywry:set-style event to update element styles
-    app.emit("pywry:set-style", {
-        "id": "demo-title",
-        "styles": {"fontSize": sizes.get(size, "20px")}
-    }, label)
-
-def on_label_style(data, event_type, label):
-    """Change all component label styles using built-in pywry:set-style event."""
-    style_map = {
-        "normal": {"fontWeight": "400", "fontStyle": "normal"},
-        "semi": {"fontWeight": "500", "fontStyle": "normal"},
-        "bold": {"fontWeight": "700", "fontStyle": "normal"},
-        "italic": {"fontWeight": "400", "fontStyle": "italic"},
-    }
-    style = data.get("value", "normal")
-    # Use built-in pywry:set-style event to update all labels
-    app.emit("pywry:set-style", {
-        "selector": ".pywry-input-label",
-        "styles": style_map.get(style, style_map["normal"])
-    }, label)
-
-def on_accent_color(data, event_type, label):
-    """Change the accent color using built-in pywry:inject-css event."""
-    colors = {
-        "blue": "#0078d4",
-        "green": "#28a745",
-        "purple": "#6f42c1",
-        "orange": "#fd7e14",
-        "pink": "#e91e63",
-    }
-    color = data.get("value", "blue")
-    accent = colors.get(color, colors["blue"])
-
-    # Use built-in pywry:inject-css to dynamically inject CSS
-    # The 'id' allows replacing the same style block on subsequent calls
-    app.emit("pywry:inject-css", {
-        "id": "custom-accent-color",
-        "css": f"""
-            :root {{
-                --pywry-accent: {accent} !important;
-                --pywry-accent-hover: {accent}dd !important;
-            }}
-            .pywry-btn-neutral {{
-                background: {accent} !important;
-            }}
-            .pywry-btn-neutral:hover {{
-                background: {accent}dd !important;
-            }}
-        """
-    })
-
-# Header toolbar with title and theme toggle
-components_header = Toolbar(
-    position="header",
-    items=[
-        Div(
-            content="<h3 id='demo-title' style='margin: 0;'>&#x1F9E9; All Toolbar Components</h3>",
-            style="flex: 1;",
-        ),
-        Select(
-            label="Accent:",
-            event="demo:accent",
-            options=[
-                Option(label="Blue", value="blue"),
-                Option(label="Green", value="green"),
-                Option(label="Purple", value="purple"),
-                Option(label="Orange", value="orange"),
-                Option(label="Pink", value="pink"),
-            ],
-            selected="blue",
-        ),
-        Select(
-            label="Title:",
-            event="demo:title_size",
-            options=[Option(label="SM", value="sm"), Option(label="MD", value="md"), Option(label="LG", value="lg")],
-            selected="md",
-        ),
-        Select(
-            label="Labels:",
-            event="demo:label_style",
-            options=[Option(label="Normal", value="normal"), Option(label="Semi", value="semi"), Option(label="Bold", value="bold"), Option(label="Italic", value="italic")],
-            selected="normal",
-        ),
-        Button(label="\u2600\uFE0F", event="demo:theme", variant="ghost", component_id="theme-toggle-btn"),
-    ],
-)
-
-# Top toolbar with text, number, and date inputs
-inputs_row = Toolbar(
-    position="top",
-    items=[
-        TextInput(
-            label="Text:",
-            event="demo:text",
-            value="Hello",
-            placeholder="Type here...",
-        ),
-        NumberInput(
-            label="Number:",
-            event="demo:number",
-            value=42,
-            min=0,
-            max=100,
-            step=1,
-        ),
-        DateInput(
-            label="Date:",
-            event="demo:date",
-            value="2026-01-13",
-        ),
-    ],
-)
-
-# Second row with select, multi-select
-selects_row = Toolbar(
-    position="top",
-    items=[
-        Select(
-            label="Select:",
-            event="demo:select",
-            options=[
-                Option(label="Option A", value="a"),
-                Option(label="Option B", value="b"),
-                Option(label="Option C", value="c"),
-            ],
-            selected="a",
-        ),
-        MultiSelect(
-            label="Multi:",
-            event="demo:multi",
-            options=[
-                Option(label="Red", value="red"),
-                Option(label="Green", value="green"),
-                Option(label="Blue", value="blue"),
-            ],
-            selected=["red"],
-        ),
-    ],
-)
-
-# Third row with sliders and range
-sliders_row = Toolbar(
-    position="top",
-    items=[
-        SliderInput(
-            label="Slider:",
-            event="demo:slider",
-            value=50,
-            min=0,
-            max=100,
-            step=5,
-            show_value=True,
-        ),
-        RangeInput(
-            label="Range:",
-            event="demo:range",
-            min=0,
-            max=100,
-            start=20,
-            end=80,
-            show_value=True,
-        ),
-    ],
-)
-
-# Fourth row with toggle, checkbox, and horizontal radio
-booleans_row = Toolbar(
-    position="top",
-    items=[
-        Toggle(label="Toggle:", event="demo:toggle", value=True),
-        Div(content="<span class='pywry-input-label'>Check:</span>", style="margin-right: 4px;"),
-        Checkbox(label="", event="demo:checkbox", value=False),
-        RadioGroup(
-            label="Radio:",
-            event="demo:radio",
-            options=[Option(label="A", value="a"), Option(label="B", value="b"), Option(label="C", value="c")],
-            selected="a",
-            direction="horizontal",
-        ),
-    ],
-)
-
-# Fifth row with TabGroups
-tabs_row = Toolbar(
-    position="top",
-    items=[
-        TabGroup(
-            label="View:",
-            event="demo:tabs",
-            options=[
-                Option(label="Table", value="table"),
-                Option(label="Chart", value="chart"),
-                Option(label="Map", value="map"),
-            ],
-            selected="table",
-        ),
-        TabGroup(
-            label="Size:",
-            event="demo:tabsize",
-            options=["SM", "MD", "LG"],
-            selected="MD",
-            size="sm",
-        ),
-    ],
-)
-
-# Right sidebar with vertical radio group
-right_sidebar = Toolbar(
-    position="right",
-    style="padding: 8px 12px;",
-    items=[
-        Div(content="<span class='pywry-input-label'>Priority</span>", style="margin-bottom: 4px;"),
-        RadioGroup(
-            event="demo:priority",
-            options=[
-                Option(label="Low", value="low"),
-                Option(label="Medium", value="med"),
-                Option(label="High", value="high"),
-            ],
-            selected="med",
-            direction="vertical",
-        ),
-    ],
-    collapsible=True,
-)
-
-# Bottom toolbar with buttons (all variants)
-buttons_row = Toolbar(
-    position="top",
-    items=[
-        Div(content="<span class='pywry-input-label'>Variants:</span>", style="margin-right: 4px;"),
-        Button(label="Primary", event="demo:btn", data={"btn": "primary"}, variant="primary"),
-        Button(label="Secondary", event="demo:btn", data={"btn": "secondary"}, variant="secondary"),
-        Button(label="Neutral", event="demo:btn", data={"btn": "neutral"}, variant="neutral"),
-        Button(label="Ghost", event="demo:btn", data={"btn": "ghost"}, variant="ghost"),
-        Button(label="Outline", event="demo:btn", data={"btn": "outline"}, variant="outline"),
-        Button(label="Danger", event="demo:btn", data={"btn": "danger"}, variant="danger"),
-        Button(label="Warning", event="demo:btn", data={"btn": "warning"}, variant="warning"),
-        Button(label="\u2699", event="demo:btn", data={"btn": "icon"}, variant="icon"),
-    ],
-)
-
-# Size variants row
-sizes_row = Toolbar(
-    position="top",
-    items=[
-        Div(content="<span class='pywry-input-label'>Sizes</span>", style="margin-right: 4px;"),
-        Button(label="XS", event="demo:btn", data={"btn": "xs"}, variant="neutral", size="xs"),
-        Button(label="SM", event="demo:btn", data={"btn": "sm"}, variant="neutral", size="sm"),
-        Button(label="Default", event="demo:btn", data={"btn": "default"}, variant="neutral"),
-        Button(label="LG", event="demo:btn", data={"btn": "lg"}, variant="neutral", size="lg"),
-        Button(label="XL", event="demo:btn", data={"btn": "xl"}, variant="neutral", size="xl"),
-    ],
-)
-
-# Footer with live status display
-components_footer = Toolbar(
-    position="footer",
-    items=[
-        Div(
-            content="<span id='values-display'><em>Interact with components above...</em></span>",
-            style="color: var(--pywry-text-secondary); width: 100%; text-align: center;",
-        ),
-    ],
-)
-
-# No custom HTML or custom JS needed - all interactions use built-in pywry events!
-components_html = ""
-
-components_handle = app.show(
-    components_html,
-    title="All Components Demo",
-    toolbars=[
-        components_header,
-        inputs_row,
-        selects_row,
-        sliders_row,
-        booleans_row,
-        tabs_row,
-        buttons_row,
-        sizes_row,
-        right_sidebar,
-        components_footer,
-    ],
-    callbacks={
-        "demo:text": make_handler("Text"),
-        "demo:number": make_handler("Number"),
-        "demo:date": make_handler("Date"),
-        "demo:select": make_handler("Select"),
-        "demo:multi": make_handler("Multi"),
-        "demo:slider": make_handler("Slider"),
-        "demo:range": make_handler("Range"),
-        "demo:toggle": make_handler("Toggle"),
-        "demo:checkbox": make_handler("Checkbox"),
-        "demo:radio": make_handler("Radio"),
-        "demo:tabs": make_handler("Tabs"),
-        "demo:tabsize": make_handler("TabSize"),
-        "demo:priority": make_handler("Priority"),
-        "demo:btn": make_handler("Button"),
-        "demo:theme": on_theme_toggle,
-        "demo:title_size": on_title_size,
-        "demo:label_style": on_label_style,
-        "demo:accent": on_accent_color,
-    },
-    height=375
-)
-```
-
-</details>
-
----
-
-### State Management
-
-<details>
-<summary><strong>Querying Toolbar State</strong></summary>
-
-```python
-from pywry import PyWry, Toolbar, Select, Option
-
-app = PyWry()
-
-def on_state(data, event_type, label):
-    """Display current toolbar state in the UI."""
-    components = data.get("components", {})
-    state_text = ", ".join(f"{k}: {v.get('value')}" for k, v in components.items())
-    app.emit("pywry:set-content", {"id": "state", "text": f"State: {state_text}"}, label)
-
-toolbar = Toolbar(
-    position="top",
-    toolbar_id="my-toolbar",
-    items=[Select(event="app:mode", options=["A", "B", "C"], selected="A")]
-)
-
-handle = app.show(
-    '<div id="state">Click refresh to see state...</div>',
-    toolbars=[toolbar],
-    callbacks={"toolbar:state-response": on_state}
-)
-
-# Request toolbar state
-handle.emit("toolbar:request-state", {"toolbarId": "my-toolbar"})
-```
-
-**Response payload:**
-```python
-{
-    "toolbars": {"toolbar-a1b2c3d4": {"position": "top", "components": ["button-x1y2z3", ...]}},
-    "components": {"button-x1y2z3": {"type": "button", "value": None}, ...},
-    "timestamp": 1234567890
-}
-```
-
-</details>
-
-<details>
-<summary><strong>Setting Toolbar Values</strong></summary>
-
-```python
-from pywry import PyWry, Toolbar, Button, Select, NumberInput
-
-app = PyWry()
-
-def on_reset(data, event_type, label):
-    """Reset all toolbar values to defaults."""
-    app.emit("toolbar:set-values", {
-        "values": {"theme-select": "light", "zoom-input": 100}
-    }, label)
-    app.emit("pywry:set-content", {"id": "status", "text": "Reset to defaults!"}, label)
-
-toolbar = Toolbar(
-    position="top",
-    items=[
-        Select(event="app:theme", component_id="theme-select", options=["light", "dark"], selected="dark"),
-        NumberInput(event="app:zoom", component_id="zoom-input", value=150, min=50, max=200),
-        Button(label="Reset", event="app:reset"),
-    ]
-)
-
-handle = app.show(
-    '<div id="status">Adjust settings above...</div>',
-    toolbars=[toolbar],
-    callbacks={"app:reset": on_reset}
-)
-```
-
-**Setting Component Attributes** (labels, disabled state, etc.):
-
-```python
-def on_submit(data, event_type, label):
-    """Show loading state then re-enable."""
-    # Update button label and disable
-    handle.set_toolbar_value("submit-btn", label="Saving...", disabled=True)
-    
-    # ... do work ...
-    
-    # Re-enable with original label
-    handle.set_toolbar_value("submit-btn", label="Submit", disabled=False)
-
-def on_category_change(data, event_type, label):
-    """Update dropdown options dynamically."""
-    category = data.get("value")
-    if category == "fruits":
-        options = [{"label": "Apple", "value": "apple"}, {"label": "Banana", "value": "banana"}]
-    else:
-        options = [{"label": "Carrot", "value": "carrot"}, {"label": "Broccoli", "value": "broccoli"}]
-    
-    handle.set_toolbar_value("item-select", value=options[0]["value"], options=options)
-```
-
-Supported attributes for `set_toolbar_value()`:
-
-| Attribute | Description | Example |
-|-----------|-------------|---------|
-| `value` | Component value | `value="dark"` |
-| `label`/`text` | Text content | `label="Loading..."` |
-| `disabled` | Enable/disable | `disabled=True` |
-| `variant` | Button style | `variant="danger"` |
-| `tooltip`/`description` | Hover text | `tooltip="Click to save"` |
-| `options` | Dropdown options | `options=[{"label": "A", "value": "a"}]` |
-| `style` | Inline CSS | `style={"color": "red"}` |
-| `className` | CSS classes | `className={"add": ["active"]}` |
-| `placeholder` | Input hint | `placeholder="Search..."` |
-| `min`/`max`/`step` | Input constraints | `min=0, max=100` |
-
-</details>
-
-<details>
-<summary><strong>JavaScript Access</strong></summary>
-
-```javascript
-// Get all toolbar state
-const state = window.__PYWRY_TOOLBAR__.getState();
-
-// Get specific toolbar state
-const state = window.__PYWRY_TOOLBAR__.getState("toolbar-a1b2c3d4");
-
-// Get/set individual component value
-const value = window.__PYWRY_TOOLBAR__.getValue("select-a1b2c3d4");
-window.__PYWRY_TOOLBAR__.setValue("select-a1b2c3d4", "light");
-```
-
-</details>
-
-</details>
-
----
-
-## CSS Selectors and Theming
-
-<details>
-<summary>Click to expand</summary>
-
-**In this section:** [Theme Classes](#theme-classes) · [Container Classes](#container-classes) · [Layout Wrappers](#layout-wrappers) · [Toolbar Classes](#toolbar-classes) · [Component Classes](#component-classes) · [Toast Classes](#toast-notification-classes) · [Component ID Targeting](#component-id-targeting) · [CSS Variables](#css-variables) · [Example](#example-custom-styling)
-
----
-
-PyWry provides a consistent DOM structure across all rendering modes (HTML, Plotly, AgGrid). Understanding the class hierarchy enables precise styling and JavaScript targeting.
-
-### Theme Classes
-
-PyWry uses a dual-class theming system for maximum compatibility:
-
-| Selector | Description |
-|----------|-------------|
-| `html.dark` | Dark theme on document root (native windows) |
-| `html.light` | Light theme on document root (native windows) |
-| `html.pywry-native` | Added to `<html>` in native window mode |
-| `.pywry-theme-dark` | Dark theme on widget container (notebook/browser mode) |
-| `.pywry-theme-light` | Light theme on widget container (notebook/browser mode) |
-| `.pywry-theme-system` | System preference theme (follows `prefers-color-scheme`) |
-
-> **Note:** In native windows, theme classes are applied to `<html>`. In notebooks/inline mode, they're applied to `.pywry-widget` for scoped styling that doesn't affect the notebook theme.
-
-### Container Classes
-
-| Selector | Description |
-|----------|-------------|
-| `.pywry-container` | Root container for native windows (full page, absolute positioned) |
-| `.pywry-widget` | Root container for widgets in notebook/browser mode |
-| `.pywry-content` | Flex container for user content (HTML/Chart/Grid), includes 16px padding |
-| `.pywry-plotly` | Plotly chart container with border styling |
-| `.pywry-grid` | AgGrid container element |
-| `.plotly-graph-div` | Plotly's internal container (Plotly's own class) |
-
-### Layout Wrappers
-
-<details>
-<summary>Wrapper hierarchy diagram and classes</summary>
-
-Layout wrappers create the nested flexbox structure for toolbar positioning. They are applied in a specific order to create the visual hierarchy:
-
-```
-┌────────────────────────────────────────────────────────────────┐
-│ .pywry-wrapper-header (column: header toolbar + rest)          │
-│  ┌──────────────────────────────────────────────────────────┐  │
-│  │ .pywry-toolbar-header                                    │  │
-│  ├──────────────────────────────────────────────────────────┤  │
-│  │ .pywry-wrapper-left (row: left toolbar + rest)           │  │
-│  │  ┌───────┬────────────────────────────────────────────┐  │  │
-│  │  │ .left │ .pywry-wrapper-right (row: rest + right)   │  │  │
-│  │  │       │  ┌──────────────────────────────────┬────┐ │  │  │
-│  │  │       │  │ .pywry-wrapper-top               │.rt │ │  │  │
-│  │  │       │  │  ┌────────────────────────────┐  │    │ │  │  │
-│  │  │       │  │  │ .pywry-toolbar-top         │  │    │ │  │  │
-│  │  │       │  │  ├────────────────────────────┤  │    │ │  │  │
-│  │  │       │  │  │ .pywry-wrapper-bottom      │  │    │ │  │  │
-│  │  │       │  │  │  ┌──────────────────────┐  │  │    │ │  │  │
-│  │  │       │  │  │  │ .pywry-wrapper-ins   │  │  │    │ │  │  │
-│  │  │       │  │  │  │  ┌────────────────┐  │  │  │    │ │  │  │
-│  │  │       │  │  │  │  │ .pywry-cont    │  │  │  │    │ │  │  │
-│  │  │       │  │  │  │  │   (content)    │  │  │  │    │ │  │  │
-│  │  │       │  │  │  │  └────────────────┘  │  │  │    │ │  │  │
-│  │  │       │  │  │  │ .pywry-toolbar-ins   │  │  │    │ │  │  │
-│  │  │       │  │  │  └──────────────────────┘  │  │    │ │  │  │
-│  │  │       │  │  │ .pywry-toolbar-bottom      │  │    │ │  │  │
-│  │  │       │  │  └────────────────────────────┘  │    │ │  │  │
-│  │  │       │  └──────────────────────────────────┴────┘ │  │  │
-│  │  └───────┴────────────────────────────────────────────┘  │  │
-│  ├──────────────────────────────────────────────────────────┤  │
-│  │ .pywry-toolbar-footer                                    │  │
-│  └──────────────────────────────────────────────────────────┘  │
-└────────────────────────────────────────────────────────────────┘
-```
-
-| Selector | Description |
-|----------|-------------|
-| `.pywry-wrapper-header` | Outermost wrapper; column layout for header/footer toolbars |
-| `.pywry-wrapper-left` | Row layout; left toolbar extends full height |
-| `.pywry-wrapper-right` | Row layout; right toolbar extends full height |
-| `.pywry-wrapper-top` | Column layout; top toolbar is inside left/right |
-| `.pywry-wrapper-bottom` | Column layout; bottom toolbar is inside left/right |
-| `.pywry-wrapper-inside` | Innermost wrapper; positions inside toolbar as overlay |
-
-> **Nesting Behavior:** Wrappers are nested based on which toolbars are present. If you only have `top` and `bottom` toolbars, only `.pywry-wrapper-top` and `.pywry-wrapper-bottom` are created (no left/right wrappers). The `header` and `footer` positions are always outermost when present.
-
-</details>
-
-### Toolbar Classes
-
-| Selector | Description |
-|----------|-------------|
-| `.pywry-toolbar` | Base toolbar container with flex layout |
-| `.pywry-toolbar-header` | Full-width toolbar at page top, with bottom border |
-| `.pywry-toolbar-footer` | Full-width toolbar at page bottom, with top border |
-| `.pywry-toolbar-top` | Toolbar above content, inside left/right toolbars |
-| `.pywry-toolbar-bottom` | Toolbar below content, inside left/right toolbars |
-| `.pywry-toolbar-left` | Vertical toolbar on left, full height, with right border |
-| `.pywry-toolbar-right` | Vertical toolbar on right, full height, with left border |
-| `.pywry-toolbar-inside` | Floating toolbar overlay at top-right of content |
-| `.pywry-toolbar-content` | Inner container for toolbar items |
-| `.pywry-toolbar-toggle` | Collapse/expand button for collapsible toolbars |
-| `.pywry-toggle-icon` | Arrow icon inside toggle button |
-| `.pywry-collapsed` | State class for collapsed toolbars |
-| `.pywry-resize-handle` | Drag handle for resizable toolbars |
-
-### Component Classes
-
-<details>
-<summary>All component selectors (Buttons, Inputs, Dropdowns, Toggle, Radio, Tabs, Div)</summary>
-
-#### Buttons
-
-| Selector | Description |
-|----------|-------------|
-| `.pywry-btn` | Base button with primary styling (default variant) |
-| `.pywry-btn-secondary` | Secondary button - subtle gray background |
-| `.pywry-btn-neutral` | Neutral button - blue accent, always visible |
-| `.pywry-btn-ghost` | Ghost button - transparent, text only |
-| `.pywry-btn-outline` | Outline button - border only, no fill |
-| `.pywry-btn-danger` | Danger button - red background |
-| `.pywry-btn-warning` | Warning button - orange background |
-| `.pywry-btn-icon` | Icon-only button - square aspect ratio |
-| `.pywry-btn-xs` | Extra small size |
-| `.pywry-btn-sm` | Small size |
-| `.pywry-btn-lg` | Large size |
-| `.pywry-btn-xl` | Extra large size |
-
-#### Inputs
-
-| Selector | Description |
-|----------|-------------|
-| `.pywry-input` | Base input styling (text, number, date) |
-| `.pywry-input-text` | Text input specific styling |
-| `.pywry-input-number` | Number input with hidden spinners |
-| `.pywry-input-date` | Date picker input |
-| `.pywry-input-range` | Slider/range input |
-| `.pywry-input-group` | Container with label + input |
-| `.pywry-input-inline` | Horizontal label + input layout |
-| `.pywry-input-label` | Label text styling |
-| `.pywry-number-wrapper` | Number input with custom spinner buttons |
-| `.pywry-number-spinner` | Custom up/down spinner container |
-| `.pywry-range-value` | Current value display for sliders |
-| `.pywry-range-group` | Dual-range slider container |
-| `.pywry-range-track` | Track element for range sliders |
-| `.pywry-range-separator` | "–" separator between min/max values |
-
-#### Dropdowns & Select
-
-| Selector | Description |
-|----------|-------------|
-| `.pywry-select` | Native `<select>` element styling |
-| `.pywry-dropdown` | Custom dropdown container |
-| `.pywry-dropdown-selected` | Selected value display area |
-| `.pywry-dropdown-text` | Text inside selected area |
-| `.pywry-dropdown-arrow` | Chevron arrow indicator |
-| `.pywry-dropdown-menu` | Dropdown options popup |
-| `.pywry-dropdown-option` | Individual option in dropdown |
-| `.pywry-dropdown-up` | Opens dropdown upward (for bottom toolbars) |
-| `.pywry-open` | State class when dropdown is expanded |
-| `.pywry-selected` | Selected state for options |
-| `.pywry-disabled` | Disabled state for dropdowns |
-
-#### Multi-Select
-
-| Selector | Description |
-|----------|-------------|
-| `.pywry-multiselect` | Multi-select dropdown container |
-| `.pywry-multiselect-header` | Header with search and actions |
-| `.pywry-multiselect-search` | Search input in header |
-| `.pywry-multiselect-actions` | Select All / Clear buttons container |
-| `.pywry-multiselect-action` | Individual action button |
-| `.pywry-multiselect-options` | Scrollable options container |
-| `.pywry-multiselect-option` | Individual option row |
-| `.pywry-multiselect-checkbox` | Checkbox input |
-| `.pywry-multiselect-label` | Option label text |
-
-#### Toggle & Checkbox
-
-| Selector | Description |
-|----------|-------------|
-| `.pywry-toggle` | Toggle switch container |
-| `.pywry-toggle-input` | Hidden checkbox input |
-| `.pywry-toggle-slider` | Visual slider track |
-| `.pywry-checkbox` | Checkbox container |
-| `.pywry-checkbox-input` | Hidden checkbox input |
-| `.pywry-checkbox-box` | Visual checkbox square |
-| `.pywry-checkbox-label` | Checkbox label text |
-
-#### Radio Group
-
-| Selector | Description |
-|----------|-------------|
-| `.pywry-radio-group` | Radio button group container |
-| `.pywry-radio-horizontal` | Horizontal layout |
-| `.pywry-radio-vertical` | Vertical layout |
-| `.pywry-radio-option` | Individual radio option |
-| `.pywry-radio-button` | Visual radio circle |
-| `.pywry-radio-label` | Radio option label |
-
-#### Tab Group
-
-| Selector | Description |
-|----------|-------------|
-| `.pywry-tab-group` | Tab container with background |
-| `.pywry-tab` | Individual tab button |
-| `.pywry-tab-active` | Currently selected tab |
-| `.pywry-tab-sm` | Small tab size variant (on `.pywry-tab-group`) |
-| `.pywry-tab-lg` | Large tab size variant (on `.pywry-tab-group`) |
-| `.pywry-tab-group.pywry-disabled` | Disabled state for entire tab group |
-
-#### Div Container
-
-| Selector | Description |
-|----------|-------------|
-| `.pywry-div` | Custom HTML container in toolbars |
-
-#### State Classes
-
-These reusable state classes can be combined with component classes:
-
-| Selector | Description |
-|----------|-------------|
-| `.pywry-open` | Open/expanded state (dropdowns) |
-| `.pywry-selected` | Selected state (dropdown options) |
-| `.pywry-disabled` | Disabled state (buttons, dropdowns, inputs, tab groups) |
-| `.pywry-collapsed` | Collapsed state (toolbars) |
-
-</details>
-
-### Toast Notification Classes
-
-<details>
-<summary>Toast container, type variants, overlay, and light theme classes</summary>
-
-PyWry's toast notification system uses the following CSS classes. These are positioned absolutely within the widget container to stay scoped and not break out of the content area.
-
-#### Container Classes
-
-| Selector | Description |
-|----------|-------------|
-| `.pywry-toast-container` | Base container for toast stack, positioned absolutely |
-| `.pywry-toast-container--top-right` | Positioned in top-right corner (default) |
-| `.pywry-toast-container--top-left` | Positioned in top-left corner |
-| `.pywry-toast-container--bottom-right` | Positioned in bottom-right corner |
-| `.pywry-toast-container--bottom-left` | Positioned in bottom-left corner |
-| `.pywry-toast-container--blocking` | Elevated z-index for confirm dialogs (above overlay) |
-
-#### Toast Element Classes
-
-| Selector | Description |
-|----------|-------------|
-| `.pywry-toast` | Base toast notification styling |
-| `.pywry-toast__icon` | Toast icon container |
-| `.pywry-toast__content` | Toast message content wrapper |
-| `.pywry-toast__title` | Toast title/header text |
-| `.pywry-toast__message` | Toast message body text |
-| `.pywry-toast__close` | Close button (hidden on confirm type) |
-| `.pywry-toast__buttons` | Button container for confirm dialogs |
-| `.pywry-toast__btn` | Base button styling |
-| `.pywry-toast__btn--cancel` | Cancel button styling |
-| `.pywry-toast__btn--confirm` | Confirm button styling |
-
-#### Type Variants
-
-Each type sets the `--pywry-toast-accent` CSS variable for the left border color:
-
-| Selector | Accent Color | Description |
-|----------|--------------|-------------|
-| `.pywry-toast--info` | `#0ea5e9` (sky blue) | Informational messages |
-| `.pywry-toast--success` | `#22c55e` (green) | Success confirmations |
-| `.pywry-toast--warning` | `#f59e0b` (amber) | Warning notices |
-| `.pywry-toast--error` | `#ef4444` (red) | Error messages |
-| `.pywry-toast--confirm` | `#6366f1` (indigo) | Confirmation dialogs |
-
-#### Overlay Classes
-
-| Selector | Description |
-|----------|-------------|
-| `.pywry-toast-overlay` | Semi-transparent overlay for blocking confirm dialogs |
-| `.pywry-toast-overlay--visible` | Visible state with pointer-events enabled |
-
-#### Theme Variants
-
-| Selector | Description |
-|----------|-------------|
-| `.pywry-theme-light .pywry-toast` | Light theme styling for toasts |
-| `.pywry-toast--light` | Explicit light theme class |
-
-#### CSS Variables for Customization
-
-```css
-/* Customize toast appearance */
-.pywry-toast {
-    --pywry-toast-bg: rgba(30, 30, 30, 0.95);
-    --pywry-toast-color: #ffffff;
-    --pywry-toast-accent: #0ea5e9;
-}
-
-/* Light theme */
-.pywry-theme-light .pywry-toast {
-    --pywry-toast-bg: rgba(255, 255, 255, 0.95);
-    --pywry-toast-color: #1f2937;
-}
-```
-
-#### Example: Custom Toast Styling
-
-```css
-/* Make toasts wider */
-.pywry-toast {
-    max-width: 500px;
-}
-
-/* Custom accent color for all toasts */
-.pywry-toast {
-    --pywry-toast-accent: #8b5cf6;  /* Purple */
-}
-
-/* Custom success color */
-.pywry-toast--success {
-    --pywry-toast-accent: #10b981;  /* Emerald */
-}
-
-/* Rounded toast corners */
-.pywry-toast {
-    border-radius: 12px;
-}
-
-/* Style the confirm buttons */
-.pywry-toast__btn--confirm {
-    background-color: #22c55e;
-}
-```
-
-</details>
-
-### Component ID Targeting
-
-<details>
-<summary>ID patterns, targeting examples, and parent-child relationships</summary>
-
-Every toolbar component has a unique `component_id` that becomes its HTML `id` attribute. This enables precise CSS and JavaScript targeting.
-
-**Default ID Pattern:** `{type}-{8-char-random}`
-
-| Component | ID Prefix | Example |
-|-----------|-----------|---------|
-| `Button` | `button-` | `button-a1b2c3d4` |
-| `Select` | `select-` | `select-e5f6g7h8` |
-| `MultiSelect` | `multiselect-` | `multiselect-i9j0k1l2` |
-| `TextInput` | `text-` | `text-m3n4o5p6` |
-| `NumberInput` | `number-` | `number-q7r8s9t0` |
-| `DateInput` | `date-` | `date-u1v2w3x4` |
-| `SliderInput` | `slider-` | `slider-y5z6a7b8` |
-| `RangeInput` | `range-` | `range-c9d0e1f2` |
-| `Toggle` | `toggle-` | `toggle-g3h4i5j6` |
-| `Checkbox` | `checkbox-` | `checkbox-k7l8m9n0` |
-| `RadioGroup` | `radio-` | `radio-o1p2q3r4` |
-| `TabGroup` | `tabs-` | `tabs-s5t6u7v8` |
-| `Div` | `div-` | `div-w9x0y1z2` |
-| `Toolbar` | `toolbar-` | `toolbar-a3b4c5d6` |
-
-**Custom IDs:** Set `component_id` explicitly for stable targeting:
-
-```python
-Button(label="Save", event="app:save", component_id="save-btn")
-Toolbar(position="top", items=[...], component_id="main-toolbar")
-```
-
-**HTML Output:**
-
-```html
-<button class="pywry-btn" id="save-btn" data-event="app:save">Save</button>
-<div class="pywry-toolbar pywry-toolbar-top" id="main-toolbar" data-component-id="main-toolbar">
-```
-
-**Targeting in CSS:**
-
-```css
-/* Target specific component by ID */
-#save-btn { background: green; }
-
-/* Target component type */
-[id^="button-"] { font-weight: bold; }
-
-/* Target by data attribute */
-[data-event="app:save"] { border: 2px solid gold; }
-```
-
-**Targeting in JavaScript:**
-
-```javascript
-// Direct selection
-document.getElementById('save-btn').style.display = 'none';
-
-// Query by data attribute
-document.querySelector('[data-event="app:save"]').click();
-```
-
-**Parent-Child Relationships:**
-
-`Div` containers pass their `component_id` as `data-parent-id` to children:
-
-```python
-Div(
-    component_id="actions-group",
-    children=[
-        Button(label="Edit", event="app:edit"),
-        Button(label="Delete", event="app:delete", variant="danger"),
-    ]
-)
-```
-
-```html
-<div class="pywry-div" id="actions-group" data-component-id="actions-group">
-    <button class="pywry-btn" id="button-xyz123" data-parent-id="actions-group" ...>Edit</button>
-    <button class="pywry-btn pywry-btn-danger" id="button-abc456" data-parent-id="actions-group" ...>Delete</button>
-</div>
-```
-
-</details>
-
-### CSS Variables
-
-<details>
-<summary>All CSS custom properties (colors, typography, spacing, transitions)</summary>
-
-Customize these variables via `inline_css` or a custom theme CSS file:
-
-```css
-:root {
-  /* ---- Color Palette (Dark Theme Default) ---- */
-  --pywry-bg-primary: #212124;
-  --pywry-bg-secondary: rgba(21, 21, 24, 1);
-  --pywry-bg-tertiary: rgba(31, 30, 35, 1);
-  --pywry-bg-quartary: rgba(36, 36, 42, 1);
-  --pywry-bg-hover: rgba(255, 255, 255, 0.08);
-  --pywry-bg-overlay: rgba(30, 30, 30, 0.8);
-  --pywry-text-primary: #ebebed;
-  --pywry-text-secondary: #a0a0a0;
-  --pywry-text-muted: #707070;
-  --pywry-border-color: #333;
-
-  /* ---- Accent Colors ---- */
-  --pywry-accent: #0078d4;
-  --pywry-accent-hover: #106ebe;
-  --pywry-text-accent: rgb(51, 187, 255);
-
-  /* ---- Scrollbar Colors (optional - has fallbacks) ---- */
-  --pywry-scrollbar-thumb: rgba(155, 155, 155, 0.5);       /* default fallback */
-  --pywry-scrollbar-thumb-hover: rgba(175, 175, 175, 0.7); /* default fallback */
-
-  /* ---- Button Colors ---- */
-  --pywry-btn-primary-bg: #e2e2e2;
-  --pywry-btn-primary-text: #151518;
-  --pywry-btn-primary-hover: #cccccc;
-  --pywry-btn-secondary-bg: #3d3d42;
-  --pywry-btn-secondary-text: #ebebed;
-  --pywry-btn-secondary-hover: #4a4a50;
-  --pywry-btn-secondary-border: rgba(90, 90, 100, 0.5);
-  --pywry-btn-neutral-bg: rgb(0, 136, 204);
-  --pywry-btn-neutral-text: #ffffff;
-  --pywry-btn-neutral-hover: rgb(0, 115, 173);
-
-  /* ---- Tab Group Colors ---- */
-  --pywry-tab-bg: #2a2a2e;
-  --pywry-tab-active-bg: #3d3d42;
-  --pywry-tab-hover-bg: #353538;
-
-  /* ---- Typography ---- */
-  --pywry-font-family: Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
-  --pywry-font-size: 14px;
-  --pywry-font-weight-normal: 400;
-  --pywry-font-weight-medium: 500;
-
-  /* ---- Spacing & Layout ---- */
-  --pywry-radius: 4px;
-  --pywry-radius-lg: 6px;
-  --pywry-spacing-xs: 2px;
-  --pywry-spacing-sm: 4px;
-  --pywry-spacing-md: 6px;
-  --pywry-spacing-lg: 8px;
-
-  /* ---- Widget Sizing ---- */
-  --pywry-widget-width: 100%;
-  --pywry-widget-min-height: 200px;
-  --pywry-widget-height: 500px;
-  --pywry-grid-min-height: 200px;
-
-  /* ---- Focus & Borders ---- */
-  --pywry-border-focus: #555;
-
-  /* ---- Transitions ---- */
-  --pywry-transition-fast: 0.1s ease;
-  --pywry-transition-normal: 0.2s ease;
-}
-
-/* ---- Light Theme Overrides ---- */
-html.light, .pywry-theme-light {
-  --pywry-bg-primary: #f5f5f5;
-  --pywry-bg-secondary: #ffffff;
-  --pywry-bg-hover: rgba(0, 0, 0, 0.06);
-  --pywry-bg-overlay: rgba(255, 255, 255, 0.8);
-  --pywry-text-primary: #000000;
-  --pywry-text-secondary: #666666;
-  --pywry-text-muted: #999999;
-  --pywry-border-color: #ccc;
-  --pywry-border-focus: #999;
-  --pywry-tab-bg: #e8e8ec;
-  --pywry-tab-active-bg: #ffffff;
-  --pywry-tab-hover-bg: #f0f0f4;
-  --pywry-btn-primary-bg: #2c2c32;
-  --pywry-btn-primary-text: #ffffff;
-  --pywry-btn-primary-hover: #1a1a1e;
-  --pywry-btn-secondary-bg: #d0d0d8;
-  --pywry-btn-secondary-text: #2c2c32;
-  --pywry-btn-secondary-hover: #c0c0c8;
-  --pywry-btn-secondary-border: rgba(180, 180, 190, 1);
-}
-```
-
-</details>
-
-### Example: Custom Styling with Built-in Events
-
-```python
-from pywry import PyWry, Toolbar, Button
-
-app = PyWry()
-
-def on_click(data, event_type, label):
-    """Change the button to green when clicked."""
-    app.emit("pywry:set-style", {
-        "id": "my-btn",
-        "styles": {"backgroundColor": "#22c55e", "color": "#fff"}
-    }, label)
-
-handle = app.show(
-    '<div id="status" style="padding:20px;">Click the button to change its color</div>',
-    toolbars=[Toolbar(position="top", items=[
-        Button(label="Click Me", event="app:click", component_id="my-btn")
-    ])],
-    callbacks={"app:click": on_click}
-)
-```
-
-</details>
-
----
-
-## JavaScript Bridge
-
-<details>
-<summary>Click to expand</summary>
-
-**In this section:** [Available Methods](#available-methods) · [Injected Globals](#injected-globals) · [AgGrid API](#accessing-aggrid-api) · [Plotly API](#accessing-plotly-api) · [Toolbar API](#accessing-toolbar-api) · [Toast Notifications](#using-toast-notifications) · [Two-Way Communication](#example-two-way-communication) · [System Event Handlers](#built-in-system-event-handlers)
-
----
-
-PyWry injects a `window.pywry` object for JavaScript ↔ Python communication.
-
-### Available Methods
-
-```javascript
-// Send result back to Python
-window.pywry.result(data);
-
-// Emit event to Python
-window.pywry.emit("app:action", { key: "value" });
-
-// Register JS event handler
-window.pywry.on("app:update", function(data) {
-    console.log("Received:", data);
-});
-
-// Remove event handler
-window.pywry.off("app:update", handler);
-
-// Open file with system default application
-window.pywry.openFile("/path/to/file.pdf");
-
-// Get current theme
-console.log(window.pywry.theme);  // "dark" or "light"
-```
-
-### Injected Globals
-
-PyWry injects several globals into the browser context:
-
-```javascript
-// ─────────────────────────────────────────────────────────────────────────────
-// CORE GLOBALS (always present)
-// ─────────────────────────────────────────────────────────────────────────────
-
-window.__PYWRY_LABEL__          // Window label, e.g., "main-window"
-window.json_data                // JSON data from Python (via HtmlContent.json_data)
-
-// ─────────────────────────────────────────────────────────────────────────────
-// PLOTLY GLOBALS (when include_plotly=True)
-// ─────────────────────────────────────────────────────────────────────────────
-
-window.__PYWRY_PLOTLY_DIV__     // Reference to main Plotly chart container
-window.__PYWRY_CHARTS__         // Registry of all Plotly charts by ID
-window.PYWRY_PLOTLY_TEMPLATES   // Bundled templates: ggplot2, seaborn, simple_white,
-                                // plotly, plotly_white, plotly_dark, presentation,
-                                // xgridoff, ygridoff, gridon
-
-// ─────────────────────────────────────────────────────────────────────────────
-// AGGRID GLOBALS (when include_aggrid=True)
-// ─────────────────────────────────────────────────────────────────────────────
-
-window.__PYWRY_GRID_API__       // Main AgGrid API for the primary grid
-window.__PYWRY_GRIDS__          // Registry of all grid instances by ID
-window.PYWRY_SHOW_NOTIFICATION  // Helper: PYWRY_SHOW_NOTIFICATION(msg, duration, container)
-
-// ─────────────────────────────────────────────────────────────────────────────
-// TOOLBAR GLOBALS (when toolbar is rendered)
-// ─────────────────────────────────────────────────────────────────────────────
-
-window.__PYWRY_TOOLBAR__        // Toolbar API: { getState(), getValue(id), setValue(id, val) }
-
-// ─────────────────────────────────────────────────────────────────────────────
-// TOAST NOTIFICATION SYSTEM
-// ─────────────────────────────────────────────────────────────────────────────
-
-window.PYWRY_TOAST              // Toast API: show(type, message, options), dismiss(id), clear()
-                                // Types: 'info', 'success', 'warning', 'error', 'confirm'
-```
-
-### Accessing AgGrid API
-
-```javascript
-// ── Primary Grid API ──────────────────────────────────────────────────────────
-// Get selected rows
-const rows = window.__PYWRY_GRID_API__.getSelectedRows();
-
-// Update data
-window.__PYWRY_GRID_API__.setGridOption('rowData', newData);
-
-// Apply transactions
-window.__PYWRY_GRID_API__.applyTransaction({ update: [row1, row2] });
-
-// Export to CSV
-window.__PYWRY_GRID_API__.exportDataAsCsv();
-
-// ── Multi-Grid Access ─────────────────────────────────────────────────────────
-// Access any grid by its ID
-const grid = window.__PYWRY_GRIDS__['my-grid-id'];
-if (grid) {
-    grid.api.getSelectedRows();
-}
-
-// Show a notification toast
-window.PYWRY_SHOW_NOTIFICATION('Data updated!', 3000);
-```
-
-### Accessing Plotly API
-
-```javascript
-// ── Primary Chart API ─────────────────────────────────────────────────────────
-// Update chart layout
-Plotly.relayout(window.__PYWRY_PLOTLY_DIV__, { title: 'New Title' });
-
-// Update chart data
-Plotly.react(window.__PYWRY_PLOTLY_DIV__, newData, newLayout);
-
-// Apply template
-Plotly.update(window.__PYWRY_PLOTLY_DIV__, {}, {
-    template: window.PYWRY_PLOTLY_TEMPLATES['seaborn']
-});
-
-// ── Multi-Chart Access ────────────────────────────────────────────────────────
-// Access any chart by its ID
-const chart = window.__PYWRY_CHARTS__['my-chart-id'];
-if (chart) {
-    Plotly.relayout(chart, { title: 'Updated' });
-}
-```
-
-### Accessing Toolbar API
-
-```javascript
-// Get current state of all toolbar components
-const state = window.__PYWRY_TOOLBAR__.getState();
-// { "theme-select": "dark", "zoom-slider": 100 }
-
-// Get value of a specific component by ID
-const theme = window.__PYWRY_TOOLBAR__.getValue('theme-select');
-
-// Set value of a component (triggers change event)
-window.__PYWRY_TOOLBAR__.setValue('zoom-slider', 150);
-```
-
-### Using Toast Notifications
-
-```javascript
-// Show different toast types
-window.PYWRY_TOAST.show('info', 'Processing your request...');
-window.PYWRY_TOAST.show('success', 'Changes saved!');
-window.PYWRY_TOAST.show('warning', 'This action cannot be undone');
-window.PYWRY_TOAST.show('error', 'Failed to connect to server');
-
-// Confirmation dialog with callback
-window.PYWRY_TOAST.show('confirm', 'Delete this item?', {
-    onConfirm: function() { deleteItem(); },
-    onCancel: function() { console.log('Cancelled'); }
-});
-
-// Dismiss all toasts
-window.PYWRY_TOAST.clear();
-```
-
-### Example: Two-Way Communication
-
-```python
-from pywry import PyWry
-
-app = PyWry()
-
-def handle_request(data, event_type, label):
-    """Send response back to JavaScript."""
-    app.emit("app:response", {"items": [1, 2, 3]}, label)
-
-handle = app.show("""
-<button onclick="requestData()">Fetch Data</button>
-<div id="result">Click the button...</div>
-<script>
-function requestData() {
-    window.pywry.emit('app:request-data', {});
-}
-window.pywry.on('app:response', function(data) {
-    document.getElementById('result').textContent = JSON.stringify(data);
-});
-</script>
-""", callbacks={"app:request-data": handle_request})
-```
-
-### Built-in System Event Handlers
-
-PyWry pre-registers handlers for common UI manipulation events. These are handled automatically by the JavaScript bridge — **you don't need to write any JavaScript to use them**:
-
-```python
-from pywry import PyWry
-
-app = PyWry()
-
-# Create a window first
-handle = app.show("""
-<div id="message">Hello</div>
-<div id="counter">0</div>
-<span class="count">initial</span>
-""")
-
-# Theme switching (updates Plotly templates, AgGrid themes, and CSS classes)
-handle.emit("pywry:update-theme", {"theme": "light"})
-
-# Inject CSS dynamically (with optional id for replacement)
-handle.emit("pywry:inject-css", {"css": ".status { color: green; }", "id": "status-css"})
-
-# Update element styles by id
-handle.emit("pywry:set-style", {"id": "counter", "styles": {"fontSize": "24px", "fontWeight": "bold"}})
-
-# Update element content by id
-handle.emit("pywry:set-content", {"id": "message", "html": "<strong>Success!</strong>"})
-
-# Update element content by CSS selector
-handle.emit("pywry:set-content", {"selector": ".count", "text": "42"})
-```
-
-See [Utility Events (Python → JS)](#utility-events-python-to-js) for complete documentation.
-
-</details>
-
----
-
-## Direct Tauri API Access
-
-<details>
-<summary>Click to expand</summary>
-
-**In this section:** [`__TAURI__` Global](#the-__tauri__-global) · [PyTauri IPC](#pytauri-ipc-python--javascript) · [Listening to Events](#listening-to-python-events-javascript) · [Tauri Events](#tauri-internal-events-advanced) · [Custom Handler](#example-custom-tauri-handler) · [Environment Detection](#environment-detection)
-
----
-
-For advanced use cases, you can access the underlying Tauri IPC system directly. PyWry is built on [PyTauri](https://pypi.org/project/pytauri/), which provides full access to Tauri's capabilities.
-
-### The `__TAURI__` Global
-
-When running in a desktop window (not in notebook/inline mode), the `window.__TAURI__` object provides direct access to Tauri APIs:
-
-```javascript
-// Check if running in Tauri context
-if (window.__TAURI__) {
-    console.log("Running in Tauri desktop mode");
-}
-
-// Available Tauri plugin APIs:
-window.__TAURI__.dialog    // Native file dialogs (save, open, message, ask, confirm)
-window.__TAURI__.fs        // Filesystem operations (readTextFile, writeTextFile, exists, mkdir)
-window.__TAURI__.event     // Event system (listen, emit)
-window.__TAURI__.pytauri   // Python IPC (pyInvoke)
-```
-
-### PyTauri IPC (Python ↔ JavaScript)
-
-Use `window.__TAURI__.pytauri.pyInvoke` to call Python-registered commands:
-
-```javascript
-// Invoke a PyWry command
-window.__TAURI__.pytauri.pyInvoke('pywry_event', {
-    label: window.__PYWRY_LABEL__,
-    event_type: 'custom:action',
-    data: { key: 'value' }
-});
-
-// Send result to Python
-window.__TAURI__.pytauri.pyInvoke('pywry_result', {
-    data: { result: 'success' },
-    window_label: window.__PYWRY_LABEL__
-});
-
-// Open a file with system default app
-window.__TAURI__.pytauri.pyInvoke('open_file', { path: '/path/to/file.pdf' });
-```
-
-### Listening to Python Events (JavaScript)
-
-Use `window.pywry.on()` to receive events sent from Python:
-
-```javascript
-// Listen for custom events from Python
-window.pywry.on('app:data-update', function(data) {
-    console.log('Received data:', data);
-    updateUI(data);
-});
-
-// Wildcard listener for debugging
-window.pywry.on('*', function(payload) {
-    console.log('Event:', payload.type, payload.data);
-});
-```
-
-### Tauri Internal Events (Advanced)
-
-> **Warning:** These are low-level internal events used by PyWry's core. Most users should use the `window.pywry` bridge instead.
-
-For advanced use cases, you can listen to raw Tauri IPC events:
-
-```javascript
-// Only works in desktop mode (not notebooks)
-if (window.__TAURI__) {
-    // Listen for cleanup signal before window closes
-    window.__TAURI__.event.listen('pywry:cleanup', function() {
-        console.log('Window closing, save state...');
-    });
-}
-```
-
-| Internal Event | Payload | Description |
-|----------------|---------|-------------|
-| `pywry:content` | `{ html, theme }` | Set window HTML content |
-| `pywry:eval` | `{ script }` | Execute JavaScript in window |
-| `pywry:event` | `{ type, data }` | Wrapper for Python → JS events |
-| `pywry:init` | `{ label }` | Window initialization |
-| `pywry:cleanup` | None | Window about to close |
-| `pywry:inject-css` | `{ id, css }` | Inject CSS dynamically |
-| `pywry:remove-css` | `{ id }` | Remove injected CSS |
-| `pywry:refresh` | None | Refresh window content |
-
-### Example: Custom Tauri Handler
-
-```python
-from pywry import PyWry
-
-app = PyWry()
-
-def on_button_click(data, event_type, label):
-    """Handle button click from JavaScript and send response."""
-    count = data.get("count", 0)
-    print(f'Received click #{count}')
-    app.emit('custom:update', {'message': f'Hello from Python! Count: {count}'}, label)
-
-handle = app.show('''
-<div id="output">Click the button...</div>
-<button onclick="sendToPython()">Send to Python</button>
-<script>
-var count = 0;
-window.pywry.on('custom:update', function(data) {
-    document.getElementById('output').textContent = data.message;
-});
-function sendToPython() {
-    count++;
-    window.pywry.emit('custom:button-click', { count: count });
-}
-</script>
-''', callbacks={'custom:button-click': on_button_click})
-```
-
-> **Note:** The `window.pywry` bridge is automatically initialized by PyWry. Use `window.pywry.on()` to listen for events from Python, and `window.pywry.emit()` to send events to Python. Native mode returns a `NativeWindowHandle` - use `handle.emit()` or `app.emit(event, data, handle.label)`. Notebook mode returns a widget with `.emit()`.
-
-### Environment Detection
-
-Check whether you're running in desktop mode vs notebook/inline:
-
-```javascript
-// In desktop mode, __TAURI__ exists
-const isDesktop = !!window.__TAURI__;
-
-// In notebook mode, content is in an iframe
-const isNotebook = window.frameElement !== null;
-
-// Conditional logic
-if (isDesktop) {
-    // Use Tauri APIs
-    window.__TAURI__.pytauri.pyInvoke('pywry_event', payload);
-} else {
-    // Use postMessage for iframe communication
-    window.parent.postMessage({ type: 'pywry:event', ...payload }, '*');
-}
-```
-
-</details>
-
----
-
-## Managing Multiple Windows/Widgets
-
-<details>
-<summary>Click to expand</summary>
-
-PyWry can display content in multiple ways, and each has its own management model. This section explains how to create, control, and clean up your display contexts.
-
-**In this section:** [Window vs. Widget](#what-is-a-window-vs-a-widget) · [WindowMode Options](#windowmode-options) · [Return Types](#return-types-by-mode) · [Native Window Management](#native-window-management) · [Widget Management](#widget-management-notebookbrowser) · [Storing References](#storing-references-for-later-control) · [Non-Blocking Scripts](#non-blocking-scripts-with-block) · [Graceful Shutdown](#graceful-shutdown-with-stop_server) · [Instance Methods](#summary-pywry-instance-methods) · [Widget Methods](#summary-widget-methods-notebookbrowser)
-
-### What is a Window vs. a Widget?
-
-| Term | What It Is | When You Get It |
-|------|------------|-----------------|
-| **Window** | A native desktop window (Tauri/WRY) | `WindowMode.NEW_WINDOW`, `SINGLE_WINDOW`, `MULTI_WINDOW` |
-| **Widget** | An embedded display in a notebook cell or browser tab | `WindowMode.NOTEBOOK`, `BROWSER` |
-
-Both **windows** and **widgets** display the same content (HTML, Plotly charts, AgGrid tables). The difference is where and how they appear to the user.
-
-### WindowMode Options
-
-When you create a `PyWry` instance, you choose a mode:
-
-```python
-from pywry import PyWry, WindowMode
-
-# Choose your mode
-app = PyWry(mode=WindowMode.MULTI_WINDOW)
-```
-
-| Mode | Behavior | Use Case |
-|------|----------|----------|
-| `NEW_WINDOW` | Each `show_*()` opens a fresh native window | Simple scripts, one-off displays |
-| `SINGLE_WINDOW` | Reuses the same window, replaces content | Dashboard with tab-like navigation |
-| `MULTI_WINDOW` | Each `show_*()` opens a new window, all stay open | Multi-monitor setups, side-by-side views |
-| `NOTEBOOK` | Renders inline in Jupyter/VS Code notebooks | Interactive data exploration |
-| `BROWSER` | Renders via URL in system browser | Server/headless mode, remote access |
-
-> **Auto-Detection:** If you don't specify a mode, PyWry detects your environment:
-> - Jupyter notebook detected → `NOTEBOOK`
-> - No display available (headless) → `BROWSER`
-> - Otherwise → `NEW_WINDOW`
-
-### Return Types by Mode
-
-The `show_*()` methods return widget objects that provide a unified API:
-
-| Mode | `show_*()` Returns | Control Via |
-|------|-------------------|-------------|
-| `NEW_WINDOW`, `SINGLE_WINDOW`, `MULTI_WINDOW` | `NativeWindowHandle` | `handle.emit(...)`, `handle.close()`, or `app.emit(event, data, handle.label)` |
-| `NOTEBOOK`, `BROWSER` | `BaseWidget` (PyWryWidget/InlineWidget) | `widget.emit(...)`, `widget.on(...)`, `widget.update(...)` |
-
-**Native mode:** use `handle.emit(event, data)` or `app.emit(event, data, handle.label)` to send events to JavaScript.
-**Notebook mode:** use `widget.emit(event, data)` on the returned widget.
-
----
-
-### Native Window Management
-
-In native modes, `show_*()` returns a `NativeWindowHandle` that provides access to the window:
-
-```python
-from pywry import PyWry, WindowMode
-import plotly.express as px
-import pandas as pd
-
-app = PyWry(mode=WindowMode.MULTI_WINDOW)
-
-fig = px.scatter(px.data.iris(), x="sepal_width", y="sepal_length")
-df = pd.DataFrame({"name": ["Alice", "Bob"], "age": [30, 25]})
-
-# Each show_*() returns a NativeWindowHandle
-handle1 = app.show_plotly(fig, title="Chart 1")
-handle2 = app.show_dataframe(df, title="Data")
-handle3 = app.show("<h1 id='heading'>Custom</h1>", title="Custom")
-
-# Send built-in events using handle.emit() or app.emit() with handle.label
-handle3.emit("pywry:set-content", {"id": "heading", "text": "Updated!"})
-
-# Close a specific window
-handle1.close()
-```
-
-#### Querying Windows
-
-```python
-# Get all active window labels
-labels = app.get_labels()  # ["pywry-a1b2c3", "pywry-d4e5f6", "pywry-g7h8i9"]
-
-# Check if a specific window is still open
-if app.is_open(handle1.label):
-    print(f"Window {handle1.label} is still open")
-
-# Check if ANY window is open
-if app.is_open():
-    print("At least one window is open")
-```
-
-#### Controlling Windows
-
-```python
-# Update content using handle.emit() (recommended)
-handle1.emit("pywry:set-content", {"id": "heading", "text": "Hello!"})
-
-# Refresh a specific window (full page reload)
-app.refresh(handle1.label)
-
-# Close a specific window
-handle1.close()  # or app.close(handle1.label)
-
-# Close ALL windows
-app.close()  # No label = close all
-```
-
----
-
-### Widget Management (Notebook/Browser)
-
-In notebook or browser mode, `show_*()` returns a **widget object** with methods for control:
-
-```python
-from pywry import PyWry, WindowMode
-import plotly.express as px
-
-app = PyWry(mode=WindowMode.NOTEBOOK)
-
-fig = px.scatter(px.data.iris(), x="sepal_width", y="sepal_length", color="species")
-
-# show_*() returns a widget object (not a string)
-widget = app.show_plotly(fig, title="Interactive Chart")
-
-# The widget has a label property for identification
-# widget.label  # "w-abc12345"
-```
-
-#### Widget Properties
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `widget.label` | `str` | Unique identifier (e.g., `"w-abc12345"`) |
-| `widget.url` | `str` | Full URL to access in a browser (e.g., `"http://localhost:8765/widget/w-abc12345"`) |
-| `widget.output` | `Output` | IPython Output widget for callback print statements |
-
-#### Registering Event Handlers
-
-```python
-def on_click(data, event_type, label):
-    """Update the chart title when a point is clicked."""
-    point = data["points"][0]
-    widget.emit("plotly:update-layout", {
-        "layout": {"title": f"Clicked: ({point['x']:.2f}, {point['y']:.2f})"}
-    })
-
-def handle_action(data, event_type, label):
-    """Handle custom action by updating status."""
-    widget.emit("pywry:set-content", {"id": "status", "text": "Action complete!"})
-
-# Register handlers — method chaining supported
-widget.on("plotly:click", on_click)
-widget.on("custom:action", handle_action)
-
-# Chaining works too
-widget.on("plotly:click", on_click).on("plotly:hover", on_hover)
-```
-
-#### Sending Events to JavaScript
-
-```python
-# Update theme using built-in utility event
-widget.emit("pywry:update-theme", {"theme": "plotly_dark"})
-
-# Or update content
-widget.emit("pywry:set-content", {"id": "status", "text": "Updated!"})
-```
-
-#### Updating Content
-
-```python
-# Replace the widget's HTML content
-widget.update("<h1>New content</h1>")
-
-# For Plotly widgets: update the figure
-widget.update_figure(new_fig)
-
-# For AgGrid widgets: update the data
-widget.update_data(new_rows)
-```
-
-#### Display Methods
-
-```python
-# Display in notebook (usually automatic)
-widget.display()
-
-# Open the widget's URL in system browser (useful for BROWSER mode)
-widget.open_in_browser()
-```
-
----
-
-### Storing References for Later Control
-
-Save the return values to control windows/widgets later:
-
-```python
-from pywry import PyWry, WindowMode
-
-app = PyWry(mode=WindowMode.MULTI_WINDOW)
-
-# Store references in a dict for easy access
-windows = {}
-windows["main"] = app.show_plotly(fig, title="Main Chart")
-windows["sidebar"] = app.show_dataframe(df, title="Data Panel")
-
-# Later: send events to specific windows
-def refresh_main():
-    windows["main"].emit("plotly:update-figure", {"figure": new_fig_dict})
-
-def close_sidebar():
-    windows["sidebar"].close()
-    del windows["sidebar"]
-```
-
----
-
-### Non-Blocking Scripts with `block()`
-
-In BROWSER mode (scripts, not notebooks), windows open but the script continues immediately. Use `block()` to wait for users to close all windows:
-
-```python
-from pywry import PyWry, WindowMode
-from pywry.inline import block
-
-app = PyWry(mode=WindowMode.BROWSER)
-widget = app.show_plotly(fig, title="Dashboard")
-widget.open_in_browser()  # Opens in default browser
-
-# Script continues immediately — window is open in browser
-
-# Do other work while user interacts with the chart
-print("Chart is open, doing other work...")
-
-# When ready, block until all browser tabs are closed
-block()  # Waits for all widgets to disconnect
-print("All windows closed, exiting")
-```
-
----
-
-### Graceful Shutdown with `stop_server()`
-
-For clean shutdown in long-running processes (web servers, daemons):
-
-```python
-from pywry import PyWry, WindowMode
-from pywry.inline import block, stop_server
-import signal
-
-app = PyWry(mode=WindowMode.BROWSER)
-
-def cleanup(signum, frame):
-    print("Shutting down...")
-    app.close()               # Close all windows
-    stop_server(timeout=5.0)  # Stop inline server with 5s timeout (default)
-    exit(0)
-
-signal.signal(signal.SIGINT, cleanup)
-signal.signal(signal.SIGTERM, cleanup)
-
-# Show windows
-widget1 = app.show_plotly(fig1)
-widget2 = app.show_plotly(fig2)
-widget1.open_in_browser()
-widget2.open_in_browser()
-
-# Keep running until interrupted
-block()
-```
-
----
-
-### Summary: PyWry Instance Methods
-
-Methods available on the `PyWry` app instance:
-
-| Method | Description |
-|--------|-------------|
-| `app.show(html, ...)` | Show HTML content, returns `NativeWindowHandle` or widget |
-| `app.show_plotly(fig, ...)` | Show Plotly figure, returns `NativeWindowHandle` or widget |
-| `app.show_dataframe(df, ...)` | Show DataFrame as AgGrid, returns `NativeWindowHandle` or widget |
-| `app.get_labels()` | Get list of all active window labels |
-| `app.is_open(label=None)` | Check if window(s) are open |
-| `app.emit(event, data, label=None)` | Send event to window(s) |
-| `app.close(label=None)` | Close specific or all windows |
-| `app.refresh(label=None)` | Refresh specific or all windows |
-| `app.refresh_css(label=None)` | Hot-reload CSS without page refresh |
-| `app.on(event, handler)` | Register global event handler |
-| `app.on_chart(event, handler)` | Register Plotly event handler (convenience) |
-| `app.on_grid(event, handler)` | Register AgGrid event handler (convenience) |
-| `app.on_toolbar(event, handler)` | Register toolbar event handler (convenience) |
-| `app.on_html(event, handler)` | Register HTML element event handler (convenience) |
-| `app.on_window(event, handler)` | Register window lifecycle event handler (convenience) |
-| `app.eval_js(script, label)` | Execute JavaScript in a window |
-
-### Summary: Widget Methods (Notebook/Browser)
-
-Methods available on widget objects returned by `show_*()` in NOTEBOOK/BROWSER modes:
-
-| Property/Method | Description |
-|-----------------|-------------|
-| `widget.label` | Unique identifier for this widget |
-| `widget.url` | Full URL to access this widget in a browser |
-| `widget.output` | IPython Output widget for callback prints |
-| `widget.on(event, handler)` | Register event handler (chainable) |
-| `widget.emit(event, data)` | Send event to JavaScript |
-| `widget.update(html)` | Replace widget HTML content |
-| `widget.display()` | Display widget in notebook cell |
-| `widget.open_in_browser()` | Open widget URL in system browser |
-
-**Plotly-specific widget methods:**
-
-| Method | Description |
-|--------|-------------|
-| `widget.update_figure(fig)` | Update the Plotly figure |
-| `widget.reset_zoom()` | Reset chart zoom to auto-range |
-| `widget.set_zoom(x_range, y_range)` | Set chart zoom to specific range |
-
-**AgGrid-specific widget methods:**
-
-| Method | Description |
-|--------|-------------|
-| `widget.update_data(rows)` | Replace grid data |
-| `widget.update_columns(col_defs)` | Replace column definitions |
-| `widget.update_cell(row_id, col, value)` | Update a single cell |
-| `widget.update_grid(data, columns, state)` | Update multiple aspects at once |
-| `widget.request_grid_state()` | Request current grid state (emits `grid:state-response`) |
-| `widget.restore_state(state)` | Restore a saved grid state |
-| `widget.reset_state()` | Reset grid to default state |
-
-**Toolbar-specific widget methods:**
-
-| Method | Description |
-|--------|-------------|
-| `widget.request_toolbar_state()` | Request current toolbar state (emits `toolbar:state-response`) |
-| `widget.get_toolbar_value(component_id)` | Request a specific component's value |
-| `widget.set_toolbar_value(id, value)` | Set a component's value |
-| `widget.set_toolbar_values(values)` | Set multiple component values at once |
-
-</details>
-
----
-
-## Browser Mode & Server Configuration
-
-<details>
-<summary>Click to expand</summary>
-
-**In this section:** [Getting Widget URL](#getting-the-widget-url) · [Server Configuration](#server-configuration) · [Environment Variables](#environment-variables) · [Production Deployment](#production-deployment-pattern) · [HTTPS](#https-configuration) · [Health Check](#server-health-check) · [WebSocket & API Security](#websocket--api-security)
-
----
-
-For headless environments, remote deployments, or when you want to serve dashboards via HTTP, use `BROWSER` mode with the inline FastAPI server.
-
-### Getting the Widget URL
-
-Every widget has a `.url` property that provides the direct HTTP endpoint:
-
-```python
-from pywry import PyWry, WindowMode
-
-app = PyWry(mode=WindowMode.BROWSER)
-
-# show_* returns an InlineWidget with a .url property
-widget = app.show_plotly(fig, title="Dashboard")
-
-print(widget.url)  # http://127.0.0.1:8765/widget/abc123def456
-```
-
-You can share this URL with anyone who can reach the server.
-
-### Server Configuration
-
-Configure the inline server via `pywry.toml`, `pyproject.toml`, or environment variables:
-
-```toml
-# pywry.toml or [tool.pywry.server] in pyproject.toml
-[server]
-host = "0.0.0.0"              # Bind to all interfaces (for remote access)
-port = 8080                   # Custom port
-auto_start = true             # Auto-start when first widget created
-force_notebook = false        # Force notebook mode in headless environments
-
-# Uvicorn settings
-workers = 1                   # Worker processes
-log_level = "info"            # Uvicorn log level
-access_log = true             # Enable access logging
-reload = false                # Auto-reload (dev mode)
-
-# Timeouts
-timeout_keep_alive = 5        # Keep-alive timeout (seconds)
-timeout_graceful_shutdown = 30  # Graceful shutdown timeout
-
-# SSL/TLS for HTTPS
-ssl_keyfile = "/path/to/key.pem"
-ssl_certfile = "/path/to/cert.pem"
-ssl_keyfile_password = "optional-password"
-ssl_ca_certs = "/path/to/ca-bundle.crt"
-
-# CORS settings (for cross-origin requests)
-cors_origins = ["*"]          # Allowed origins (use specific domains in production)
-cors_allow_credentials = true
-cors_allow_methods = ["*"]
-cors_allow_headers = ["*"]
-
-# Limits
-limit_concurrency = 100       # Max concurrent connections
-limit_max_requests = 10000    # Max requests before worker restart
-backlog = 2048                # Socket backlog size
-
-# WebSocket Security
-websocket_allowed_origins = [] # Allowed origins for WebSocket (empty = any, rely on token)
-websocket_require_token = true # Require per-widget token for WebSocket auth
-
-# Internal API Security
-internal_api_header = "X-PyWry-Token"  # Header name for internal auth
-internal_api_token = ""                # Auto-generated if not set
-strict_widget_auth = false             # false = notebook (lenient), true = browser (strict)
-```
-
-### Environment Variables
-
-Override any server setting with `PYWRY_SERVER__*`:
-
-```bash
-# Remote deployment: bind to all interfaces
-export PYWRY_SERVER__HOST=0.0.0.0
-export PYWRY_SERVER__PORT=8080
-
-# Enable HTTPS
-export PYWRY_SERVER__SSL_CERTFILE=/etc/ssl/certs/server.crt
-export PYWRY_SERVER__SSL_KEYFILE=/etc/ssl/private/server.key
-
-# Restrict CORS for production
-export PYWRY_SERVER__CORS_ORIGINS='["https://myapp.com"]'
-
-# Enable logging
-export PYWRY_SERVER__LOG_LEVEL=info
-export PYWRY_SERVER__ACCESS_LOG=true
-
-# WebSocket Security
-export PYWRY_SERVER__WEBSOCKET_ALLOWED_ORIGINS='http://localhost:8080,https://app.example.com'
-export PYWRY_SERVER__WEBSOCKET_REQUIRE_TOKEN=true
-
-# Internal API Security
-export PYWRY_SERVER__INTERNAL_API_HEADER=X-PyWry-Token
-export PYWRY_SERVER__INTERNAL_API_TOKEN=my-secret-token  # Or leave empty for auto-gen
-export PYWRY_SERVER__STRICT_WIDGET_AUTH=true  # Browser mode (stricter)
-```
-
-### Production Deployment Pattern
-
-For production deployments, create **view factory functions** that generate widgets on demand. Each user request gets a fresh widget instance with a unique ID, while you maintain static, bookmarkable routes.
-
-#### Environment Variables for Production
-
-```bash
-# Set this environment variable on your server:
-export PYWRY_HEADLESS=1  # Forces InlineWidget, skips browser.open()
-```
-
-**What `PYWRY_HEADLESS=1` does:**
-- Forces `InlineWidget` (FastAPI/IFrame) instead of `anywidget` - ensuring `.url` and `.label` are always available
-- Prevents `open_in_browser()` from being called (which would fail on headless servers)
-- No code changes needed - the same API works locally and in production
-
-#### Architecture Overview
-
-```
-Static Route           View Factory           Widget Instance
-──────────────         ──────────────         ─────────────────
-GET /dashboard    →    create_dashboard()  →  /widget/{unique_id}
-GET /analytics    →    create_analytics()  →  /widget/{unique_id}
-GET /sales        →    create_sales()      →  /widget/{unique_id}
-```
-
-**How it works:**
-
-1. `pywry.inline.show_plotly()` creates an `InlineWidget` and **immediately** registers it in `_state.widgets`
-2. The server reads from `_state.widgets` when serving `/widget/{id}`
-3. The redirect happens **after** the widget is registered, so it's always available
-
-> **Important:** Set `PYWRY_HEADLESS=1` on your production server. This ensures the same code works both locally (opens browser) and on servers (no browser, just widget registration).
-
-> **Note:** Call `_start_server()` at module load time (not inside route handlers) to avoid a startup delay on the first request.
-
-#### Complete Production Example
-
-```python
-# app.py - Production PyWry server with static routes
-from fastapi import Request
-from fastapi.responses import RedirectResponse
-from pywry.inline import (
-    _state,
-    _start_server,
-    show,              # For HTML content
-    show_plotly,       # For Plotly figures
-    show_dataframe,    # For DataFrames/AgGrid
-)
-import plotly.express as px
-import pandas as pd
-
-# Start the server at module load time (before defining routes)
-_start_server()
-
-# Get PyWry's FastAPI app and add custom routes
-app = _state.app
-
-# ═══════════════════════════════════════════════════════════
-# VIEW FACTORIES - Each creates a fresh widget for each request
-# open_browser=True forces InlineWidget (required for server deployments)
-# With PYWRY_HEADLESS=1, browser.open() is automatically skipped
-# ═══════════════════════════════════════════════════════════
-
-def create_sales_dashboard(user_id: str | None = None) -> str:
-    """Create a sales dashboard widget, return its label."""
-    df = get_sales_data(user_id)
-    fig = px.bar(df, x="month", y="revenue", title="Sales Dashboard")
-
-    # open_browser=True forces InlineWidget which has .url for redirects
-    # With PYWRY_HEADLESS=1, open_in_browser() is automatically skipped
-    widget = show_plotly(
-        fig,
-        title="Sales Dashboard",
-        callbacks={"chart:export": handle_export},
-        open_browser=True,  # Forces InlineWidget for server deployments
-    )
-    return widget.label  # .label works on all widget types
-
-def create_inventory_view(warehouse_id: str | None = None) -> str:
-    """Create an inventory grid widget."""
-    df = get_inventory_data(warehouse_id)
-
-    widget = show_dataframe(
-        df,
-        title="Inventory",
-        callbacks={"grid:row-selected": handle_row_select},
-        open_browser=True,
-    )
-    return widget.label
-
-def create_analytics_dashboard() -> str:
-    """Create an analytics dashboard with multiple charts."""
-    widget = show(
-        generate_analytics_html(),
-        title="Analytics",
-        include_plotly=True,
-        callbacks={
-            "plotly:click": handle_chart_click,
-            "toolbar:refresh": refresh_analytics,
-        },
-        open_browser=True,
-    )
-    return widget.label
-
-# ═══════════════════════════════════════════════════════════
-# EVENT HANDLERS - Shared across all widget instances
-# Use runtime.emit_event(label, event, data) when widget reference unavailable
-# ═══════════════════════════════════════════════════════════
-
-def handle_export(data, event_type, label):
-    """Handle export request from any sales dashboard."""
-    # Use label to target the correct widget
-    from pywry import runtime
-    runtime.emit_event(label, "pywry:set-content", {"id": "status", "text": "Exporting..."})
-    # ... do export work ...
-    runtime.emit_event(label, "pywry:set-content", {"id": "status", "text": "Export complete!"})
-
-def handle_row_select(data, event_type, label):
-    """Handle row selection from any inventory grid."""
-    from pywry import runtime
-    selected = data.get("selected_rows", [])
-    runtime.emit_event(label, "pywry:set-content", {
-        "id": "selection-count",
-        "text": f"Selected {len(selected)} rows"
-    })
-
-def handle_chart_click(data, event_type, label):
-    """Handle chart click from any analytics dashboard."""
-    from pywry import runtime
-    point = data.get("points", [{}])[0]
-    runtime.emit_event(label, "pywry:set-content", {
-        "id": "click-info",
-        "text": f"Clicked: ({point.get('x')}, {point.get('y')})"
-    })
-
-def refresh_analytics(data, event_type, label):
-    """Refresh analytics for a specific widget."""
-    from pywry import runtime
-    runtime.emit_event(label, "pywry:set-content", {"id": "status", "text": "Refreshing..."})
-    # ... refresh logic ...
-    runtime.emit_event(label, "pywry:set-content", {"id": "status", "text": "Data refreshed!"})
-
-# ═══════════════════════════════════════════════════════════
-# FASTAPI ROUTES - Static URLs that redirect to dynamic widgets
-# ═══════════════════════════════════════════════════════════
-
-@app.get("/")
-async def index():
-    """Landing page with links to dashboards."""
-    return {
-        "dashboards": {
-            "sales": "/sales",
-            "inventory": "/inventory",
-            "analytics": "/analytics",
-        }
-    }
-
-@app.get("/sales")
-async def sales_dashboard(request: Request, user_id: str | None = None):
-    """Static route that creates a fresh sales dashboard."""
-    widget_id = create_sales_dashboard(user_id)
-    return RedirectResponse(f"/widget/{widget_id}")
-
-@app.get("/inventory")
-async def inventory_view(warehouse_id: str | None = None):
-    """Static route that creates a fresh inventory view."""
-    widget_id = create_inventory_view(warehouse_id)
-    return RedirectResponse(f"/widget/{widget_id}")
-
-@app.get("/analytics")
-async def analytics_dashboard():
-    """Static route that creates a fresh analytics dashboard."""
-    widget_id = create_analytics_dashboard()
-    return RedirectResponse(f"/widget/{widget_id}")
-
-# ═══════════════════════════════════════════════════════════
-# HELPER FUNCTIONS (replace with your data sources)
-# ═══════════════════════════════════════════════════════════
-
-def get_sales_data(user_id: str | None = None) -> pd.DataFrame:
-    return pd.DataFrame({
-        "month": ["Jan", "Feb", "Mar", "Apr"],
-        "revenue": [100, 150, 120, 180]
-    })
-
-def get_inventory_data(warehouse_id: str | None = None) -> pd.DataFrame:
-    return pd.DataFrame({
-        "sku": ["A001", "B002", "C003"],
-        "quantity": [50, 30, 100],
-        "location": ["Shelf 1", "Shelf 2", "Shelf 3"]
-    })
-
-def generate_analytics_html() -> str:
-    return "<h1>Analytics Dashboard</h1><div id='charts'></div>"
-
-if __name__ == "__main__":
-    import uvicorn
-    uvicorn.run(app, host="0.0.0.0", port=8080)
-```
-
-Run with:
-
-```bash
-python app.py
-# Or with uvicorn directly:
-# uvicorn app:app --host 0.0.0.0 --port 8080
-```
-
-Now users can access:
-- `http://yourserver:8080/sales` → Creates fresh widget, redirects to `/widget/{id}`
-- `http://yourserver:8080/inventory?warehouse_id=NYC` → Parameterized view
-- `http://yourserver:8080/analytics` → Analytics dashboard
-
-#### State Management Across Widgets
-
-Track widget instances and their state:
-
-```python
-from dataclasses import dataclass, field
-from datetime import datetime
-from typing import Any
-import threading
-from pywry import PyWry, WindowMode
-
-# Create a global app instance for browser mode
-app = PyWry(mode=WindowMode.BROWSER)
-
-@dataclass
-class WidgetSession:
-    """Track a widget instance and its state."""
-    widget_id: str
-    view_name: str
-    user_id: str | None
-    created_at: datetime
-    state: dict[str, Any] = field(default_factory=dict)
-
-class WidgetManager:
-    """Manage all active widget sessions."""
-
-    def __init__(self):
-        self._sessions: dict[str, WidgetSession] = {}
-        self._lock = threading.Lock()
-
-    def create(self, widget_id: str, view_name: str, user_id: str | None = None) -> WidgetSession:
-        session = WidgetSession(
-            widget_id=widget_id,
-            view_name=view_name,
-            user_id=user_id,
-            created_at=datetime.now(),
-        )
-        with self._lock:
-            self._sessions[widget_id] = session
-        return session
-
-    def get(self, widget_id: str) -> WidgetSession | None:
-        return self._sessions.get(widget_id)
-
-    def update_state(self, widget_id: str, key: str, value: Any) -> None:
-        session = self._sessions.get(widget_id)
-        if session:
-            session.state[key] = value
-
-    def remove(self, widget_id: str) -> None:
-        with self._lock:
-            self._sessions.pop(widget_id, None)
-
-    def get_by_user(self, user_id: str) -> list[WidgetSession]:
-        return [s for s in self._sessions.values() if s.user_id == user_id]
-
-# Global manager
-manager = WidgetManager()
-
-# Use in view factories
-def create_sales_dashboard(user_id: str | None = None) -> str:
-    widget = app.show_plotly(fig, title="Sales", open_browser=True)
-
-    # Track the session
-    manager.create(widget.label, "sales", user_id)
-
-    return widget.label
-
-# Use in event handlers
-def handle_filter_change(data, event_type, label):
-    """Update state and show feedback in the widget."""
-    from pywry import runtime
-
-    manager.update_state(label, "filters", data)
-    session = manager.get(label)
-
-    if session:
-        # Show visual feedback in the widget
-        runtime.emit_event(label, "pywry:set-content", {
-            "id": "filter-status",
-            "text": f"Filters updated for {session.user_id}"
-        })
-```
-
-#### Cleanup on Disconnect
-
-Register a disconnect callback to clean up sessions:
-
-```python
-from pywry import PyWry, WindowMode
-import plotly.express as px
-from datetime import datetime
-
-app = PyWry(mode=WindowMode.BROWSER)
-fig = px.scatter(px.data.iris(), x="sepal_width", y="sepal_length", color="species")
-
-def on_disconnect(data, event_type, label):
-    """Called when widget WebSocket disconnects - cleanup resources."""
-    session = manager.get(label)
-    if session:
-        manager.remove(label)
-
-def handle_click(data, event_type, label):
-    """Show clicked point info in the chart title."""
-    point = data.get("points", [{}])[0]
-    # In BROWSER mode, show_plotly returns a widget, but the callback
-    # receives the label parameter, so we can use app.emit()
-    app.emit("plotly:update-layout", {
-        "layout": {"title": f"Clicked: ({point.get('x')}, {point.get('y')})"}
-    }, label)
-
-widget = app.show_plotly(fig, callbacks={
-    "pywry:disconnect": on_disconnect,
-    "plotly:click": handle_click,
-})
-```
-
-### Simple Script Example
-
-For quick testing or simple scripts (not production):
-
-```python
-# simple.py - Quick script for local testing
-from pywry import PyWry, WindowMode
-from pywry.inline import block
-import plotly.express as px
-
-app = PyWry(mode=WindowMode.BROWSER)
-
-fig = px.scatter(px.data.iris(), x="sepal_width", y="sepal_length", color="species")
-widget = app.show_plotly(fig, title="Quick Test")
-
-print(f"Open: {widget.url}")
-block()  # Keep server running
-```
-
-```bash
-PYWRY_SERVER__HOST=0.0.0.0 python simple.py
-```
-
-### Programmatic URL Access
-
-```python
-from pywry import PyWry, WindowMode
-
-app = PyWry(mode=WindowMode.BROWSER)
-widget = app.show_plotly(fig)
-
-# Get the URL
-url = widget.url  # http://127.0.0.1:8765/widget/abc123
-
-# Open in system browser programmatically
-widget.open_in_browser()
-
-# Get widget ID (used in URL path)
-widget_id = widget.widget_id  # "abc123"
-
-# Construct URL manually if needed
-from pywry.config import get_settings
-settings = get_settings().server
-protocol = "https" if settings.ssl_certfile else "http"
-base_url = f"{protocol}://{settings.host}:{settings.port}"
-full_url = f"{base_url}/widget/{widget_id}"
-```
-
-### HTTPS Configuration
-
-For production deployments, enable SSL/TLS:
-
-```toml
-[server]
-host = "0.0.0.0"
-port = 443
-ssl_certfile = "/etc/letsencrypt/live/myapp.com/fullchain.pem"
-ssl_keyfile = "/etc/letsencrypt/live/myapp.com/privkey.pem"
-```
-
-The widget URL will automatically use `https://`:
-
-```python
-widget = app.show_plotly(fig)
-print(widget.url)  # https://0.0.0.0:443/widget/abc123
-```
-
-### Server Health Check
-
-The inline server exposes a `/health` endpoint:
-
-```bash
-curl http://localhost:8765/health
-# {"status": "ok"}
-```
-
-Use this for load balancer health checks or monitoring.
-
-> **Note:** The `/health` endpoint requires internal API authentication when accessed externally. Python code using `_make_server_request()` automatically includes the required header.
-
-### WebSocket & API Security
-
-PyWry implements a multi-layer security model for WebSocket connections and internal API endpoints.
-
-> **Security Defaults:** Per-widget token authentication and internal API protection are **enabled by default**. For production deployments, also configure HTTPS, restrict CORS origins, and consider using CSP `strict()` preset.
-
-#### Security Model Overview
-
-| Layer | Setting | Purpose |
-|-------|---------|---------|
-| **Origin Validation** | `websocket_allowed_origins` | Restrict which origins can connect via WebSocket |
-| **Per-Widget Tokens** | `websocket_require_token` | Each widget gets a unique token embedded in HTML |
-| **Internal API Auth** | `internal_api_header/token` | Protect internal endpoints from external access |
-| **Widget Auth Mode** | `strict_widget_auth` | Browser (strict) vs Notebook (lenient) security |
-
-#### Per-Widget Token Authentication
-
-Each widget instance generates a unique short-lived token that's embedded in its HTML:
-
-```python
-# Token flow (automatic, no user code needed):
-# 1. show_plotly() creates widget with unique ID
-# 2. Server generates token, stores in widget_tokens[id]
-# 3. Token embedded in HTML as window.PYWRY_TOKEN
-# 4. JavaScript sends token via Sec-WebSocket-Protocol header
-# 5. Server validates token on WebSocket upgrade
-```
-
-The token is passed during WebSocket handshake via the `Sec-WebSocket-Protocol` header, ensuring it's not exposed in URLs or browser history.
-
-#### Allowed Origins
-
-For deployments where widgets are embedded in iframes on external sites, configure allowed origins:
-
-```toml
-[server]
-# Allow specific origins (empty = allow any, rely on token auth only)
-websocket_allowed_origins = [
-    "http://localhost:8080",
-    "https://app.example.com",
-    "https://dashboard.mycompany.com"
-]
-```
-
-> **Note:** When a widget is embedded in an iframe, the **origin** is the embedding site, not the PyWry server. Configure origins based on where your widgets will be embedded.
-
-#### Internal API Protection
-
-Internal endpoints (`/health`, `/register_widget`, `/disconnect`) are protected from external access:
-
-```toml
-[server]
-internal_api_header = "X-PyWry-Token"  # Custom header name
-internal_api_token = "my-secret"       # Set explicitly, or leave empty for auto-generation
-```
-
-Requests without the correct header receive `404 Not Found` (not `401`/`403`), hiding endpoint existence from attackers.
-
-#### Strict vs Lenient Widget Auth
-
-The `strict_widget_auth` setting controls how the `/widget/{id}` endpoint is protected:
-
-| Mode | `strict_widget_auth` | Behavior | Use Case |
-|------|----------------------|----------|----------|
-| **Notebook** | `false` (default) | Only checks widget ID exists | Jupyter iframes (can't send headers) |
-| **Browser** | `true` | Requires internal API header | Standalone browser mode |
-
-```toml
-[server]
-# For Jupyter/notebook deployments (default)
-strict_widget_auth = false
-
-# For standalone browser deployments
-strict_widget_auth = true
-```
-
-#### Programmatic Configuration
-
-```python
-from pywry import PyWry, PyWrySettings, ServerSettings
-
-settings = PyWrySettings(
-    server=ServerSettings(
-        # WebSocket security
-        websocket_allowed_origins=["https://app.example.com"],
-        websocket_require_token=True,
-
-        # Internal API security
-        internal_api_header="X-MyApp-Token",
-        internal_api_token="my-secret-token",  # Or None for auto-gen
-
-        # Widget auth mode
-        strict_widget_auth=True,  # Browser mode
-    )
-)
-
-app = PyWry(settings=settings)
-```
-
-#### Security Configuration Reference
-
-| Setting | Type | Default | Description |
-|---------|------|---------|-------------|
-| `websocket_allowed_origins` | `list[str]` | `[]` | Origins allowed for WebSocket. Empty = any origin (token-only auth) |
-| `websocket_require_token` | `bool` | `true` | Require per-widget token via `Sec-WebSocket-Protocol` |
-| `internal_api_header` | `str` | `"X-PyWry-Token"` | Header name for internal API auth |
-| `internal_api_token` | `str \| None` | `None` | Internal API token. `None` = auto-generate on start |
-| `strict_widget_auth` | `bool` | `false` | `true` = require header for `/widget/{id}`, `false` = check ID exists |
-
-</details>
-
----
-
-## Deploy Mode & Scaling
-
-<details>
-<summary>Click to expand</summary>
-
-**In this section:** [Overview](#deploy-mode-overview) · [Enable Deploy Mode](#enabling-deploy-mode) · [State Backends](#state-backends) · [Redis Configuration](#redis-configuration) · [State Stores](#state-stores) · [Multi-Worker Architecture](#multi-worker-architecture) · [Authentication & Sessions](#authentication--sessions)
-
----
-
-For production deployments with multiple workers or horizontal scaling, PyWry provides a **deploy mode** that externalizes state to Redis. This enables running PyWry behind a load balancer with multiple Uvicorn workers while maintaining consistent widget state and event routing.
-
-### Deploy Mode Overview
-
-| Feature | Single Process (Default) | Deploy Mode (Redis) |
-|---------|--------------------------|---------------------|
-| **State Storage** | In-memory (dict) | Redis with TTL |
-| **Event Bus** | In-memory queue | Redis Pub/Sub |
-| **Connection Routing** | Local tracking | Redis with worker affinity |
-| **Session Management** | N/A | Redis with RBAC support |
-| **Horizontal Scaling** | ❌ | ✅ |
-| **Worker Crash Recovery** | ❌ | ✅ |
-
-### Enabling Deploy Mode
-
-Deploy mode is activated automatically when:
-
-1. `PYWRY_DEPLOY__STATE_BACKEND=redis` is set, OR
-2. `PYWRY_DEPLOY_MODE=1` is set explicitly
-
-```bash
-# Via environment variables (recommended for production)
-export PYWRY_DEPLOY__STATE_BACKEND=redis
-export PYWRY_DEPLOY__REDIS_URL=redis://localhost:6379/0
-
-# Run with multiple workers
-uvicorn app:app --host 0.0.0.0 --port 8080 --workers 4
-```
-
-### State Backends
-
-| Backend | Use Case | Configuration |
-|---------|----------|---------------|
-| `memory` | Single process, development | Default, no configuration needed |
-| `redis` | Multi-worker, production | Requires Redis server |
-
-### Redis Configuration
-
-Configure Redis connection via `pywry.toml`, `pyproject.toml`, or environment variables:
-
-```toml
-# pywry.toml or [tool.pywry.deploy] in pyproject.toml
-[deploy]
-state_backend = "redis"
-redis_url = "redis://localhost:6379/0"
-redis_prefix = "pywry"              # Key namespace
-redis_pool_size = 10                # Connection pool size per store
-
-# TTL settings (seconds)
-widget_ttl = 86400                  # Widget data TTL (24 hours)
-connection_ttl = 300                # WebSocket connection TTL (5 minutes)
-session_ttl = 86400                 # User session TTL (24 hours)
-
-# Worker identification
-worker_id = ""                      # Auto-generated if empty
-
-# Authentication (optional)
-auth_enabled = false
-auth_session_cookie = "pywry_session"
-auth_header = "Authorization"
-
-# RBAC (optional)
-default_roles = ["viewer"]
-admin_users = []
-```
-
-#### Environment Variables
-
-```bash
-# Core Redis settings
-export PYWRY_DEPLOY__STATE_BACKEND=redis
-export PYWRY_DEPLOY__REDIS_URL=redis://user:password@host:6379/0
-export PYWRY_DEPLOY__REDIS_PREFIX=myapp
-
-# TTL settings
-export PYWRY_DEPLOY__WIDGET_TTL=86400
-export PYWRY_DEPLOY__CONNECTION_TTL=300
-export PYWRY_DEPLOY__SESSION_TTL=86400
-
-# Worker ID (optional - auto-generated if not set)
-export PYWRY_DEPLOY__WORKER_ID=worker-1
-
-# Authentication
-export PYWRY_DEPLOY__AUTH_ENABLED=true
-export PYWRY_DEPLOY__AUTH_SESSION_COOKIE=pywry_session
-export PYWRY_DEPLOY__AUTH_HEADER=Authorization
-
-# RBAC
-export PYWRY_DEPLOY__DEFAULT_ROLES=viewer,editor
-export PYWRY_DEPLOY__ADMIN_USERS=admin@example.com,super@example.com
-```
-
-### State Stores
-
-Deploy mode provides four pluggable state stores:
-
-| Store | Interface | Purpose |
-|-------|-----------|---------|
-| `WidgetStore` | `get_widget_store()` | Widget HTML, tokens, metadata |
-| `EventBus` | `get_event_bus()` | Cross-worker event routing |
-| `ConnectionRouter` | `get_connection_router()` | WebSocket connection affinity |
-| `SessionStore` | `get_session_store()` | User sessions for RBAC |
-
-#### Using State Stores Programmatically
-
-```python
-from pywry.state import (
-    get_widget_store,
-    get_event_bus,
-    get_connection_router,
-    get_session_store,
-    is_deploy_mode,
-    get_worker_id,
-)
-
-# Check if deploy mode is active
-if is_deploy_mode():
-    print(f"Running in deploy mode, worker: {get_worker_id()}")
-
-# Access stores (automatically returns Redis or Memory implementation)
-widget_store = get_widget_store()
-event_bus = get_event_bus()
-connection_router = get_connection_router()
-session_store = get_session_store()
-
-# Example: Register a widget
-await widget_store.register(
-    widget_id="my-widget",
-    html="<h1>Hello</h1>",
-    token="secret-token",
-    owner_worker_id=get_worker_id(),
-    metadata={"title": "My Widget"},
-)
-
-# Example: Get widget data
-widget_data = await widget_store.get("my-widget")
-if widget_data:
-    print(f"Widget HTML: {widget_data.html[:50]}...")
-    print(f"Owner: {widget_data.owner_worker_id}")
-```
-
-#### State Store Interfaces
-
-<details>
-<summary><strong>WidgetStore Interface</strong></summary>
-
-```python
-class WidgetStore(Protocol):
-    """Store for widget HTML content and metadata."""
-
-    async def register(
-        self,
-        widget_id: str,
-        html: str,
-        token: str | None = None,
-        owner_worker_id: str | None = None,
-        metadata: dict[str, Any] | None = None,
-    ) -> None:
-        """Register a widget with its HTML content."""
-
-    async def get(self, widget_id: str) -> WidgetData | None:
-        """Get complete widget data."""
-
-    async def get_html(self, widget_id: str) -> str | None:
-        """Get widget HTML content."""
-
-    async def get_token(self, widget_id: str) -> str | None:
-        """Get widget authentication token."""
-
-    async def exists(self, widget_id: str) -> bool:
-        """Check if a widget exists."""
-
-    async def delete(self, widget_id: str) -> bool:
-        """Delete a widget."""
-
-    async def list_active(self) -> list[str]:
-        """List all active widget IDs."""
-
-    async def update_html(self, widget_id: str, html: str) -> bool:
-        """Update widget HTML content."""
-```
-
-</details>
-
-<details>
-<summary><strong>EventBus Interface</strong></summary>
-
-```python
-class EventBus(Protocol):
-    """Cross-worker event bus for widget events."""
-
-    async def publish(self, event: EventMessage) -> None:
-        """Publish an event to the bus."""
-
-    async def subscribe(self, widget_id: str) -> AsyncIterator[EventMessage]:
-        """Subscribe to events for a widget."""
-
-    async def publish_to_worker(
-        self,
-        worker_id: str,
-        event: EventMessage,
-    ) -> None:
-        """Publish an event to a specific worker."""
-```
-
-</details>
-
-<details>
-<summary><strong>ConnectionRouter Interface</strong></summary>
-
-```python
-class ConnectionRouter(Protocol):
-    """Route WebSocket connections to appropriate workers."""
-
-    async def register(self, connection: ConnectionInfo) -> None:
-        """Register a new WebSocket connection."""
-
-    async def get(self, widget_id: str) -> ConnectionInfo | None:
-        """Get connection info for a widget."""
-
-    async def heartbeat(self, widget_id: str) -> bool:
-        """Update connection heartbeat timestamp."""
-
-    async def remove(self, widget_id: str) -> bool:
-        """Remove a connection registration."""
-
-    async def get_worker_connections(self, worker_id: str) -> list[str]:
-        """Get all widget IDs connected to a worker."""
-```
-
-</details>
-
-<details>
-<summary><strong>SessionStore Interface</strong></summary>
-
-```python
-class SessionStore(Protocol):
-    """User session management for RBAC."""
-
-    async def create(
-        self,
-        user_id: str,
-        roles: list[str] | None = None,
-        metadata: dict[str, Any] | None = None,
-    ) -> UserSession:
-        """Create a new user session."""
-
-    async def get(self, session_id: str) -> UserSession | None:
-        """Get a session by ID."""
-
-    async def get_by_user(self, user_id: str) -> list[UserSession]:
-        """Get all sessions for a user."""
-
-    async def update_roles(self, session_id: str, roles: list[str]) -> bool:
-        """Update session roles."""
-
-    async def delete(self, session_id: str) -> bool:
-        """Delete a session."""
-
-    async def touch(self, session_id: str) -> bool:
-        """Refresh session TTL."""
-```
-
-</details>
-
-### Multi-Worker Architecture
-
-When running with multiple workers, PyWry uses the following architecture:
-
-```
-                    ┌─────────────────────────────┐
-                    │        Load Balancer        │
-                    └─────────────┬───────────────┘
-                                  │
-        ┌─────────────────────────┼─────────────────────────┐
-        │                         │                         │
-        ▼                         ▼                         ▼
-┌───────────────┐       ┌───────────────┐       ┌───────────────┐
-│   Worker 1    │       │   Worker 2    │       │   Worker 3    │
-│   (uvicorn)   │       │   (uvicorn)   │       │   (uvicorn)   │
-│               │       │               │       │               │
-│  Callbacks A  │       │  Callbacks B  │       │  Callbacks C  │
-│  WebSockets   │       │  WebSockets   │       │  WebSockets   │
-└───────┬───────┘       └───────┬───────┘       └───────┬───────┘
-        │                       │                       │
-        └───────────────────────┼───────────────────────┘
-                                │
-                    ┌───────────▼───────────┐
-                    │        Redis          │
-                    │                       │
-                    │  • Widget Store       │
-                    │  • Event Bus (Pub/Sub)│
-                    │  • Connection Router  │
-                    │  • Session Store      │
-                    └───────────────────────┘
-```
-
-**Key Concepts:**
-
-1. **Widget Store**: All workers can serve any widget's HTML since content is in Redis
-2. **Connection Router**: Tracks which worker owns each WebSocket connection
-3. **Event Bus**: Routes events to the correct worker for callback execution
-4. **Callbacks**: Python callbacks are executed by the worker that registered them
-
-### Authentication & Sessions
-
-When `auth_enabled=true`, PyWry provides session-based authentication:
-
-```python
-from pywry.state import get_session_store, UserSession
-
-session_store = get_session_store()
-
-# Create a session for a user
-session = await session_store.create(
-    user_id="user@example.com",
-    roles=["viewer", "editor"],
-    metadata={"display_name": "John Doe"},
-)
-
-# Session token can be set as a cookie or header
-# session.session_id = "abc123..."
-
-# Validate a session
-session = await session_store.get(session_id)
-if session and "admin" in session.roles:
-    # Allow admin action
-    pass
-
-# Refresh session TTL on activity
-await session_store.touch(session.session_id)
-```
-
-#### RBAC Configuration
-
-```toml
-[deploy]
-auth_enabled = true
-default_roles = ["viewer"]      # Roles for new users
-admin_users = [                 # Users with admin privileges
-    "admin@example.com",
-    "super@example.com"
-]
-```
-
-### DeploySettings Reference
-
-| Setting | Type | Default | Description |
-|---------|------|---------|-------------|
-| `state_backend` | `"memory"` \| `"redis"` | `"memory"` | State storage backend |
-| `redis_url` | `str` | `"redis://localhost:6379/0"` | Redis connection URL |
-| `redis_prefix` | `str` | `"pywry"` | Key prefix for Redis keys |
-| `redis_pool_size` | `int` | `10` | Connection pool size |
-| `widget_ttl` | `int` | `86400` | Widget data TTL (seconds) |
-| `connection_ttl` | `int` | `300` | Connection routing TTL (seconds) |
-| `session_ttl` | `int` | `86400` | User session TTL (seconds) |
-| `worker_id` | `str \| None` | `None` | Worker ID (auto-generated if None) |
-| `auth_enabled` | `bool` | `false` | Enable authentication |
-| `auth_session_cookie` | `str` | `"pywry_session"` | Session cookie name |
-| `auth_header` | `str` | `"Authorization"` | Auth header name |
-| `default_roles` | `list[str]` | `["viewer"]` | Default roles for new users |
-| `admin_users` | `list[str]` | `[]` | User IDs with admin privileges |
-
-</details>
-
----
-
-## CLI Commands
-
-<details>
-<summary>Click to expand</summary>
-
-PyWry provides a CLI for **configuration management only**. Entry point: `pywry`
-
-**In this section:** [Show Configuration](#show-configuration) · [Initialize Configuration](#initialize-configuration) · [Example: Show Sources](#example-show-sources)
-
-### Show Configuration
-
-```bash
-# Human-readable format
-pywry config --show
-
-# TOML format (for creating config files)
-pywry config --toml
-
-# Environment variable format
-pywry config --env
-
-# Show configuration file sources
-pywry config --sources
-
-# Write to file
-pywry config --toml --output pywry.toml
-```
-
-### Initialize Configuration
-
-```bash
-# Create pywry.toml with defaults
-pywry init
-
-# Overwrite existing file
-pywry init --force
-
-# Custom output path
-pywry init --path my-config.toml
-```
-
-### Example: Show Sources
-
-```bash
-$ pywry config --sources
-Configuration sources (in priority order):
-  1. Built-in defaults
-  2. ~/.config/pywry/config.toml (not found)
-  3. pyproject.toml [tool.pywry] (found)
-  4. ./pywry.toml (found)
-  5. Environment variables (PYWRY_*)
-```
-
-</details>
-
----
-
-## Debugging
-
-<details>
-<summary>Click to expand</summary>
-
-**In this section:** [Enable Debug Logging](#enable-debug-logging) · [Standard Python Logging](#standard-python-logging) · [Environment Variable](#environment-variable)
-
-### Enable Debug Logging
-
-```python
-import pywry.log
-
-# Enable verbose debug output for all pywry modules
-pywry.log.enable_debug()
-```
-
-### Standard Python Logging
-
-```python
-import logging
-
-# Enable debug for specific modules
-logging.getLogger("pywry").setLevel(logging.DEBUG)
-logging.getLogger("pywry.runtime").setLevel(logging.DEBUG)
-```
-
-### Environment Variable
-
-```bash
-export PYWRY_LOG__LEVEL=DEBUG
-```
-
-</details>
-
----
-
-## Building from Source
-
-<details>
-<summary>Click to expand</summary>
-
-**In this section:** [Prerequisites](#prerequisites) · [Setup](#setup) · [Run Tests](#run-tests) · [Lint and Format](#lint-and-format) · [Project Structure](#project-structure)
-
-### Prerequisites
-
-- Python 3.10+
-- Git
-
-### Setup
-
-```bash
-# Clone repository
-git clone https://github.com/OpenBB-finance/OpenBB.git
-cd pywry
-
-# Create virtual environment
-python -m venv venv
-source venv/bin/activate  # Linux/macOS
-venv\Scripts\activate     # Windows
-
-# Install in development mode
-pip install -e ".[dev]"
-```
-
-### Run Tests
-
-```bash
-# Run all tests
-pytest tests/ -v
-
-# Run with coverage
-pytest tests/ --cov=pywry --cov-report=html
-```
-
-### Lint and Format
-
-```bash
-# Check code style
-ruff check pywry/ tests/
-
-# Format code
-ruff format pywry/ tests/
-
-# Type checking
-mypy pywry/
-```
-
-### Project Structure
-
-```
-pywry/
-├── pywry/
-│   ├── __init__.py        # Public API exports (version: 2.0.0)
-│   ├── __main__.py        # PyTauri subprocess entry point
-│   ├── app.py             # Main PyWry class - user entry point
-│   ├── asset_loader.py    # CSS/JS file loading with caching
-│   ├── assets.py          # Bundled asset loading (Plotly.js, AgGrid, CSS)
-│   ├── callbacks.py       # Event callback registry (singleton)
-│   ├── cli.py             # CLI commands (pywry config, pywry init)
-│   ├── config.py          # Layered configuration system (pydantic-settings)
-│   ├── grid.py            # AgGrid Pydantic models (ColDef, GridOptions, etc.)
-│   ├── hot_reload.py      # Hot reload manager
-│   ├── inline.py          # FastAPI-based inline server + InlineWidget
-│   ├── log.py             # Logging utilities
-│   ├── models.py          # Pydantic models (HtmlContent, WindowConfig, ThemeMode, WindowMode)
-│   ├── notebook.py        # Notebook environment detection
-│   ├── plotly_config.py   # Plotly configuration models (PlotlyConfig, ModeBarButton, etc.)
-│   ├── runtime.py         # PyTauri subprocess management (stdin/stdout IPC)
-│   ├── scripts.py         # JavaScript bridge code injected into windows
-│   ├── state_mixins.py    # Widget state management mixins (GridStateMixin, PlotlyStateMixin, ToolbarStateMixin)
-│   ├── Tauri.toml         # Tauri configuration
-│   ├── templates.py       # HTML template builder with CSP, themes, scripts
-│   ├── toolbar.py         # Toolbar component models (Button, Select, etc.)
-│   ├── watcher.py         # File system watcher (watchdog-based)
-│   ├── widget.py          # anywidget-based widgets (PyWryWidget, PyWryPlotlyWidget, PyWryAgGridWidget)
-│   ├── widget_protocol.py # BaseWidget protocol and NativeWindowHandle class
-│   ├── capabilities/      # Tauri capability permissions
-│   │   └── default.toml   # Default permissions (core, dialog, fs)
-│   ├── commands/          # IPC command handlers
-│   │   ├── __init__.py
-│   │   └── window_commands.py
-│   ├── frontend/          # Frontend HTML and bundled assets
-│   │   ├── assets/        # Plotly.js, AgGrid, icons
-│   │   ├── src/           # main.js, aggrid-defaults.js, plotly-widget.js, plotly-templates.js
-│   │   └── style/         # CSS files (pywry.css)
-│   ├── state/             # State management for deploy mode
-│   │   ├── __init__.py    # Public state API exports
-│   │   ├── base.py        # Abstract interfaces (WidgetStore, EventBus, etc.)
-│   │   ├── memory.py      # In-memory implementations (default)
-│   │   ├── redis.py       # Redis implementations (deploy mode)
-│   │   ├── types.py       # Type definitions (WidgetData, EventMessage, etc.)
-│   │   ├── auth.py        # Authentication helpers
-│   │   ├── callbacks.py   # Callback registry for state
-│   │   ├── server.py      # Server state management
-│   │   ├── sync_helpers.py # Async-to-sync utilities
-│   │   └── _factory.py    # Factory functions for state stores
-│   ├── utils/             # Utility helpers
-│   │   ├── __init__.py
-│   │   └── async_helpers.py
-│   └── window_manager/    # Window mode implementations
-│       ├── __init__.py
-│       ├── controller.py      # WindowController
-│       ├── lifecycle.py       # WindowLifecycle with resource tracking
-│       └── modes/
-│           ├── __init__.py
-│           ├── base.py        # Abstract WindowModeBase interface
-│           ├── browser.py     # BROWSER mode - opens in system browser
-│           ├── new_window.py  # NEW_WINDOW mode
-│           ├── single_window.py # SINGLE_WINDOW mode
-│           └── multi_window.py  # MULTI_WINDOW mode
-├── tests/                 # Unit and E2E tests
-├── examples/              # Demo notebooks
-├── build_assets.py        # Asset download script
-├── build_widget.py        # Widget build script
-├── pyproject.toml         # Package configuration
-├── ruff.toml              # Ruff linting configuration
-├── pytest.ini             # Pytest configuration
-├── AGENTS.md              # AI coding agent guide
-└── README.md
-```
-
-</details>
-
----
-
-# Integrations
-
-## Plotly Integration
-
-<details>
-<summary>Click to expand</summary>
-
-PyWry bundles Plotly.js 3.3.1 for offline charting with full event integration. Display figures with `show_plotly()` and handle chart events in Python.
-
-**In this section:** [Basic Usage](#basic-usage) · [Plotly Templates](#plotly-templates) · [Theme Coordination](#theme-coordination) · [User Templates](#user-templates) · [JavaScript Access](#javascript-access) · [PlotlyConfig](#plotlyconfig) · [ModeBarButton](#modebarbutton) · [SvgIcon](#svgicon) · [PlotlyIconName](#plotlyiconname) · [Pre-built Buttons](#pre-built-buttons) · [StandardButton](#standardbutton) · [Accessing Plotly API](#accessing-plotly-api-javascript)
-
-### Basic Usage
-
-```python
-import plotly.graph_objects as go
-from pywry import PyWry
-
-app = PyWry()
-fig = go.Figure(data=[go.Scatter(x=[1, 2, 3], y=[4, 5, 6])])
-app.show_plotly(fig)
-```
-
-### Plotly Templates
-
-PyWry bundles all official Plotly templates for consistent theming with no network dependencies.
-
-| Template | Description |
-|----------|-------------|
-| `plotly` | Default Plotly theme |
-| `plotly_white` | Light theme with white background |
-| `plotly_dark` | Dark theme with dark background |
-| `ggplot2` | ggplot2 style |
-| `seaborn` | Seaborn style |
-| `simple_white` | Minimal white theme |
-| `presentation` | High contrast for presentations |
-| `xgridoff` | No vertical grid lines |
-| `ygridoff` | No horizontal grid lines |
-| `gridon` | Grid lines enabled |
-
-### Theme Coordination
-
-The window theme determines the default Plotly template when no template is specified:
-
-| Window Theme | Default Plotly Template |
-|--------------|-------------------------|
-| `ThemeMode.DARK` | `plotly_dark` |
-| `ThemeMode.LIGHT` | `plotly_white` |
-| `ThemeMode.SYSTEM` | Follows OS preference |
-
-### User Templates
-
-When you specify a template on your figure, **it is used exactly as-is**:
-
-```python
-import plotly.graph_objects as go
-from pywry import PyWry, ThemeMode
-
-pywry = PyWry(theme=ThemeMode.DARK)
-
-# Your template is used completely - seaborn's light backgrounds included
-fig = go.Figure(data=[...])
-fig.update_layout(template='seaborn')
-
-pywry.show_plotly(fig)  # Shows seaborn template exactly
-```
-
-PyWry does not modify or merge user templates. The window theme only affects charts without an explicit template.
-
-### JavaScript Access
-
-Templates are available in the browser via `window.PYWRY_PLOTLY_TEMPLATES`:
-
-```javascript
-// Access any template directly
-const darkTemplate = window.PYWRY_PLOTLY_TEMPLATES['plotly_dark'];
-
-// Apply to a chart
-Plotly.update('my-chart', {}, { template: darkTemplate });
-```
-
-### PlotlyConfig
-
-Top-level configuration object passed to `Plotly.newPlot()`. Controls responsiveness, interactivity, modebar behavior, and more.
-
-```python
-from pywry import PlotlyConfig, PlotlyIconName, ModeBarButton
-
-config = PlotlyConfig(
-    responsive=True,           # Resize with container (default: True)
-    display_mode_bar="hover",  # Show on hover (default), True, or False
-    display_logo=False,        # Hide Plotly logo
-    scroll_zoom=True,          # Enable scroll-to-zoom
-    double_click="reset",      # Reset on double-click ("reset+autosize", "reset", "autosize", False)
-    static_plot=False,         # Disable all interactivity
-    editable=False,            # Allow editing titles, annotations, etc.
-    mode_bar_buttons_to_remove=["lasso2d", "select2d"],  # Remove specific buttons
-    mode_bar_buttons_to_add=[...],  # Add custom buttons (see ModeBarButton)
-)
-
-# Pass to show_plotly
-app.show_plotly(fig, config=config)
-```
-
-### ModeBarButton
-
-Define custom buttons for the Plotly modebar. Buttons can emit PyWry events when clicked.
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `name` | `str` | Unique identifier for the button |
-| `title` | `str` | Tooltip text shown on hover |
-| `icon` | `SvgIcon \| PlotlyIconName \| str` | Button icon (built-in or custom SVG) |
-| `event` | `str \| None` | PyWry event to emit when clicked |
-| `data` | `dict \| None` | Additional data to include in event payload |
-| `toggle` | `bool \| None` | Whether button has toggle state |
-| `click` | `str \| None` | JavaScript handler (use `event` for PyWry events instead) |
-
-```python
-from pywry import PyWry, ModeBarButton, PlotlyConfig, PlotlyIconName
-import plotly.express as px
-import pandas as pd
-
-app = PyWry()
-
-# Sample data
-df = px.data.iris()
-fig = px.scatter(df, x="sepal_width", y="sepal_length", color="species")
-
-# Custom button that emits a PyWry event
-export_button = ModeBarButton(
-    name="exportData",
-    title="Export Data",
-    icon=PlotlyIconName.SAVE,
-    event="app:export",
-    data={"format": "csv"},
-)
-
-config = PlotlyConfig(
-    mode_bar_buttons_to_add=[export_button],
-)
-
-def on_export(data, event_type, label):
-    """Trigger a CSV download when the custom modebar button is clicked."""
-    csv_content = df.to_csv(index=False)
-    app.emit("pywry:download", {
-        "content": csv_content,
-        "filename": "iris_data.csv",
-        "mimeType": "text/csv"
-    }, label)
-
-handle = app.show_plotly(fig, config=config, callbacks={"app:export": on_export})
-```
-
-### SvgIcon
-
-Define custom SVG icons for modebar buttons.
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `width` | `int` | SVG viewBox width (default: 500) |
-| `height` | `int` | SVG viewBox height (default: 500) |
-| `path` | `str \| None` | SVG path `d` attribute |
-| `svg` | `str \| None` | Full SVG markup (alternative to `path`) |
-| `transform` | `str \| None` | SVG transform attribute |
-
-```python
-from pywry import SvgIcon, ModeBarButton
-
-# Custom icon using SVG path
-custom_icon = SvgIcon(
-    width=24,
-    height=24,
-    path="M12 2L2 7l10 5 10-5-10-5zM2 17l10 5 10-5M2 12l10 5 10-5",
-)
-
-button = ModeBarButton(
-    name="customAction",
-    title="Custom Action",
-    icon=custom_icon,
-    event="app:custom",
-)
-```
-
-### PlotlyIconName
-
-Enum of built-in Plotly icon names. Use these instead of custom SVGs when possible.
-
-```python
-from pywry import PlotlyIconName
-
-# Available icons
-PlotlyIconName.CAMERA_RETRO  # Download/screenshot
-PlotlyIconName.HOME          # Reset/home
-PlotlyIconName.ZOOM_IN       # Zoom in
-PlotlyIconName.ZOOM_OUT      # Zoom out
-PlotlyIconName.PAN           # Pan mode
-PlotlyIconName.LASSO         # Lasso select
-PlotlyIconName.SAVE          # Save
-PlotlyIconName.PENCIL        # Edit
-PlotlyIconName.ERASER        # Erase
-PlotlyIconName.UNDO          # Undo
-# ... and more (see PlotlyIconName enum)
-```
-
-### Pre-built Buttons
-
-PyWry includes convenience button classes:
-
-```python
-from pywry.plotly_config import DownloadImageButton, ResetAxesButton, ToggleGridButton
-
-config = PlotlyConfig(
-    mode_bar_buttons_to_add=[
-        DownloadImageButton(),
-        ResetAxesButton(),
-        ToggleGridButton(),  # Emits "plotly:toggle-grid" event
-    ],
-)
-```
-
-### StandardButton
-
-Enum of standard Plotly modebar button names. Use with `mode_bar_buttons_to_remove`:
-
-```python
-from pywry.plotly_config import StandardButton
-
-config = PlotlyConfig(
-    mode_bar_buttons_to_remove=[
-        StandardButton.LASSO_2D,
-        StandardButton.SELECT_2D,
-        StandardButton.TOGGLE_SPIKELINES,
-    ],
-)
-```
-
-### Accessing Plotly API (JavaScript)
-
-```javascript
-// Update chart layout
-Plotly.relayout(window.__PYWRY_PLOTLY_DIV__, { title: 'New Title' });
-
-// Update chart data
-Plotly.react(window.__PYWRY_PLOTLY_DIV__, newData, newLayout);
-
-// Apply template
-Plotly.update(window.__PYWRY_PLOTLY_DIV__, {}, {
-    template: window.PYWRY_PLOTLY_TEMPLATES['seaborn']
-});
-```
-
-</details>
-
-## AgGrid Integration
-
-<details>
-<summary>Click to expand</summary>
-
-PyWry bundles AgGrid 35.0.0 for high-performance data tables. Display DataFrames with `show_dataframe()` and handle grid events in Python.
-
-**In this section:** [Basic Usage](#basic-usage-1) · [Import Grid Models](#import-grid-models) · [Column Definitions](#column-definitions) · [ColDef Properties](#coldef-properties) · [Row Selection](#row-selection) · [Grid Options](#grid-options) · [Available Grid Models](#available-grid-models) · [Accessing AgGrid API](#accessing-aggrid-api-javascript)
-
-### Basic Usage
-
-```python
-import pandas as pd
-from pywry import PyWry
-
-app = PyWry()
-df = pd.DataFrame({"name": ["Alice", "Bob"], "age": [25, 30]})
-app.show_dataframe(df)
-```
-
-### Import Grid Models
-
-```python
-from pywry.grid import ColDef, ColGroupDef, DefaultColDef, RowSelection, GridOptions, build_grid_config
-```
-
-### Column Definitions
-
-Use `ColDef` to define individual columns with all common AgGrid options:
-
-```python
-from pywry import PyWry
-from pywry.grid import ColDef
-import pandas as pd
-
-app = PyWry()
-df = pd.DataFrame({"name": ["Alice", "Bob"], "age": [25, 30], "salary": [50000, 60000]})
-
-# Define custom column configurations
-column_defs = [
-    ColDef(field="name", header_name="Full Name", pinned="left", min_width=120),
-    ColDef(field="age", filter="agNumberColumnFilter", sortable=True),
-    ColDef(field="salary", value_formatter="'$' + value.toLocaleString()", flex=1),
-]
-
-app.show_dataframe(df, column_defs=column_defs)
-```
-
-### ColDef Properties
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `field` | `str` | Column field name (matches DataFrame column) |
-| `header_name` | `str` | Display name in header |
-| `hide` | `bool` | Whether column is hidden |
-| `pinned` | `"left"` \| `"right"` | Pin column to side |
-| `width`, `min_width`, `max_width` | `int` | Column sizing |
-| `flex` | `int` | Flex sizing weight |
-| `sortable` | `bool` | Enable sorting |
-| `filter` | `bool` \| `str` | Enable/specify filter type |
-| `resizable` | `bool` | Allow column resizing |
-| `editable` | `bool` | Allow cell editing |
-| `cell_data_type` | `str` | Data type hint (`"text"`, `"number"`, `"boolean"`, `"date"`) |
-| `value_formatter` | `str` | JS expression for formatting display value |
-| `cell_renderer` | `str` | Custom cell renderer name |
-| `cell_class` | `str` \| `list` | CSS class(es) for cells |
-| `cell_style` | `dict` | Inline styles for cells |
-
-### Row Selection
-
-Configure row selection behavior:
-
-```python
-from pywry.grid import RowSelection
-
-selection = RowSelection(
-    mode="multiRow",           # or "singleRow"
-    checkboxes=True,
-    header_checkbox=True,
-    enable_click_selection=True,
-)
-```
-
-### Grid Options
-
-For full control, use `GridOptions`:
-
-```python
-from pywry.grid import GridOptions, DefaultColDef
-
-grid_options = GridOptions(
-    pagination=True,
-    pagination_page_size=50,
-    animate_rows=True,
-    default_col_def=DefaultColDef(
-        sortable=True,
-        filter=True,
-        resizable=True,
-        min_width=80,
-    ).to_dict(),
-)
-
-app.show_dataframe(df, grid_options=grid_options.to_dict())
-```
-
-### Available Grid Models
-
-| Model | Purpose |
-|-------|---------|
-| `ColDef` | Column definition with all common options |
-| `ColGroupDef` | Column group for MultiIndex columns |
-| `DefaultColDef` | Default settings applied to all columns |
-| `RowSelection` | Row selection configuration |
-| `GridOptions` | Complete AgGrid configuration |
-| `GridConfig` | Combined AgGrid options + PyWry context |
-| `GridData` | Normalized grid data from various inputs |
-
-### Accessing AgGrid API (JavaScript)
-
-```javascript
-// Get selected rows
-const rows = window.__PYWRY_GRID_API__.getSelectedRows();
-
-// Update data
-window.__PYWRY_GRID_API__.setGridOption('rowData', newData);
-
-// Apply transactions
-window.__PYWRY_GRID_API__.applyTransaction({ update: [row1, row2] });
-
-// Export to CSV
-window.__PYWRY_GRID_API__.exportDataAsCsv();
-```
-
----
-
-## MCP Server (AI Agents)
-
-<details>
-<summary>Click to expand</summary>
-
-**In this section:** [Overview](#mcp-overview) · [Installation](#mcp-installation) · [Running the Server](#running-the-mcp-server) · [Configuration](#mcp-configuration) · [Available Tools](#available-mcp-tools) · [Skills System](#skills-system) · [Component Reference](#component-reference) · [Event Handling](#mcp-event-handling) · [Resources & Prompts](#resources--prompts)
-
----
-
-### MCP Overview
-
-PyWry includes a built-in [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that allows AI agents (Claude, GPT, etc.) to create and manipulate native desktop widgets programmatically.
-
-**What AI agents can do with PyWry MCP:**
-
-- Create native desktop windows with interactive toolbars
-- Build dynamic UIs with 17 Pydantic-based components
-- Display Plotly charts and AgGrid tables
-- Update content and styling in real-time
-- Capture user interactions via events
-- Export generated widgets as standalone Python code
-
-### MCP Installation
-
-Install PyWry with MCP support:
-
-```bash
-pip install 'pywry[mcp]'
-```
-
-This installs the `mcp` package and its dependencies.
-
-### Running the MCP Server
-
-**stdio transport** (default, for direct integration):
-
-```bash
-python -m pywry.mcp
-```
-
-**SSE transport** (for HTTP-based clients):
-
-```bash
-python -m pywry.mcp --transport sse --port 8001
-# or shorthand:
-python -m pywry.mcp --sse 8001
-```
-
-**CLI Options:**
-
-| Option | Default | Description |
-|--------|---------|-------------|
-| `--transport` | `stdio` | Transport type: `stdio` or `sse` |
-| `--port` | `8001` | Port for SSE transport |
-| `--sse [PORT]` | `8001` | Shorthand for `--transport sse --port PORT` |
-
-### MCP Configuration
-
-**VS Code / Cursor MCP Settings:**
-
-Add to your MCP settings (`.vscode/mcp.json` or global settings):
-
-```json
-{
-  "servers": {
-    "pywry": {
-      "command": "python",
-      "args": ["-m", "pywry.mcp"],
-      "env": {
-        "PYWRY_HEADLESS": "1"
-      }
-    }
-  }
-}
-```
-
-For SSE transport:
-
-```json
-{
-  "servers": {
-    "pywry": {
-      "url": "http://127.0.0.1:8001/sse"
-    }
-  }
-}
-```
-
-**Environment Variables:**
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `PYWRY_HEADLESS` | `0` | Set to `1` for inline/browser widget mode (recommended for MCP) |
-| `PYWRY_THEME` | `dark` | Default theme: `dark`, `light`, or `system` |
-
-### Available MCP Tools
-
-The MCP server exposes 25+ tools for widget creation and manipulation:
-
-#### Core Tools
-
-| Tool | Description |
-|------|-------------|
-| `get_skills` | Get context-specific guidance and documentation |
-| `create_widget` | Create a native window with HTML content and toolbars |
-| `list_widgets` | List all active widgets with their URLs |
-| `destroy_widget` | Close and clean up a widget |
-| `get_events` | Retrieve captured events from a widget |
-
-#### Widget Manipulation
-
-| Tool | Description |
-|------|-------------|
-| `set_content` | Update element text/HTML by component_id |
-| `set_style` | Update element CSS styles by component_id |
-| `show_toast` | Display a toast notification |
-| `inject_css` | Inject custom CSS into a widget |
-| `remove_css` | Remove injected CSS by style_id |
-| `navigate` | Navigate widget to a new URL |
-| `download` | Trigger a file download in the widget |
-| `send_event` | Send a custom event to a widget |
-| `update_theme` | Switch widget theme (dark/light/system) |
-
-#### Visualization Tools
-
-| Tool | Description |
-|------|-------------|
-| `show_plotly` | Create a Plotly chart widget from figure JSON |
-| `update_plotly` | Update an existing Plotly chart |
-| `show_dataframe` | Create an AgGrid table from JSON data |
-
-#### Marquee / Ticker Tools
-
-| Tool | Description |
-|------|-------------|
-| `update_marquee` | Update marquee content, speed, or state |
-| `update_ticker_item` | Update individual ticker items by ID |
-| `build_ticker_item` | Build ticker item HTML for use in marquees |
-
-#### Helper Tools
-
-| Tool | Description |
-|------|-------------|
-| `build_div` | Build a Div component HTML string |
-| `get_component_docs` | Get detailed documentation for a component |
-| `get_component_source` | Get Python source code for a component class |
-| `list_resources` | List all available resources and templates |
-| `export_widget` | Export a widget as standalone Python code |
-
-### Skills System
-
-The MCP server includes a skills system that provides context-appropriate guidance to AI agents. Skills are loaded on-demand to minimize memory usage.
-
-**Retrieving Skills:**
-
-```
-# List all available skills
-get_skills()
-
-# Get specific skill guidance
-get_skills(skill="component_reference")
-get_skills(skill="native")
-get_skills(skill="data_visualization")
-```
-
-**Available Skills:**
-
-| Skill ID | Description |
-|----------|-------------|
-| `component_reference` | **MANDATORY** - Complete reference for all 18 components and event signatures |
-| `interactive_buttons` | How to make buttons work automatically with auto-wired callbacks |
-| `native` | Desktop window mode with full OS control |
-| `jupyter` | Inline widgets in Jupyter notebook cells |
-| `iframe` | Embedded widgets in external web pages |
-| `deploy` | Production multi-user SSE server deployment |
-| `css_selectors` | Targeting elements for updates |
-| `styling` | Theme variables and CSS customization |
-| `data_visualization` | Charts, tables, and live data patterns |
-| `forms_and_inputs` | Building interactive forms with validation |
-
-### Component Reference
-
-The MCP server supports 17 toolbar component types:
-
-| Component | Description | Key Properties |
-|-----------|-------------|----------------|
-| `button` | Click button | `label`, `event`, `variant` |
-| `select` | Dropdown menu | `options`, `selected`, `event` |
-| `multiselect` | Multi-choice dropdown | `options`, `selected`, `event` |
-| `toggle` | On/off switch | `label`, `event`, `value` |
-| `checkbox` | Checkbox | `label`, `event`, `value` |
-| `radio` | Radio button group | `options`, `event` |
-| `tabs` | Tab bar | `options`, `event` |
-| `text` | Text input | `placeholder`, `event` |
-| `textarea` | Multi-line text | `rows`, `event` |
-| `search` | Search input with debounce | `debounce`, `event` |
-| `number` | Numeric input | `min`, `max`, `step`, `event` |
-| `date` | Date picker | `event` |
-| `slider` | Single value slider | `min`, `max`, `step`, `show_value`, `event` |
-| `range` | Two-handle range slider | `min`, `max`, `start`, `end`, `event` |
-| `div` | Container with content | `content`, `component_id`, `style` |
-| `secret` | Password input | `show_toggle`, `show_copy`, `event` |
-| `marquee` | Scrolling ticker | `text`, `speed`, `ticker_items` |
-
-**Button Variants:** `primary`, `neutral`, `danger`, `success`
-
-**Toolbar Positions:** `top`, `bottom`, `left`, `right`, `inside`
-
-### MCP Event Handling
-
-Events from widget interactions are captured and can be retrieved via `get_events`:
-
-```
-# Get events without clearing
-get_events(widget_id="abc123", clear=false)
-
-# Get and clear events
-get_events(widget_id="abc123", clear=true)
-```
-
-**Event Structure:**
-
-```json
-{
-  "events": [
-    {
-      "event_type": "button:click",
-      "data": {"componentId": "submit-btn"},
-      "label": "Submit"
-    },
-    {
-      "event_type": "slider:change",
-      "data": {"value": 75, "componentId": "volume"},
-      "label": "Volume"
-    }
-  ]
-}
-```
-
-**Auto-Wired Button Callbacks:**
-
-Button events following the pattern `elementId:action` are automatically wired:
-
-| Pattern | Action |
-|---------|--------|
-| `counter:increment` | Adds 1 to element with id="counter" |
-| `counter:decrement` | Subtracts 1 from element |
-| `counter:reset` | Sets element to 0 |
-| `status:toggle` | Toggles true/false |
-
-### Resources & Prompts
-
-The MCP server exposes resources and prompts for agent discovery:
-
-**Resource URIs:**
-
-| URI Pattern | Description |
-|-------------|-------------|
-| `pywry://component/{name}` | Component documentation (e.g., `pywry://component/button`) |
-| `pywry://source/{name}` | Component Python source code |
-| `pywry://skill/{name}` | Skill guidance markdown |
-| `pywry://docs/events` | Built-in events reference |
-| `pywry://docs/quickstart` | Quick start guide |
-| `pywry://export/{widget_id}` | Export widget as Python code |
-
-**Prompts:**
-
-All skills are also available as prompts prefixed with `skill:`:
-
-- `skill:component_reference`
-- `skill:native`
-- `skill:data_visualization`
-- etc.
-
-### Example: Creating a Counter Widget
-
-An AI agent would call:
-
-```json
-{
-  "tool": "create_widget",
-  "arguments": {
-    "html": "<div id=\"count\" style=\"font-size:72px;text-align:center;padding:50px\">0</div>",
-    "title": "Counter",
-    "height": 300,
-    "toolbars": [{
-      "position": "top",
-      "items": [
-        {"type": "button", "label": "+1", "event": "count:increment", "variant": "primary"},
-        {"type": "button", "label": "-1", "event": "count:decrement", "variant": "neutral"},
-        {"type": "button", "label": "Reset", "event": "count:reset", "variant": "danger"}
-      ]
-    }]
-  }
-}
-```
-
-The buttons auto-wire to increment, decrement, and reset the `<div id="count">` element.
-
-### Example: Stock Ticker with Live Updates
-
-```json
-{
-  "tool": "create_widget",
-  "arguments": {
-    "html": "<div id=\"main\" style=\"padding:20px\"><h1>Market Watch</h1></div>",
-    "title": "Stock Ticker",
-    "toolbars": [{
-      "position": "top",
-      "items": [{
-        "type": "marquee",
-        "component_id": "ticker",
-        "speed": 20,
-        "ticker_items": [
-          {"ticker": "AAPL", "text": "AAPL: $175.50", "style": "color: green"},
-          {"ticker": "GOOG", "text": "GOOG: $140.25", "style": "color: red"},
-          {"ticker": "MSFT", "text": "MSFT: $380.00", "style": "color: green"}
-        ]
-      }]
-    }]
-  }
-}
-```
-
-Update individual tickers:
-
-```json
-{
-  "tool": "update_ticker_item",
-  "arguments": {
-    "widget_id": "abc123",
-    "ticker": "AAPL",
-    "text": "AAPL: $178.25 ↑",
-    "styles": {"color": "green", "fontWeight": "bold"}
-  }
-}
-```
-
-### Programmatic Usage
-
-You can also use the MCP server programmatically in Python:
-
-```python
-from pywry.mcp import create_server, run_server
-
-# Create server instance
-server = create_server(name="my-pywry-server")
-
-# Run with SSE transport
-run_server(transport="sse", port=8001, host="127.0.0.1")
-```
-
-</details>
-
-For full AgGrid API reference, see: https://www.ag-grid.com/javascript-data-grid/grid-options/
-
-</details>
-
----
+Apache 2.0 — see [LICENSE](LICENSE) for details.
diff --git a/pywry/docs/docs/guides/state-and-auth.md b/pywry/docs/docs/guides/state-and-auth.md
index 0a4a05f..c081503 100644
--- a/pywry/docs/docs/guides/state-and-auth.md
+++ b/pywry/docs/docs/guides/state-and-auth.md
@@ -384,7 +384,9 @@ All Redis store constructors accept a `redis_client` parameter for dependency in
 
 ## Next Steps
 
+- **[OAuth2 Authentication](oauth2.md)** — Add Google, GitHub, Microsoft, or custom OIDC login flows
 - **[Deploy Mode](deploy-mode.md)** — Running PyWry behind a production server
 - **[Configuration](configuration.md)** — Full settings reference
 - **[Event System](events.md)** — How events flow across rendering paths
 - **[API Reference: State](../reference/state.md)** — Full state API docs
+- **[API Reference: OAuth2](../reference/auth.md)** — Full OAuth2 API docs
diff --git a/pywry/docs/docs/stylesheets/extra.css b/pywry/docs/docs/stylesheets/extra.css
index 99530dd..a319e21 100644
--- a/pywry/docs/docs/stylesheets/extra.css
+++ b/pywry/docs/docs/stylesheets/extra.css
@@ -572,7 +572,7 @@
 .pywry-docs-hero__subtitle {
   font-size: 1rem;
   color: var(--pywry-text-muted);
-  max-width: 540px;
+  max-width: 680px;
   margin: 0 auto 1.5rem;
   line-height: 1.55;
 }
diff --git a/pywry/examples/pywry_demo_multi_widget.py b/pywry/examples/pywry_demo_multi_widget.py
new file mode 100644
index 0000000..5cfc895
--- /dev/null
+++ b/pywry/examples/pywry_demo_multi_widget.py
@@ -0,0 +1,471 @@
+"""PyWry Multi-Widget Demo — Plotly + AG Grid + Toolbar in one window.
+
+Demonstrates combining a Plotly chart, AG Grid table, KPI cards, and a
+detail panel in a single ``app.show()`` call.  Every piece uses the
+library's built-in integrations — ``build_plotly_init_script``,
+``build_grid_html``, toolbars, and the bidirectional event system.
+
+Cross-widget interactions (no inline JS required):
+  • Select grid rows  →  chart redraws showing only selected products
+  • Click a chart bar  →  detail panel shows that product's breakdown
+  • Toolbar chart-type selector  →  live chart type switch
+  • Export button  →  CSV download via ``pywry:download``
+
+Works from all rendering paths (native window, notebook, iframe, browser).
+"""
+
+import json
+
+import pandas as pd
+import plotly.graph_objects as go
+
+from pywry import (
+    Button,
+    HtmlContent,
+    Option,
+    PyWry,
+    Select,
+    ThemeMode,
+    Toolbar,
+)
+from pywry.grid import build_grid_config, build_grid_html
+from pywry.templates import build_plotly_init_script
+
+
+# ---------------------------------------------------------------------------
+# Sample data
+# ---------------------------------------------------------------------------
+
+SALES = pd.DataFrame(
+    {
+        "Product": ["Widget A", "Widget B", "Widget C", "Widget D", "Widget E"],
+        "Q1": [12_000, 18_000, 7_500, 22_000, 9_500],
+        "Q2": [14_500, 16_000, 11_000, 19_000, 13_000],
+        "Q3": [16_000, 21_000, 9_000, 25_000, 11_500],
+        "Q4": [19_000, 17_500, 13_500, 28_000, 15_000],
+    }
+)
+
+QUARTERS = ["Q1", "Q2", "Q3", "Q4"]
+
+# Pre-compute per-product totals for the KPI and detail panels
+PRODUCT_TOTALS = {row["Product"]: sum(row[q] for q in QUARTERS) for _, row in SALES.iterrows()}
+GRAND_TOTAL = sum(PRODUCT_TOTALS.values())
+BEST_PRODUCT = max(PRODUCT_TOTALS, key=PRODUCT_TOTALS.get)
+BEST_QUARTER = max(QUARTERS, key=lambda q: int(SALES[q].sum()))
+AVG_PER_PRODUCT = GRAND_TOTAL // len(SALES)
+
+# ---------------------------------------------------------------------------
+# Plotly figure builder
+# ---------------------------------------------------------------------------
+
+# Current chart type — mutated by the toolbar callback
+_chart_type = "bar"
+
+
+def make_figure(
+    chart_type: str = "bar",
+    products: list[str] | None = None,
+) -> go.Figure:
+    """Build a Plotly figure, optionally limited to *products*."""
+    df = SALES if products is None else SALES[SALES["Product"].isin(products)]
+    fig = go.Figure()
+    for q in QUARTERS:
+        trace_cls = go.Bar if chart_type == "bar" else go.Scatter
+        kwargs: dict = {"x": df["Product"], "y": df[q], "name": q}
+        if chart_type == "line":
+            kwargs["mode"] = "lines+markers"
+        fig.add_trace(trace_cls(**kwargs))
+    fig.update_layout(
+        title="Quarterly Sales by Product",
+        xaxis_title="Product",
+        yaxis_title="Revenue ($)",
+        barmode="group" if chart_type == "bar" else None,
+        margin={"l": 60, "r": 20, "t": 50, "b": 40},
+        legend={"orientation": "h", "y": -0.18},
+        template="plotly_dark",
+    )
+    fig_dict = json.loads(fig.to_json())
+    fig_dict["config"] = {"displayModeBar": False}
+
+    return fig_dict
+
+
+# ---------------------------------------------------------------------------
+# Dashboard CSS — uses PyWry theme variables so it auto-matches
+# ---------------------------------------------------------------------------
+
+DASHBOARD_CSS = """
+.dashboard {
+    display: flex;
+    flex-direction: column;
+    height: 100%;
+    gap: 8px;
+    padding: 10px;
+    overflow-y: auto;
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+}
+
+/* ---- KPI row ---- */
+.kpi-row {
+    display: flex;
+    gap: 8px;
+    flex-shrink: 0;
+}
+.kpi-card {
+    flex: 1;
+    background: var(--pywry-bg-tertiary);
+    border: 1px solid var(--pywry-border-color);
+    border-radius: 6px;
+    padding: 12px 14px;
+    display: flex;
+    flex-direction: column;
+    gap: 2px;
+}
+.kpi-label {
+    font-size: 11px;
+    text-transform: uppercase;
+    letter-spacing: 0.5px;
+    color: var(--pywry-text-secondary);
+}
+.kpi-value {
+    font-size: 22px;
+    font-weight: 600;
+    color: var(--pywry-text-primary);
+}
+
+/* ---- Main content row (chart + grid side-by-side) ---- */
+.content-row {
+    display: flex;
+    gap: 8px;
+    flex: 1;
+    min-height: 0;
+}
+.panel {
+    background: var(--pywry-bg-tertiary);
+    border: 1px solid var(--pywry-border-color);
+    border-radius: 6px;
+    overflow: hidden;
+    display: flex;
+    flex-direction: column;
+}
+.panel-header {
+    padding: 8px 12px;
+    font-size: 12px;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.4px;
+    color: var(--pywry-text-secondary);
+    border-bottom: 1px solid var(--pywry-border-color);
+    flex-shrink: 0;
+}
+.panel-body {
+    flex: 1;
+    min-height: 0;
+    position: relative;
+}
+.chart-panel { flex: 55; }
+.grid-panel  { flex: 45; }
+
+/* Plotly container fills its panel */
+.chart-panel .panel-body {
+    padding: 6px 8px;
+}
+.chart-panel .panel-body .pywry-plotly {
+    width: 100% !important;
+    height: 100% !important;
+}
+
+/* Grid container fills its panel */
+.grid-panel .panel-body {
+    display: flex;
+    flex-direction: column;
+    padding: 6px 8px;
+}
+.grid-panel .panel-body .pywry-grid {
+    flex: 1;
+}
+
+/* ---- Detail panel ---- */
+.detail-panel {
+    flex-shrink: 0;
+    min-height: 60px;
+}
+.detail-body {
+    padding: 10px 14px;
+    display: flex;
+    gap: 20px;
+    align-items: center;
+    color: var(--pywry-text-secondary);
+    font-size: 13px;
+}
+.detail-body .detail-product {
+    font-size: 15px;
+    font-weight: 600;
+    color: var(--pywry-text-primary);
+    min-width: 90px;
+}
+.detail-body .detail-metric {
+    display: flex;
+    flex-direction: column;
+    gap: 1px;
+}
+.detail-body .detail-metric .metric-label {
+    font-size: 10px;
+    text-transform: uppercase;
+    color: var(--pywry-text-muted);
+}
+.detail-body .detail-metric .metric-value {
+    font-size: 14px;
+    font-weight: 500;
+    color: var(--pywry-text-primary);
+}
+"""
+
+# ---------------------------------------------------------------------------
+# Build the HTML snippets via library integrations
+# ---------------------------------------------------------------------------
+
+chart_html = build_plotly_init_script(
+    figure=make_figure("bar"),
+    chart_id="sales-chart",
+)
+
+grid_config = build_grid_config(
+    SALES,
+    grid_id="sales-grid",
+    row_selection=True,
+)
+grid_html = build_grid_html(grid_config)
+
+
+def _fmt(n: int) -> str:
+    """Format an integer with $ and comma grouping."""
+    return f"${n:,}"
+
+
+DETAIL_PLACEHOLDER = (
+    '<span style="color:var(--pywry-text-muted)">'
+    "Click a chart bar to see product details, "
+    "or select grid rows to filter the chart."
+    "</span>"
+)
+
+dashboard_html = f"""
+<div class="dashboard">
+    <!-- KPI cards -->
+    <div class="kpi-row">
+        <div class="kpi-card">
+            <span class="kpi-label">Total Revenue</span>
+            <span class="kpi-value">{_fmt(GRAND_TOTAL)}</span>
+        </div>
+        <div class="kpi-card">
+            <span class="kpi-label">Best Product</span>
+            <span class="kpi-value">{BEST_PRODUCT}</span>
+        </div>
+        <div class="kpi-card">
+            <span class="kpi-label">Best Quarter</span>
+            <span class="kpi-value">{BEST_QUARTER}</span>
+        </div>
+        <div class="kpi-card">
+            <span class="kpi-label">Avg / Product</span>
+            <span class="kpi-value">{_fmt(AVG_PER_PRODUCT)}</span>
+        </div>
+    </div>
+
+    <!-- Chart + Grid side-by-side -->
+    <div class="content-row">
+        <div class="panel chart-panel">
+            <div class="panel-header">Revenue Chart</div>
+            <div class="panel-body">{chart_html}</div>
+        </div>
+        <div class="panel grid-panel">
+            <div class="panel-header">Sales Data</div>
+            <div class="panel-body">{grid_html}</div>
+        </div>
+    </div>
+
+    <!-- Detail panel -->
+    <div class="panel detail-panel">
+        <div class="panel-header">Details</div>
+        <div class="detail-body" id="detail-content">{DETAIL_PLACEHOLDER}</div>
+    </div>
+</div>
+"""
+
+# ---------------------------------------------------------------------------
+# Toolbar
+# ---------------------------------------------------------------------------
+
+toolbar = Toolbar(
+    position="top",
+    items=[
+        Select(
+            label="Chart Type:",
+            event="app:chart-type",
+            options=[
+                Option(label="Bar", value="bar"),
+                Option(label="Line", value="line"),
+            ],
+            selected="bar",
+        ),
+        Button(label="Export CSV", event="app:export", variant="secondary"),
+        Button(label="Clear Selection", event="app:clear", variant="ghost"),
+    ],
+)
+
+# ---------------------------------------------------------------------------
+# App + callbacks
+# ---------------------------------------------------------------------------
+
+app = PyWry(title="Multi-Widget Demo", theme=ThemeMode.DARK, width=1400, height=780)
+widget = None  # assigned after show()
+
+# Track the current selection so chart-type changes preserve it
+_selected_products: list[str] = []
+
+
+def _push_figure(products: list[str] | None = None) -> None:
+    """Rebuild the chart figure and send it to the frontend."""
+    fig = make_figure(_chart_type, products or None)
+    widget.emit(
+        "plotly:update-figure",
+        {"figure": fig, "chartId": "sales-chart"},
+    )
+
+
+def _push_detail_for_product(name: str) -> None:
+    """Update the detail panel with a single product's quarterly breakdown."""
+    row = SALES[SALES["Product"] == name].iloc[0]
+    total = sum(int(row[q]) for q in QUARTERS)
+    best_q = max(QUARTERS, key=lambda q: int(row[q]))
+    metrics = "".join(
+        f'<div class="detail-metric">'
+        f'<span class="metric-label">{q}</span>'
+        f'<span class="metric-value">{_fmt(int(row[q]))}</span>'
+        f"</div>"
+        for q in QUARTERS
+    )
+    html = (
+        f'<span class="detail-product">{name}</span>'
+        f"{metrics}"
+        f'<div class="detail-metric">'
+        f'<span class="metric-label">Total</span>'
+        f'<span class="metric-value">{_fmt(total)}</span>'
+        f"</div>"
+        f'<div class="detail-metric">'
+        f'<span class="metric-label">Best Qtr</span>'
+        f'<span class="metric-value">{best_q}</span>'
+        f"</div>"
+    )
+    widget.emit("pywry:set-content", {"id": "detail-content", "html": html})
+
+
+def _push_detail_for_selection(products: list[str]) -> None:
+    """Update the detail panel with aggregated stats for selected products."""
+    if not products:
+        widget.emit(
+            "pywry:set-content",
+            {"id": "detail-content", "html": DETAIL_PLACEHOLDER},
+        )
+        return
+    if len(products) == 1:
+        _push_detail_for_product(products[0])
+        return
+    subset = SALES[SALES["Product"].isin(products)]
+    total = sum(int(subset[q].sum()) for q in QUARTERS)
+    metrics = "".join(
+        f'<div class="detail-metric">'
+        f'<span class="metric-label">{q}</span>'
+        f'<span class="metric-value">{_fmt(int(subset[q].sum()))}</span>'
+        f"</div>"
+        for q in QUARTERS
+    )
+    html = (
+        f'<span class="detail-product">{len(products)} selected</span>'
+        f"{metrics}"
+        f'<div class="detail-metric">'
+        f'<span class="metric-label">Total</span>'
+        f'<span class="metric-value">{_fmt(total)}</span>'
+        f"</div>"
+    )
+    widget.emit("pywry:set-content", {"id": "detail-content", "html": html})
+
+
+# --- Event handlers -------------------------------------------------------
+
+
+def on_chart_click(data, _event_type, _label):
+    """Click a chart data point → show that product's breakdown in detail panel."""
+    points = data.get("points", [])
+    if points:
+        product = points[0].get("x")
+        if product:
+            _push_detail_for_product(product)
+
+
+def on_row_selected(data, _event_type, _label):
+    """Grid row selection → filter chart to selected products + update detail."""
+    global _selected_products  # noqa: PLW0603
+    rows = data.get("rows", [])
+    _selected_products = [r["Product"] for r in rows if "Product" in r]
+    _push_figure(_selected_products or None)
+    _push_detail_for_selection(_selected_products)
+
+
+def on_chart_type(data, _event_type, _label):
+    """Toolbar chart-type selector → redraw chart (preserving row selection)."""
+    global _chart_type  # noqa: PLW0603
+    _chart_type = data.get("value", "bar")
+    _push_figure(_selected_products or None)
+
+
+def on_export(_data, _event_type, _label):
+    """Toolbar export → CSV download via the event system."""
+    widget.emit(
+        "pywry:download",
+        {
+            "content": SALES.to_csv(index=False),
+            "filename": "sales_data.csv",
+            "mimeType": "text/csv",
+        },
+    )
+
+
+def on_clear(_data, _event_type, _label):
+    """Toolbar clear → reset chart, deselect grid rows, clear detail."""
+    global _selected_products  # noqa: PLW0603
+    _selected_products = []
+    _push_figure()
+    # Re-set the same data to clear AG Grid's row selection state
+    widget.emit(
+        "grid:update-data",
+        {"data": SALES.to_dict("records"), "gridId": "sales-grid"},
+    )
+    widget.emit(
+        "pywry:set-content",
+        {"id": "detail-content", "html": DETAIL_PLACEHOLDER},
+    )
+
+
+# ---------------------------------------------------------------------------
+# Show everything in one window
+# ---------------------------------------------------------------------------
+
+content = HtmlContent(html=dashboard_html, inline_css=DASHBOARD_CSS)
+
+widget = app.show(
+    content,
+    include_plotly=True,
+    include_aggrid=True,
+    toolbars=[toolbar],
+    callbacks={
+        "plotly:click": on_chart_click,
+        "grid:row-selected": on_row_selected,
+        "app:chart-type": on_chart_type,
+        "app:export": on_export,
+        "app:clear": on_clear,
+    },
+)
+
+app.block()
diff --git a/pywry/examples/pywry_demo_oauth2.py b/pywry/examples/pywry_demo_oauth2.py
new file mode 100644
index 0000000..b7ad113
--- /dev/null
+++ b/pywry/examples/pywry_demo_oauth2.py
@@ -0,0 +1,340 @@
+"""Demo: Google OAuth2 Sign-In with PyWry.
+
+Demonstrates the documented auth patterns:
+
+- ``GoogleProvider`` for explicit provider configuration
+- ``HtmlContent`` for structured content (html / css / init_script)
+- ``app.login(provider=provider)`` as the core auth API
+- ``app.logout()`` for session teardown
+
+Setup
+-----
+1. Create a Google OAuth2 client at https://console.cloud.google.com/apis/credentials
+2. Set the authorized redirect URI to ``http://127.0.0.1:0/callback``
+   (for native / loopback flows any port is matched).
+3. Export the credentials::
+
+       # PowerShell
+       $env:PYWRY_OAUTH2__CLIENT_ID = "your-client-id.apps.googleusercontent.com"
+       $env:PYWRY_OAUTH2__CLIENT_SECRET = "your-client-secret"
+
+       # Bash
+       export PYWRY_OAUTH2__CLIENT_ID="your-client-id.apps.googleusercontent.com"
+       export PYWRY_OAUTH2__CLIENT_SECRET="your-client-secret"
+
+4. Run::
+
+       python examples/pywry_demo_oauth2.py
+"""
+
+from __future__ import annotations
+
+import html as html_mod
+import os
+import sys
+import threading
+
+from typing import Any
+
+from pywry import HtmlContent, PyWry, WindowMode
+from pywry.auth import GoogleProvider
+
+
+# ───────────────────────────────────────────────────────────
+# Provider setup (documented pattern)
+# ───────────────────────────────────────────────────────────
+
+CLIENT_ID = os.environ.get(
+    "PYWRY_OAUTH2__CLIENT_ID",
+    "***.apps.googleusercontent.com",
+)
+CLIENT_SECRET = os.environ.get("PYWRY_OAUTH2__CLIENT_SECRET", "GOCSPX-your-client-secret")
+
+if not CLIENT_ID or "your-client-id" in CLIENT_ID:
+    print(
+        "\n"
+        "╔══════════════════════════════════════════════════════════════╗\n"
+        "║  ERROR: Real Google OAuth2 credentials are required.         ║\n"
+        "╚══════════════════════════════════════════════════════════════╝\n"
+        "\n"
+        "  1. Go to https://console.cloud.google.com/apis/credentials\n"
+        "  2. Create an OAuth 2.0 Client ID (type: Desktop app)\n"
+        "  3. Set the env vars:\n"
+        "\n"
+        "     PowerShell:\n"
+        '       $env:PYWRY_OAUTH2__CLIENT_ID = "YOUR_REAL_ID.apps.googleusercontent.com"\n'
+        '       $env:PYWRY_OAUTH2__CLIENT_SECRET = "GOCSPX-your-real-secret"\n'
+        "\n"
+        "     Then run:  python examples/pywry_demo_oauth2.py\n"
+    )
+    sys.exit(1)
+
+
+provider = GoogleProvider(client_id=CLIENT_ID, client_secret=CLIENT_SECRET)
+
+
+# ───────────────────────────────────────────────────────────
+# Login page
+# ───────────────────────────────────────────────────────────
+
+LOGIN_CSS = """\
+* { margin: 0; padding: 0; box-sizing: border-box; }
+body, html { height: 100%; }
+#login-root {
+    height: 100vh; display: flex; align-items: center; justify-content: center;
+    background: linear-gradient(135deg, #0f0c29, #302b63, #24243e);
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+    color: #e0e0e0;
+}
+.login-card {
+    background: rgba(255,255,255,0.06); backdrop-filter: blur(12px);
+    border: 1px solid rgba(255,255,255,0.12); border-radius: 16px;
+    padding: 3rem 2.5rem; text-align: center; width: 380px;
+    box-shadow: 0 8px 32px rgba(0,0,0,0.3);
+}
+.logo { font-size: 3rem; margin-bottom: 0.5rem; }
+h1 { font-size: 1.6rem; margin-bottom: 0.25rem; font-weight: 600; }
+.subtitle { color: #aaa; margin-bottom: 2rem; }
+.btn-google {
+    display: inline-flex; align-items: center; justify-content: center;
+    width: 100%; padding: 0.75rem 1.5rem;
+    background: #fff; color: #444; border: none; border-radius: 8px;
+    font-size: 1rem; font-weight: 500; cursor: pointer;
+    transition: box-shadow 0.2s, transform 0.1s;
+}
+.btn-google:hover { box-shadow: 0 2px 12px rgba(66,133,244,0.4); transform: translateY(-1px); }
+.btn-google:active { transform: translateY(0); }
+.btn-google:disabled { opacity: 0.6; cursor: default; transform: none; box-shadow: none; }
+.hint { margin-top: 1.5rem; font-size: 0.75rem; color: #777; }
+code {
+    background: rgba(255,255,255,0.1); padding: 2px 5px;
+    border-radius: 4px; font-size: 0.7rem;
+}
+"""
+
+LOGIN_HTML = """\
+<div id="login-root">
+  <div class="login-card">
+    <div class="logo">🔐</div>
+    <h1>Welcome to PyWry</h1>
+    <p class="subtitle">Sign in to continue</p>
+    <button id="btn-google" class="btn-google">
+      <svg width="18" height="18" viewBox="0 0 48 48" style="margin-right:10px;">
+        <path fill="#EA4335"
+          d="M24 9.5c3.54 0 6.71 1.22 9.21 3.6l6.85-6.85C35.9 2.38 30.47 0 24 0
+             14.62 0 6.51 5.38 2.56 13.22l7.98 6.19C12.43 13.72 17.74 9.5 24 9.5z"/>
+        <path fill="#4285F4"
+          d="M46.98 24.55c0-1.57-.14-3.09-.41-4.55H24v9.02h12.94
+             c-.58 2.96-2.26 5.48-4.78 7.18l7.73 6
+             c4.51-4.18 7.09-10.36 7.09-17.65z"/>
+        <path fill="#FBBC05"
+          d="M10.53 28.59a14.5 14.5 0 0 1 0-9.18l-7.98-6.19
+             a24.07 24.07 0 0 0 0 21.56l7.98-6.19z"/>
+        <path fill="#34A853"
+          d="M24 48c6.48 0 11.93-2.13 15.89-5.81l-7.73-6
+             c-2.15 1.45-4.92 2.3-8.16 2.3-6.26 0-11.57-4.22-13.47-9.91
+             l-7.98 6.19C6.51 42.62 14.62 48 24 48z"/>
+      </svg>
+      Sign in with Google
+    </button>
+    <p class="hint">
+      Requires <code>PYWRY_OAUTH2__CLIENT_ID</code> and
+      <code>PYWRY_OAUTH2__CLIENT_SECRET</code> env vars.
+    </p>
+  </div>
+</div>
+"""
+
+LOGIN_INIT_SCRIPT = """\
+document.getElementById("btn-google").addEventListener("click", function() {
+    this.textContent = "Signing in\\u2026";
+    this.disabled = true;
+    window.pywry.emit("auth:login", {});
+});
+"""
+
+LOGIN_CONTENT = HtmlContent(
+    html=LOGIN_HTML,
+    inline_css=LOGIN_CSS,
+    init_script=LOGIN_INIT_SCRIPT,
+)
+
+# ── Home page ─────────────────────────────────────────────
+
+HOME_CSS = """\
+* { margin: 0; padding: 0; box-sizing: border-box; }
+body, html { height: 100%; }
+#home-root {
+    min-height: 100vh;
+    background: linear-gradient(160deg, #0f0c29, #1a1a3e);
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+    color: #e0e0e0;
+}
+nav {
+    display: flex; align-items: center; justify-content: space-between;
+    padding: 0.75rem 1.5rem;
+    background: rgba(255,255,255,0.05);
+    border-bottom: 1px solid rgba(255,255,255,0.08);
+}
+.brand { font-weight: 700; font-size: 1.1rem; color: #8b5cf6; }
+.nav-user { display: flex; align-items: center; gap: 0.6rem; }
+.avatar { width: 32px; height: 32px; border-radius: 50%; }
+.avatar-placeholder {
+    width: 32px; height: 32px; border-radius: 50%;
+    background: rgba(255,255,255,0.1); display: flex;
+    align-items: center; justify-content: center; font-size: 1.1rem;
+}
+.nav-name { font-size: 0.85rem; }
+.btn-logout {
+    background: transparent; border: 1px solid rgba(255,255,255,0.2);
+    color: #ccc; padding: 0.3rem 0.8rem; border-radius: 6px;
+    font-size: 0.8rem; cursor: pointer; transition: background 0.2s;
+}
+.btn-logout:hover { background: rgba(255,255,255,0.1); }
+main { max-width: 800px; margin: 0 auto; padding: 3rem 1.5rem; }
+.hero { text-align: center; margin-bottom: 3rem; }
+.hero h1 { font-size: 2rem; margin-bottom: 0.3rem; }
+.email { color: #8b5cf6; margin-bottom: 0.5rem; }
+.tagline { color: #888; }
+.cards {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
+    gap: 1.2rem;
+}
+.card {
+    background: rgba(255,255,255,0.05);
+    border: 1px solid rgba(255,255,255,0.08);
+    border-radius: 12px; padding: 1.5rem;
+}
+.card h3 { margin-bottom: 0.5rem; font-size: 1rem; }
+.card p { font-size: 0.85rem; color: #aaa; line-height: 1.5; }
+code {
+    background: rgba(255,255,255,0.1); padding: 2px 5px;
+    border-radius: 4px; font-size: 0.8rem;
+}
+"""
+
+HOME_INIT_SCRIPT = """\
+document.getElementById("btn-logout").addEventListener("click", function() {
+    window.pywry.emit("auth:do-logout", {});
+});
+"""
+
+
+def build_home_content(user_info: dict[str, Any]) -> HtmlContent:
+    """Build an ``HtmlContent`` for the authenticated home screen."""
+    name = html_mod.escape(
+        str(user_info.get("name") or user_info.get("login") or user_info.get("email") or "User")
+    )
+    email = html_mod.escape(str(user_info.get("email", "")))
+    picture = user_info.get("picture", "")
+
+    avatar = (
+        f'<img class="avatar" src="{html_mod.escape(picture)}" alt="avatar" />'
+        if picture
+        else '<div class="avatar-placeholder">👤</div>'
+    )
+
+    home_html = f"""\
+<div id="home-root">
+  <nav>
+    <span class="brand">PyWry</span>
+    <div class="nav-user">
+      {avatar}
+      <span class="nav-name">{name}</span>
+      <button id="btn-logout" class="btn-logout">Sign out</button>
+    </div>
+  </nav>
+
+  <main>
+    <div class="hero">
+      <h1>Welcome, {name}!</h1>
+      <p class="email">{email}</p>
+      <p class="tagline">You are signed in via Google OAuth2.</p>
+    </div>
+
+    <section class="cards">
+      <div class="card">
+        <h3>🔒 Authenticated</h3>
+        <p>Your session is active with PKCE-protected tokens stored in memory.</p>
+      </div>
+      <div class="card">
+        <h3>🔄 Auto-Refresh</h3>
+        <p>Tokens are refreshed automatically before they expire.</p>
+      </div>
+      <div class="card">
+        <h3>🚀 Ready to Build</h3>
+        <p>Add <code>show_plotly()</code>, <code>show_dataframe()</code>,
+           or any HTML widget here.</p>
+      </div>
+    </section>
+  </main>
+</div>
+"""
+    return HtmlContent(html=home_html, inline_css=HOME_CSS, init_script=HOME_INIT_SCRIPT)
+
+
+# ───────────────────────────────────────────────────────────
+# App & callbacks
+# ───────────────────────────────────────────────────────────
+
+app = PyWry(
+    mode=WindowMode.SINGLE_WINDOW,
+    title="PyWry - Sign In",
+    width=460,
+    height=560,
+)
+
+
+def on_login(_data: dict[str, Any], _event_type: str, _label: str) -> None:
+    """Handle *Sign in with Google* button click.
+
+    The blocking OAuth2 flow runs in a background thread so the IPC
+    reader thread stays free to process ``set_content`` commands.
+    """
+
+    def _do_login() -> None:
+        try:
+            # Documented pattern:  result = app.login(provider=provider)
+            result = app.login(provider=provider)
+            if result.success:
+                user_info = result.user_info or {}
+                app.show(
+                    build_home_content(user_info),
+                    title=f"PyWry - {user_info.get('name', 'Home')}",
+                    width=900,
+                    height=640,
+                    callbacks={"auth:do-logout": on_logout},
+                )
+        except Exception as exc:
+            print(f"Authentication failed: {exc}")
+            app.show(
+                LOGIN_CONTENT,
+                title="PyWry - Sign In",
+                callbacks={"auth:login": on_login},
+            )
+
+    threading.Thread(target=_do_login, daemon=True).start()
+
+
+def on_logout(_data: dict[str, Any], _event_type: str, _label: str) -> None:
+    """Sign out: clear tokens and return to login."""
+    app.logout()
+    app.show(
+        LOGIN_CONTENT,
+        title="PyWry - Sign In",
+        width=460,
+        height=560,
+        callbacks={"auth:login": on_login},
+    )
+
+
+# ── Launch ────────────────────────────────────────────────
+
+app.show(
+    LOGIN_CONTENT,
+    title="PyWry - Sign In",
+    callbacks={"auth:login": on_login},
+)
+
+app.block()
diff --git a/pywry/pyproject.toml b/pywry/pyproject.toml
index 3428eea..c3ffb60 100644
--- a/pywry/pyproject.toml
+++ b/pywry/pyproject.toml
@@ -27,6 +27,7 @@ keywords = ["rendering", "frontend", "webview", "tauri", "gui", "plotly", "aggri
 dependencies = [
     "pytauri>=0.8.0",
     "anyio>=4.0.0",
+    "httpx>=0.27.0",
     "pandas>=1.5.3",
     "pydantic>=2.0.0",
     "pydantic-settings>=2.0.0",
@@ -66,10 +67,15 @@ notebook = [
 mcp = [
     "fastmcp>=2.14.5,<3",
 ]
+auth = [
+    "keyring>=24.0",
+    "authlib>=1.3.0",
+]
 all = [
     "anywidget>=0.9.0",
     "fastmcp>=2.14.5,<3",
     "ipykernel>=7.2.0",
+    "keyring>=24.0",
 ]
 
 [project.urls]
diff --git a/pywry/pytest.ini b/pywry/pytest.ini
index 4ba01e3..6ffff9b 100644
--- a/pywry/pytest.ini
+++ b/pywry/pytest.ini
@@ -5,7 +5,6 @@ python_classes = Test*
 python_functions = test_*
 addopts = -v --tb=short
 asyncio_mode = auto
-asyncio_default_fixture_loop_scope = function
 markers =
     e2e: End-to-end tests that require actual window creation
     redis: marks tests requiring Redis
diff --git a/pywry/pywry/__main__.py b/pywry/pywry/__main__.py
index 11724cc..3b1aced 100644
--- a/pywry/pywry/__main__.py
+++ b/pywry/pywry/__main__.py
@@ -8,6 +8,7 @@
 # flake8: noqa: N806
 
 import sys
+import typing
 
 
 # Set process and thread title for Activity Monitor/Task Manager visibility
@@ -29,7 +30,7 @@
         from ctypes import Structure, byref, c_uint32, cdll
 
         class _ProcessSerialNumber(Structure):
-            _fields_ = [("highLongOfPSN", c_uint32), ("lowLongOfPSN", c_uint32)]
+            _fields_: typing.ClassVar = [("highLongOfPSN", c_uint32), ("lowLongOfPSN", c_uint32)]
 
         _Carbon = cdll.LoadLibrary("/System/Library/Frameworks/Carbon.framework/Carbon")
         _psn = _ProcessSerialNumber()
@@ -42,6 +43,7 @@ class _ProcessSerialNumber(Structure):
 import io
 import json
 import os
+import signal
 import threading
 
 from contextlib import suppress
@@ -839,6 +841,12 @@ def _handle_close_requested(ipc: JsonIPC, app_handle: Any, label: str, window_ev
 
 def main() -> int:  # pylint: disable=too-many-statements
     """Run the PyWry subprocess."""
+    # Ignore SIGINT in the subprocess.  The parent process handles Ctrl-C
+    # and sends a "quit" IPC command for a clean shutdown.  Without this,
+    # SIGINT raises KeyboardInterrupt inside the Rust/PyO3 on_run callback
+    # which causes a panic in pytauri-core.
+    signal.signal(signal.SIGINT, signal.SIG_IGN)
+
     from .commands import register_commands
 
     log(f"Starting subprocess... (headless={HEADLESS})")
diff --git a/pywry/pywry/app.py b/pywry/pywry/app.py
index 8a842cf..5bd16b4 100644
--- a/pywry/pywry/app.py
+++ b/pywry/pywry/app.py
@@ -4,6 +4,7 @@
 
 from __future__ import annotations
 
+import contextlib
 import json
 import uuid
 
@@ -142,6 +143,10 @@ def __init__(
         self._aggrid_js: str | None = None
         self._aggrid_css: dict[tuple[str, ThemeMode], str] = {}
 
+        # Auth state
+        self._auth_result: Any = None  # AuthFlowResult | None
+        self._session_manager: Any = None  # SessionManager | None
+
         info(f"PyWry initialized with {mode.value} mode")
 
     def _create_mode(self, mode: WindowMode) -> WindowModeBase:
@@ -236,6 +241,126 @@ def _setup_hot_reload_watching(
 
         debug(f"Hot reload enabled for window {target_label}")
 
+    # ── Auth API ──────────────────────────────────────────────────────
+
+    @property
+    def is_authenticated(self) -> bool:
+        """Check if the app has a successful authentication result."""
+        return self._auth_result is not None and getattr(self._auth_result, "success", False)
+
+    def login(
+        self,
+        provider: Any | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        """Authenticate via OAuth2.
+
+        In native mode, opens a dedicated auth window pointing at the
+        provider's authorize URL. Blocks until authentication completes.
+
+        In deploy mode, returns the login URL for the frontend.
+
+        Parameters
+        ----------
+        provider : OAuthProvider, optional
+            Override the default provider from settings.
+        **kwargs : Any
+            Additional keyword arguments passed to ``AuthFlowManager.run_native()``.
+
+        Returns
+        -------
+        AuthFlowResult
+            The result of the authentication flow.
+
+        Raises
+        ------
+        AuthenticationError
+            If authentication fails.
+        """
+        from .auth.flow import AuthFlowManager
+        from .auth.providers import OAuthProvider, create_provider_from_settings
+        from .auth.session import SessionManager
+        from .auth.token_store import get_token_store
+
+        # Resolve provider
+        if provider is None:
+            oauth2_settings = self._settings.oauth2
+            if oauth2_settings is None:
+                # Try to instantiate from env vars as a fallback
+                from .config import OAuth2Settings
+
+                try:
+                    oauth2_settings = OAuth2Settings()
+                except Exception:
+                    oauth2_settings = None
+                if oauth2_settings is None or not oauth2_settings.client_id:
+                    from .exceptions import AuthenticationError
+
+                    msg = (
+                        "No OAuth2 settings configured. "
+                        "Set PYWRY_OAUTH2__CLIENT_ID and PYWRY_OAUTH2__PROVIDER, "
+                        "or pass a provider instance."
+                    )
+                    raise AuthenticationError(msg)
+                # Cache the auto-detected settings
+                self._settings.oauth2 = oauth2_settings
+            provider = create_provider_from_settings(oauth2_settings)
+        elif not isinstance(provider, OAuthProvider):
+            # Assume it's settings-like
+            provider = create_provider_from_settings(provider)
+
+        oauth2_settings = self._settings.oauth2
+        use_pkce = getattr(oauth2_settings, "use_pkce", True) if oauth2_settings else True
+        auth_timeout = (
+            getattr(oauth2_settings, "auth_timeout_seconds", 120.0) if oauth2_settings else 120.0
+        )
+        token_backend = (
+            getattr(oauth2_settings, "token_store_backend", "memory")
+            if oauth2_settings
+            else "memory"
+        )
+        refresh_buffer = (
+            getattr(oauth2_settings, "refresh_buffer_seconds", 60) if oauth2_settings else 60
+        )
+
+        # Create token store
+        token_store = get_token_store(backend=token_backend)
+
+        # Create session manager
+        self._session_manager = SessionManager(
+            provider=provider,
+            token_store=token_store,
+            refresh_buffer_seconds=refresh_buffer,
+        )
+
+        # Create flow manager
+        flow_manager = AuthFlowManager(
+            provider=provider,
+            token_store=token_store,
+            session_manager=self._session_manager,
+            use_pkce=use_pkce,
+            auth_timeout=auth_timeout,
+        )
+
+        # Run the flow
+        result = flow_manager.authenticate(app=self, **kwargs)
+
+        self._auth_result = result
+        return result
+
+    def logout(self) -> None:
+        """Log out and clear authentication state.
+
+        Clears stored tokens and cancels any background refresh.
+        """
+        if self._session_manager is not None:
+            from .state.sync_helpers import run_async
+
+            with contextlib.suppress(Exception):
+                run_async(self._session_manager.logout())
+            self._session_manager = None
+        self._auth_result = None
+
     # pylint: disable=too-many-arguments
     def show(
         self,
diff --git a/pywry/pywry/auth/__init__.py b/pywry/pywry/auth/__init__.py
new file mode 100644
index 0000000..a8ee6ee
--- /dev/null
+++ b/pywry/pywry/auth/__init__.py
@@ -0,0 +1,44 @@
+"""OAuth2 authentication system for PyWry.
+
+Provides OAuth2 provider abstractions, token storage, session management,
+and auth flow orchestration for both native window and deploy modes.
+"""
+
+from __future__ import annotations
+
+from .flow import AuthFlowManager
+from .pkce import PKCEChallenge
+from .providers import (
+    GenericOIDCProvider,
+    GitHubProvider,
+    GoogleProvider,
+    MicrosoftProvider,
+    OAuthProvider,
+    create_provider_from_settings,
+)
+from .session import SessionManager
+from .token_store import (
+    MemoryTokenStore,
+    RedisTokenStore,
+    TokenStore,
+    get_token_store,
+    reset_token_store,
+)
+
+
+__all__ = [
+    "AuthFlowManager",
+    "GenericOIDCProvider",
+    "GitHubProvider",
+    "GoogleProvider",
+    "MemoryTokenStore",
+    "MicrosoftProvider",
+    "OAuthProvider",
+    "PKCEChallenge",
+    "RedisTokenStore",
+    "SessionManager",
+    "TokenStore",
+    "create_provider_from_settings",
+    "get_token_store",
+    "reset_token_store",
+]
diff --git a/pywry/pywry/auth/callback_server.py b/pywry/pywry/auth/callback_server.py
new file mode 100644
index 0000000..c73a632
--- /dev/null
+++ b/pywry/pywry/auth/callback_server.py
@@ -0,0 +1,219 @@
+"""Ephemeral localhost HTTP server for OAuth2 redirect capture.
+
+Used in native window mode to intercept the OAuth2 callback
+on a randomly assigned port. Serves a success/error HTML page
+and extracts authorization code + state from query parameters.
+
+Uses only stdlib (http.server, threading, urllib.parse) — zero
+additional dependencies.
+"""
+
+# pylint: disable=logging-too-many-args
+
+# pylint: disable=C0103,W0212
+
+from __future__ import annotations
+
+import html
+import logging
+import threading
+
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from typing import Any
+from urllib.parse import parse_qs, urlparse
+
+
+logger = logging.getLogger("pywry.auth")
+
+_SUCCESS_HTML = """<!DOCTYPE html>
+<html>
+<head><title>Authentication Complete</title>
+<style>
+  body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+         display: flex; align-items: center; justify-content: center;
+         height: 100vh; margin: 0; background: #f0f2f5; color: #1a1a2e; }
+  .card { text-align: center; padding: 2rem 3rem; background: white;
+          border-radius: 12px; box-shadow: 0 2px 12px rgba(0,0,0,.08); }
+  h1 { font-size: 1.5rem; margin-bottom: 0.5rem; }
+  p { color: #666; }
+</style></head>
+<body><div class="card">
+  <h1>&#x2705; Authentication Complete</h1>
+  <p>You can close this window.</p>
+</div></body></html>"""
+
+_ERROR_HTML = """<!DOCTYPE html>
+<html>
+<head><title>Authentication Error</title>
+<style>
+  body {{ font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+         display: flex; align-items: center; justify-content: center;
+         height: 100vh; margin: 0; background: #f0f2f5; color: #1a1a2e; }}
+  .card {{ text-align: center; padding: 2rem 3rem; background: white;
+          border-radius: 12px; box-shadow: 0 2px 12px rgba(0,0,0,.08); }}
+  h1 {{ font-size: 1.5rem; margin-bottom: 0.5rem; color: #cc0000; }}
+  p {{ color: #666; }}
+</style></head>
+<body><div class="card">
+  <h1>&#x274C; Authentication Failed</h1>
+  <p>{error}</p>
+</div></body></html>"""
+
+_WAITING_HTML = """<!DOCTYPE html>
+<html>
+<head><title>Waiting for Authentication</title>
+<style>
+  body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+         display: flex; align-items: center; justify-content: center;
+         height: 100vh; margin: 0; background: #f0f2f5; color: #1a1a2e; }
+  .card { text-align: center; padding: 2rem 3rem; background: white;
+          border-radius: 12px; box-shadow: 0 2px 12px rgba(0,0,0,.08); }
+</style></head>
+<body><div class="card">
+  <h1>Waiting for authentication&hellip;</h1>
+  <p>Please complete the login in the browser window.</p>
+</div></body></html>"""
+
+
+class OAuthCallbackServer:
+    """Ephemeral localhost HTTP server for capturing OAuth2 redirects.
+
+    Parameters
+    ----------
+    host : str
+        Bind address (default ``"127.0.0.1"``).
+    port : int
+        Port number (``0`` for auto-assign).
+    """
+
+    def __init__(self, host: str = "127.0.0.1", port: int = 0) -> None:
+        """Initialize the callback server."""
+        self._host = host
+        self._port = port
+        self._server: HTTPServer | None = None
+        self._thread: threading.Thread | None = None
+        self._result: dict[str, Any] | None = None
+        self._result_event = threading.Event()
+        self._actual_port: int = 0
+
+    @property
+    def redirect_uri(self) -> str:
+        """Get the redirect URI for this callback server.
+
+        Returns
+        -------
+        str
+            The full redirect URI (e.g. ``http://127.0.0.1:54321/callback``).
+        """
+        return f"http://{self._host}:{self._actual_port}/callback"
+
+    def start(self) -> str:
+        """Start the callback server on a daemon thread.
+
+        Returns
+        -------
+        str
+            The redirect URI to use with the OAuth2 provider.
+        """
+        server_ref = self
+
+        class _CallbackHandler(BaseHTTPRequestHandler):
+            """HTTP request handler for OAuth2 callbacks."""
+
+            def do_GET(self) -> None:
+                """Handle GET requests."""
+                parsed = urlparse(self.path)
+
+                if parsed.path == "/callback":
+                    params = parse_qs(parsed.query)
+                    result: dict[str, Any] = {
+                        "code": params.get("code", [None])[0],
+                        "state": params.get("state", [None])[0],
+                        "error": params.get("error", [None])[0],
+                        "error_description": params.get("error_description", [None])[0],
+                    }
+
+                    # Only capture the first callback
+                    if not server_ref._result_event.is_set():
+                        server_ref._result = result
+
+                        if result.get("error"):
+                            error_msg = result.get("error_description") or result["error"]
+                            safe_msg = html.escape(str(error_msg), quote=True)
+                            error_html = _ERROR_HTML.format(error=safe_msg)
+                            self._send_html(error_html)
+                        else:
+                            self._send_html(_SUCCESS_HTML)
+
+                        server_ref._result_event.set()
+                        # Schedule shutdown on a background thread to avoid deadlock
+                        threading.Thread(target=self._shutdown_server, daemon=True).start()
+                    else:
+                        self._send_html(_SUCCESS_HTML)
+
+                elif parsed.path == "/":
+                    self._send_html(_WAITING_HTML)
+                else:
+                    self.send_error(404)
+
+            def _send_html(self, html_content: str) -> None:
+                """Send an HTML response with security headers."""
+                encoded = html_content.encode("utf-8")
+                self.send_response(200)
+                self.send_header("Content-Type", "text/html; charset=utf-8")
+                self.send_header("Content-Length", str(len(encoded)))
+                self.send_header("Cache-Control", "no-store")
+                self.send_header(
+                    "Content-Security-Policy",
+                    "default-src 'none'; style-src 'unsafe-inline'",
+                )
+                self.send_header("X-Content-Type-Options", "nosniff")
+                self.end_headers()
+                self.wfile.write(encoded)
+
+            def _shutdown_server(self) -> None:
+                """Shut down the HTTP server."""
+                if server_ref._server:
+                    server_ref._server.shutdown()
+
+            def log_message(self, *args: Any) -> None:
+                """Redirect HTTP server logging to the pywry logger."""
+                if args:
+                    logger.debug("OAuth callback server: %s", args[0] % args[1:])
+
+        self._server = HTTPServer((self._host, self._port), _CallbackHandler)
+        self._actual_port = self._server.server_address[1]
+
+        self._thread = threading.Thread(target=self._server.serve_forever, daemon=True)
+        self._thread.start()
+
+        logger.debug("OAuth callback server started on %s", self.redirect_uri)
+        return self.redirect_uri
+
+    def wait_for_callback(self, timeout: float = 120.0) -> dict[str, Any] | None:
+        """Block until the callback is received or timeout expires.
+
+        Parameters
+        ----------
+        timeout : float
+            Maximum seconds to wait (default 120).
+
+        Returns
+        -------
+        dict or None
+            Callback parameters (``code``, ``state``, ``error``, ``error_description``)
+            or ``None`` if timeout expired.
+        """
+        received = self._result_event.wait(timeout=timeout)
+        if received:
+            return self._result
+        return None
+
+    def stop(self) -> None:
+        """Force-shutdown the callback server."""
+        if self._server:
+            self._server.shutdown()
+        if self._thread and self._thread.is_alive():
+            self._thread.join(timeout=5)
+        self._server = None
+        self._thread = None
diff --git a/pywry/pywry/auth/deploy_routes.py b/pywry/pywry/auth/deploy_routes.py
new file mode 100644
index 0000000..995fae5
--- /dev/null
+++ b/pywry/pywry/auth/deploy_routes.py
@@ -0,0 +1,590 @@
+"""FastAPI routes for OAuth2 authentication in deploy mode.
+
+Provides login, callback, refresh, logout, userinfo, and status
+endpoints that integrate with the existing session store and auth middleware.
+"""
+
+# pylint: disable=logging-too-many-args,too-many-statements
+
+from __future__ import annotations
+
+import asyncio
+import collections
+import contextlib
+import logging
+import secrets
+import threading
+import time
+
+from typing import TYPE_CHECKING, Any
+
+from fastapi import APIRouter, Request, Response
+from fastapi.responses import JSONResponse, RedirectResponse
+
+from ..state.auth import AuthConfig, generate_session_token
+from ..state.types import UserSession
+from .pkce import PKCEChallenge
+
+
+if TYPE_CHECKING:
+    from ..config import DeploySettings
+    from ..state.base import SessionStore
+    from .providers import OAuthProvider
+    from .token_store import TokenStore
+
+
+logger = logging.getLogger("pywry.auth")
+
+
+# ── CSRF Origin Verification ────────────────────────────────────────
+
+
+def _verify_csrf_origin(request: Request, *, trusted_origins: list[str] | None = None) -> bool:
+    """Verify that POST requests originate from a trusted origin.
+
+    Checks the ``Origin`` header first, then falls back to ``Referer``.
+    Returns ``True`` if the origin is trusted, ``False`` otherwise.
+
+    Parameters
+    ----------
+    request : Request
+        The incoming request.
+    trusted_origins : list[str] | None
+        Allowed origins (e.g. ``["https://myapp.example.com"]``).
+        If ``None`` or empty, allows same-origin requests only.
+    """
+    origin = request.headers.get("origin")
+    referer = request.headers.get("referer")
+
+    # Determine the source origin
+    source_origin: str | None = None
+    if origin and origin != "null":
+        source_origin = origin.rstrip("/")
+    elif referer:
+        # Extract scheme + host from Referer
+        from urllib.parse import urlparse
+
+        parsed = urlparse(referer)
+        if parsed.scheme and parsed.netloc:
+            source_origin = f"{parsed.scheme}://{parsed.netloc}".rstrip("/")
+
+    if source_origin is None:
+        # No Origin/Referer — could be a same-origin navigation (browser omits for same-origin GET)
+        # For POST requests we reject (fail-closed)
+        return False
+
+    # If specific trusted origins are provided, check against them
+    if trusted_origins:
+        return source_origin in [o.rstrip("/") for o in trusted_origins]
+
+    # Same-origin check: compare against the request's own host
+    request_origin = f"{request.url.scheme}://{request.url.netloc}".rstrip("/")
+    return source_origin == request_origin
+
+
+# ── Login Rate Limiter ───────────────────────────────────────────────
+
+
+class LoginRateLimiter:
+    """Simple in-process sliding-window rate limiter for login requests.
+
+    Limits by client IP address with a configurable window and max requests.
+
+    Parameters
+    ----------
+    max_requests : int
+        Maximum number of requests allowed per window.
+    window_seconds : float
+        Time window in seconds.
+    """
+
+    def __init__(self, max_requests: int = 10, window_seconds: float = 60.0) -> None:
+        self._max_requests = max_requests
+        self._window = window_seconds
+        self._requests: dict[str, collections.deque[float]] = {}
+        self._lock = threading.Lock()
+
+    def is_allowed(self, client_ip: str) -> bool:
+        """Check if a request from *client_ip* is allowed."""
+        now = time.monotonic()
+        with self._lock:
+            if client_ip not in self._requests:
+                self._requests[client_ip] = collections.deque()
+
+            dq = self._requests[client_ip]
+            # Evict old entries outside the window
+            while dq and dq[0] < now - self._window:
+                dq.popleft()
+
+            if len(dq) >= self._max_requests:
+                return False
+
+            dq.append(now)
+            return True
+
+    def reset(self) -> None:
+        """Clear all rate limit state (for testing)."""
+        with self._lock:
+            self._requests.clear()
+
+
+_login_rate_limiter = LoginRateLimiter()
+
+
+# ── Bounded Auth State Store ─────────────────────────────────────────
+
+
+class AuthStateStore:
+    """Bounded, TTL-enforced store for pending OAuth2 CSRF state.
+
+    Thread-safe via ``asyncio.Lock``. Evicts expired entries on every
+    write and enforces a hard capacity limit to prevent memory exhaustion.
+
+    Parameters
+    ----------
+    max_pending : int
+        Maximum number of concurrent pending auth states.
+    max_age : float
+        Maximum age of a pending state in seconds before auto-eviction.
+    """
+
+    def __init__(self, max_pending: int = 1000, max_age: float = 600.0) -> None:
+        self._store: dict[str, dict[str, Any]] = {}
+        self._lock = asyncio.Lock()
+        self._max_pending = max_pending
+        self._max_age = max_age
+
+    async def put(self, state: str, data: dict[str, Any]) -> None:
+        """Store a pending auth state."""
+        async with self._lock:
+            self._evict_expired()
+            if len(self._store) >= self._max_pending:
+                # Evict oldest entry when at capacity
+                oldest_key = min(self._store, key=lambda k: self._store[k].get("created_at", 0))
+                del self._store[oldest_key]
+            self._store[state] = data
+
+    async def pop(self, state: str) -> dict[str, Any] | None:
+        """Retrieve and remove a pending auth state (single-use)."""
+        async with self._lock:
+            self._evict_expired()
+            return self._store.pop(state, None)
+
+    async def contains(self, state: str) -> bool:
+        """Check if a state exists."""
+        async with self._lock:
+            self._evict_expired()
+            return state in self._store
+
+    def _evict_expired(self) -> None:
+        """Remove all expired entries (caller must hold lock)."""
+        now = time.time()
+        expired = [
+            k for k, v in self._store.items() if now - v.get("created_at", 0) > self._max_age
+        ]
+        for k in expired:
+            del self._store[k]
+
+    async def cleanup(self) -> int:
+        """Explicitly clean up expired states. Returns count removed."""
+        async with self._lock:
+            before = len(self._store)
+            self._evict_expired()
+            return before - len(self._store)
+
+    async def size(self) -> int:
+        """Return current number of pending states."""
+        async with self._lock:
+            return len(self._store)
+
+    def _get_store_for_testing(self) -> dict[str, dict[str, Any]]:
+        """Expose internal store for testing only."""
+        return self._store
+
+
+# Global instance — shared across routes in this process.
+# For multi-worker deploy, this should be replaced with a Redis-backed store.
+_auth_state_store = AuthStateStore()
+
+# Legacy alias kept for test compatibility
+_pending_auth_states = _auth_state_store._get_store_for_testing()
+
+
+def create_auth_router(  # noqa: C901, PLR0915
+    provider: OAuthProvider,
+    session_store: SessionStore,
+    token_store: TokenStore,
+    deploy_settings: DeploySettings,
+    auth_config: AuthConfig,
+    use_pkce: bool = True,
+) -> APIRouter:
+    """Create a FastAPI router with OAuth2 authentication routes.
+
+    Parameters
+    ----------
+    provider : OAuthProvider
+        The configured OAuth2 provider.
+    session_store : SessionStore
+        Session store for creating/managing sessions.
+    token_store : TokenStore
+        Token store for persisting OAuth2 tokens.
+    deploy_settings : DeploySettings
+        Deploy configuration (cookie name, default roles, etc.).
+    auth_config : AuthConfig
+        Auth configuration (secret, session TTL, etc.).
+    use_pkce : bool
+        Whether to use PKCE (default True).
+
+    Returns
+    -------
+    APIRouter
+        Router with ``/auth/*`` routes.
+    """
+    router = APIRouter(prefix="/auth", tags=["authentication"])
+
+    @router.get("/login")
+    async def auth_login(request: Request) -> Response:
+        """Initiate OAuth2 login flow.
+
+        Generates PKCE challenge, state nonce, and OIDC nonce,
+        then redirects the user to the provider's authorization page.
+
+        Rate limited to prevent abuse.
+        """
+        # Rate limit login attempts by client IP
+        client_ip = request.client.host if request.client else "unknown"
+        if not _login_rate_limiter.is_allowed(client_ip):
+            return JSONResponse(
+                status_code=429,
+                content={
+                    "error": "rate_limited",
+                    "error_description": "Too many login attempts. Please try again later.",
+                },
+            )
+
+        state = secrets.token_urlsafe(32)
+        nonce = secrets.token_urlsafe(32)
+
+        pkce: PKCEChallenge | None = None
+        if use_pkce:
+            pkce = PKCEChallenge.generate()
+
+        # Determine redirect URI: use configured value or derive from request
+        configured_uri = getattr(deploy_settings, "auth_redirect_uri", "")
+        redirect_uri = configured_uri or str(request.url_for("auth_callback"))
+
+        # Enforce HTTPS for redirect URIs in deploy mode (unless localhost dev)
+        force_https = getattr(deploy_settings, "force_https", False)
+        if force_https and redirect_uri.startswith("http://"):
+            _host = redirect_uri.split("://", 1)[1].split("/")[0].split(":")[0]
+            if _host not in ("localhost", "127.0.0.1", "[::1]"):
+                redirect_uri = "https://" + redirect_uri[len("http://") :]
+
+        # Store state for CSRF validation
+        await _auth_state_store.put(
+            state,
+            {
+                "pkce_verifier": pkce.verifier if pkce else None,
+                "redirect_uri": redirect_uri,
+                "nonce": nonce,
+                "created_at": time.time(),
+            },
+        )
+
+        authorize_url = provider.build_authorize_url(
+            redirect_uri=redirect_uri,
+            state=state,
+            pkce=pkce,
+            extra_params={"nonce": nonce},
+        )
+
+        return RedirectResponse(url=authorize_url, status_code=302)
+
+    @router.get("/callback")
+    async def auth_callback(
+        request: Request,  # pylint: disable=unused-argument
+        code: str | None = None,
+        state: str | None = None,
+        error: str | None = None,
+        error_description: str | None = None,
+    ) -> Response:
+        """Handle OAuth2 callback from the provider.
+
+        Validates the state parameter, exchanges the authorization code
+        for tokens, creates a session, and redirects to the application.
+        """
+        if error:
+            return JSONResponse(
+                status_code=400,
+                content={
+                    "error": error,
+                    "error_description": error_description or "Authentication failed",
+                },
+            )
+
+        if not state or not await _auth_state_store.contains(state):
+            return JSONResponse(
+                status_code=400,
+                content={
+                    "error": "invalid_state",
+                    "error_description": "Invalid or expired state parameter",
+                },
+            )
+
+        if not code:
+            return JSONResponse(
+                status_code=400,
+                content={
+                    "error": "missing_code",
+                    "error_description": "Authorization code not provided",
+                },
+            )
+
+        # Retrieve and remove pending state (single-use)
+        auth_state = await _auth_state_store.pop(state)
+        if auth_state is None:
+            return JSONResponse(
+                status_code=400,
+                content={
+                    "error": "invalid_state",
+                    "error_description": "State already consumed or expired",
+                },
+            )
+        redirect_uri = auth_state["redirect_uri"]
+        pkce_verifier = auth_state.get("pkce_verifier")
+        nonce = auth_state.get("nonce")
+
+        # Exchange code for tokens
+        try:
+            tokens = await provider.exchange_code(
+                code=code,
+                redirect_uri=redirect_uri,
+                pkce_verifier=pkce_verifier,
+                nonce=nonce,
+            )
+        except Exception:
+            logger.exception("Token exchange failed")
+            return JSONResponse(
+                status_code=500,
+                content={
+                    "error": "token_exchange_failed",
+                    "error_description": "An internal error occurred",
+                },
+            )
+
+        # Fetch user info
+        user_info: dict[str, Any] = {}
+        try:
+            user_info = await provider.get_userinfo(tokens.access_token)
+        except Exception as exc:
+            logger.warning("Failed to fetch user info: %s", exc)
+
+        # Determine user ID from user info or token
+        user_id = (
+            user_info.get("sub")
+            or user_info.get("id")
+            or user_info.get("login")
+            or user_info.get("email")
+            or "unknown"
+        )
+
+        # Create session
+        session_ttl = auth_config.session_ttl
+        expires_at = time.time() + session_ttl
+
+        session_token = generate_session_token(
+            user_id=str(user_id),
+            secret=auth_config.token_secret,
+            expires_at=expires_at,
+        )
+
+        session = UserSession(
+            session_id=session_token,
+            user_id=str(user_id),
+            roles=list(deploy_settings.default_roles),
+            created_at=time.time(),
+            expires_at=expires_at,
+            metadata={
+                "provider": provider.__class__.__name__,
+                "user_info": user_info,
+            },
+        )
+
+        # Check if the user is an admin
+        admin_users = getattr(deploy_settings, "admin_users", [])
+        if (
+            str(user_id) in admin_users or user_info.get("email") in admin_users
+        ) and "admin" not in session.roles:
+            session.roles.append("admin")
+
+        await session_store.create_session(
+            session_id=session.session_id,
+            user_id=session.user_id,
+            roles=session.roles,
+            ttl=int(auth_config.session_ttl),
+            metadata=session.metadata,
+        )
+
+        # Store OAuth tokens keyed by session_id for isolation
+        await token_store.save(session_token, tokens)
+
+        # Set session cookie and redirect to app
+        cookie_name = deploy_settings.auth_session_cookie
+        response = RedirectResponse(url="/", status_code=302)
+
+        # Determine cookie security based on request scheme and config
+        force_https = getattr(deploy_settings, "force_https", False)
+        request_is_https = str(request.url).startswith("https://")
+        cookie_secure = force_https or request_is_https
+
+        response.set_cookie(
+            key=cookie_name,
+            value=session_token,
+            httponly=True,
+            secure=cookie_secure,
+            samesite="lax",
+            max_age=session_ttl,
+        )
+
+        logger.info("User %s authenticated via %s", user_id, provider.__class__.__name__)
+        return response
+
+    @router.post("/refresh")
+    async def auth_refresh(request: Request) -> JSONResponse:
+        """Refresh the OAuth2 access token using the refresh token."""
+        # CSRF origin verification for state-changing POST
+        if not _verify_csrf_origin(request):
+            return JSONResponse(
+                status_code=403,
+                content={
+                    "error": "csrf_failed",
+                    "error_description": "Origin verification failed",
+                },
+            )
+
+        session: UserSession | None = getattr(request.state, "session", None)
+        if not session:
+            return JSONResponse(status_code=401, content={"error": "not_authenticated"})
+
+        existing_tokens = await token_store.load(session.session_id)
+        if not existing_tokens or not existing_tokens.refresh_token:
+            return JSONResponse(
+                status_code=400,
+                content={
+                    "error": "no_refresh_token",
+                    "error_description": "No refresh token available",
+                },
+            )
+
+        try:
+            new_tokens = await provider.refresh_tokens(existing_tokens.refresh_token)
+            await token_store.save(session.session_id, new_tokens)
+            return JSONResponse(
+                content={
+                    "success": True,
+                    "expires_in": new_tokens.expires_in,
+                    "token_type": new_tokens.token_type,
+                }
+            )
+        except Exception:
+            logger.exception("Token refresh failed for user %s", session.user_id)
+            return JSONResponse(
+                status_code=500,
+                content={
+                    "error": "refresh_failed",
+                    "error_description": "An internal error occurred",
+                },
+            )
+
+    @router.post("/logout")
+    async def auth_logout(request: Request) -> Response:
+        """Log out the current user.
+
+        Deletes the session, clears stored tokens, and removes the cookie.
+        """
+        # CSRF origin verification for state-changing POST
+        if not _verify_csrf_origin(request):
+            return JSONResponse(
+                status_code=403,
+                content={
+                    "error": "csrf_failed",
+                    "error_description": "Origin verification failed",
+                },
+            )
+
+        session: UserSession | None = getattr(request.state, "session", None)
+
+        if session:
+            # Revoke tokens at provider if supported
+            existing_tokens = await token_store.load(session.session_id)
+            if existing_tokens:
+                with contextlib.suppress(Exception):
+                    await provider.revoke_token(existing_tokens.access_token)
+
+            # Clean up
+            await session_store.delete_session(session.session_id)
+            await token_store.delete(session.session_id)
+
+        cookie_name = deploy_settings.auth_session_cookie
+        response = JSONResponse(content={"success": True, "message": "Logged out"})
+        response.delete_cookie(key=cookie_name)
+        return response
+
+    @router.get("/userinfo")
+    async def auth_userinfo(request: Request) -> JSONResponse:
+        """Return the current user's profile information."""
+        session: UserSession | None = getattr(request.state, "session", None)
+        if not session:
+            return JSONResponse(status_code=401, content={"error": "not_authenticated"})
+
+        user_info = session.metadata.get("user_info", {})
+        return JSONResponse(
+            content={
+                "user_id": session.user_id,
+                "roles": session.roles,
+                "user_info": user_info,
+            }
+        )
+
+    @router.get("/status")
+    async def auth_status(request: Request) -> JSONResponse:
+        """Return the current authentication status."""
+        session: UserSession | None = getattr(request.state, "session", None)
+        if not session:
+            return JSONResponse(
+                content={
+                    "authenticated": False,
+                }
+            )
+
+        return JSONResponse(
+            content={
+                "authenticated": True,
+                "user_id": session.user_id,
+                "roles": session.roles,
+                "expires_at": session.expires_at,
+            }
+        )
+
+    return router
+
+
+def cleanup_expired_states(max_age: float = 600.0) -> int:
+    """Remove expired pending auth states (synchronous wrapper).
+
+    Parameters
+    ----------
+    max_age : float
+        Maximum age in seconds before a state is considered expired.
+
+    Returns
+    -------
+    int
+        Number of expired states removed.
+    """
+    now = time.time()
+    store = _auth_state_store._get_store_for_testing()
+    expired = [k for k, v in store.items() if now - v.get("created_at", 0) > max_age]
+    for k in expired:
+        del store[k]
+    return len(expired)
diff --git a/pywry/pywry/auth/flow.py b/pywry/pywry/auth/flow.py
new file mode 100644
index 0000000..37b7346
--- /dev/null
+++ b/pywry/pywry/auth/flow.py
@@ -0,0 +1,381 @@
+"""OAuth2 authentication flow orchestrator.
+
+Provides AuthFlowManager that coordinates the complete OAuth2 flow
+in both native window mode (ephemeral callback server) and deploy
+mode (server-side routes). Uses threading.Event for blocking
+synchronization between the main thread and auth callbacks.
+"""
+
+# pylint: disable=logging-too-many-args,too-many-branches,too-many-statements
+
+from __future__ import annotations
+
+import contextlib
+import logging
+import secrets
+import threading
+
+from typing import TYPE_CHECKING, Any
+
+from ..exceptions import (
+    AuthenticationError,
+    AuthFlowCancelled,
+    AuthFlowTimeout,
+)
+from ..state.sync_helpers import run_async
+from ..state.types import AuthFlowResult, AuthFlowState
+from .callback_server import OAuthCallbackServer
+from .pkce import PKCEChallenge
+
+
+if TYPE_CHECKING:
+    from .providers import OAuthProvider
+    from .session import SessionManager
+    from .token_store import TokenStore
+
+
+logger = logging.getLogger("pywry.auth")
+
+
+class AuthFlowManager:
+    """Orchestrates OAuth2 authentication flows.
+
+    Supports two modes:
+
+    - **Native mode**: Opens a dedicated auth window pointing at the
+      provider's authorize URL, captures the redirect on an ephemeral
+      localhost HTTP server, and exchanges the code for tokens.
+
+    - **Deploy mode**: Returns the ``/auth/login`` URL for the frontend
+      to navigate to. The server-side routes handle the actual flow.
+
+    Parameters
+    ----------
+    provider : OAuthProvider
+        The configured OAuth2 provider.
+    token_store : TokenStore, optional
+        Store for persisting tokens after successful auth.
+    session_manager : SessionManager, optional
+        Session manager for token lifecycle.
+    use_pkce : bool
+        Whether to use PKCE (default ``True``).
+    auth_timeout : float
+        Seconds to wait for the auth callback (default ``120``).
+    """
+
+    def __init__(
+        self,
+        provider: OAuthProvider,
+        token_store: TokenStore | None = None,
+        session_manager: SessionManager | None = None,
+        use_pkce: bool = True,
+        auth_timeout: float = 120.0,
+    ) -> None:
+        """Initialize the auth flow manager."""
+        self.provider = provider
+        self.token_store = token_store
+        self.session_manager = session_manager
+        self.use_pkce = use_pkce
+        self.auth_timeout = auth_timeout
+
+        self._flow_state = AuthFlowState.PENDING
+        self._flow_id: str | None = None
+        self._cancellation_event = threading.Event()
+        self._callback_server: OAuthCallbackServer | None = None
+
+    @property
+    def flow_state(self) -> AuthFlowState:
+        """Current state of the auth flow."""
+        return self._flow_state
+
+    def run_native(  # noqa: C901, PLR0912, PLR0915
+        self,
+        show_window: Any | None = None,
+        close_window: Any | None = None,
+        window_config: dict[str, Any] | None = None,
+    ) -> AuthFlowResult:
+        """Run the OAuth2 flow in native window mode.
+
+        This method blocks until authentication completes, times out,
+        or is cancelled.
+
+        Parameters
+        ----------
+        show_window : callable, optional
+            Function to open the auth window. Signature:
+            ``show_window(url: str, config: dict) -> str`` (returns label).
+            If None, the URL is logged for manual navigation.
+        close_window : callable, optional
+            Function to close the auth window. Signature:
+            ``close_window(label: str) -> None``.
+        window_config : dict, optional
+            Additional window configuration (title, width, height).
+
+        Returns
+        -------
+        AuthFlowResult
+            The result of the authentication flow.
+
+        Raises
+        ------
+        AuthFlowTimeout
+            If the callback is not received within the timeout.
+        AuthFlowCancelled
+            If the user closes the auth window or aborts.
+        AuthenticationError
+            If the provider returns an error.
+        """
+        self._flow_id = secrets.token_urlsafe(16)
+        self._flow_state = AuthFlowState.IN_PROGRESS
+        self._cancellation_event.clear()
+
+        provider_name = self.provider.__class__.__name__
+
+        # 1. Start callback server
+        self._callback_server = OAuthCallbackServer()
+        redirect_uri = self._callback_server.start()
+        logger.info("Auth flow %s: callback server at %s", self._flow_id, redirect_uri)
+
+        auth_window_label: str | None = None
+
+        try:
+            # 2. Generate PKCE + state
+            pkce: PKCEChallenge | None = None
+            if self.use_pkce:
+                pkce = PKCEChallenge.generate()
+
+            state = secrets.token_urlsafe(32)
+
+            # 3. Build authorize URL
+            authorize_url = self.provider.build_authorize_url(
+                redirect_uri=redirect_uri,
+                state=state,
+                pkce=pkce,
+            )
+
+            # 4. Open auth window (or log URL)
+            config = {
+                "title": "Sign In",
+                "width": 500,
+                "height": 700,
+                "center": True,
+                "resizable": True,
+                **(window_config or {}),
+            }
+
+            if show_window is not None:
+                auth_window_label = show_window(authorize_url, config)
+                logger.debug("Auth window opened: %s", auth_window_label)
+            else:
+                logger.info("Open this URL to authenticate: %s", authorize_url)
+
+            # 5. Wait for callback with cancellation polling
+            result = self._wait_for_callback_with_cancellation()
+
+            if result is None:
+                # Timeout
+                self._flow_state = AuthFlowState.TIMED_OUT
+                msg = f"Authentication timed out after {self.auth_timeout}s"
+                raise AuthFlowTimeout(  # noqa: TRY301
+                    msg,
+                    timeout=self.auth_timeout,
+                    provider=provider_name,
+                    flow_id=self._flow_id,
+                )
+
+            # Check for errors from provider
+            if result.get("error"):
+                self._flow_state = AuthFlowState.FAILED
+                error_desc = result.get("error_description") or result["error"]
+                msg = f"Provider returned error: {error_desc}"
+                raise AuthenticationError(msg, provider=provider_name, flow_id=self._flow_id)  # noqa: TRY301
+
+            # Validate state
+            if result.get("state") != state:
+                self._flow_state = AuthFlowState.FAILED
+                msg = "State parameter mismatch (possible CSRF attack)"
+                raise AuthenticationError(msg, provider=provider_name, flow_id=self._flow_id)  # noqa: TRY301
+
+            code = result.get("code")
+            if not code:
+                self._flow_state = AuthFlowState.FAILED
+                msg = "No authorization code in callback"
+                raise AuthenticationError(msg, provider=provider_name, flow_id=self._flow_id)  # noqa: TRY301
+
+            # 6. Exchange code for tokens
+            tokens = run_async(
+                self.provider.exchange_code(
+                    code=code,
+                    redirect_uri=redirect_uri,
+                    pkce_verifier=pkce.verifier if pkce else None,
+                ),
+                timeout=30.0,
+            )
+
+            # 7. Fetch user info
+            user_info: dict[str, Any] = {}
+            try:
+                user_info = run_async(
+                    self.provider.get_userinfo(tokens.access_token),
+                    timeout=10.0,
+                )
+            except Exception as exc:
+                logger.warning("Failed to fetch user info: %s", exc)
+
+            # 8. Store tokens if token_store is available
+            if self.token_store:
+                user_id = (
+                    user_info.get("sub")
+                    or user_info.get("id")
+                    or user_info.get("email")
+                    or "default"
+                )
+                run_async(self.token_store.save(str(user_id), tokens))
+
+            # 9. Initialize session manager if available
+            if self.session_manager:
+                run_async(self.session_manager.save_tokens(tokens))
+
+            self._flow_state = AuthFlowState.COMPLETED
+            logger.info("Auth flow %s completed successfully", self._flow_id)
+
+            return AuthFlowResult(
+                success=True,
+                tokens=tokens,
+                user_info=user_info,
+            )
+
+        except (AuthFlowTimeout, AuthFlowCancelled):
+            raise
+        except AuthenticationError:
+            raise
+        except Exception as exc:
+            self._flow_state = AuthFlowState.FAILED
+            msg = f"Authentication flow failed: {exc}"
+            raise AuthenticationError(msg, provider=provider_name, flow_id=self._flow_id) from exc
+        finally:
+            # Clean up
+            if self._callback_server:
+                self._callback_server.stop()
+                self._callback_server = None
+            if auth_window_label and close_window is not None:
+                with contextlib.suppress(Exception):
+                    close_window(auth_window_label)
+
+    def run_deploy(self, base_url: str = "") -> str:
+        """Get the login URL for deploy mode.
+
+        In deploy mode, the actual OAuth2 flow is handled server-side
+        by the routes in ``deploy_routes.py``. This method simply
+        returns the URL that the frontend should navigate to.
+
+        Parameters
+        ----------
+        base_url : str
+            The base URL of the deploy server (e.g. ``http://localhost:8080``).
+
+        Returns
+        -------
+        str
+            The ``/auth/login`` URL.
+        """
+        return f"{base_url}/auth/login"
+
+    def authenticate(
+        self,
+        app: Any,
+        show_window: Any | None = None,
+        close_window: Any | None = None,
+        window_config: dict[str, Any] | None = None,
+    ) -> AuthFlowResult:
+        """Unified authentication entry point.
+
+        Detects the app mode and runs the appropriate flow.
+
+        Parameters
+        ----------
+        app : PyWry
+            The PyWry application instance.
+        show_window : callable, optional
+            Window opener for native mode.
+        close_window : callable, optional
+            Window closer for native mode.
+        window_config : dict, optional
+            Window configuration for native mode.
+
+        Returns
+        -------
+        AuthFlowResult
+            The authentication result.
+        """
+        mode_enum = getattr(app, "_mode_enum", None)
+
+        # Check if we're in browser/deploy mode
+        if mode_enum is not None:
+            try:
+                from ..models import WindowMode
+
+                if mode_enum == WindowMode.BROWSER:
+                    login_url = self.run_deploy()
+                    return AuthFlowResult(
+                        success=False,
+                        error=f"Navigate to {login_url} to authenticate (deploy mode)",
+                    )
+            except ImportError:
+                pass
+
+        # Native mode — provide a default show_window that opens the system browser
+        if show_window is None:
+            import webbrowser
+
+            def _open_browser(url: str, _config: dict[str, Any]) -> str:
+                webbrowser.open(url)
+                return "__browser__"
+
+            show_window = _open_browser
+            # No close needed for system browser
+            close_window = close_window or (lambda _label: None)
+
+        return self.run_native(
+            show_window=show_window,
+            close_window=close_window,
+            window_config=window_config,
+        )
+
+    def cancel(self) -> None:
+        """Cancel the current authentication flow.
+
+        Sets the cancellation event which unblocks ``_wait_for_callback_with_cancellation``.
+        """
+        self._flow_state = AuthFlowState.CANCELLED
+        self._cancellation_event.set()
+        if self._callback_server:
+            self._callback_server.stop()
+
+    def _wait_for_callback_with_cancellation(self) -> dict[str, Any] | None:
+        """Wait for the callback with cancellation support.
+
+        Polls both the callback server result and the cancellation event
+        every 100ms. Returns the callback result, or raises
+        ``AuthFlowCancelled`` if cancelled, or returns ``None`` on timeout.
+        """
+        deadline = threading.Event()
+        elapsed = 0.0
+        poll_interval = 0.1
+
+        while elapsed < self.auth_timeout:
+            # Check cancellation
+            if self._cancellation_event.is_set():
+                self._flow_state = AuthFlowState.CANCELLED
+                provider_name = self.provider.__class__.__name__
+                msg = "Authentication flow was cancelled"
+                raise AuthFlowCancelled(msg, provider=provider_name, flow_id=self._flow_id)
+
+            # Check callback server
+            if self._callback_server and self._callback_server._result_event.is_set():
+                return self._callback_server._result
+
+            deadline.wait(timeout=poll_interval)
+            elapsed += poll_interval
+
+        return None
diff --git a/pywry/pywry/auth/pkce.py b/pywry/pywry/auth/pkce.py
new file mode 100644
index 0000000..5672a66
--- /dev/null
+++ b/pywry/pywry/auth/pkce.py
@@ -0,0 +1,52 @@
+"""PKCE (Proof Key for Code Exchange) implementation.
+
+RFC 7636 - Proof Key for Code Exchange for OAuth 2.0 public clients.
+Uses S256 challenge method (SHA-256 hash of the code verifier).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import secrets
+
+from base64 import urlsafe_b64encode
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class PKCEChallenge:
+    """PKCE code verifier and challenge pair.
+
+    Attributes
+    ----------
+    verifier : str
+        The code verifier (high-entropy random string).
+    challenge : str
+        The code challenge (base64url-encoded SHA-256 hash of verifier).
+    method : str
+        The challenge method, always "S256".
+    """
+
+    verifier: str
+    challenge: str
+    method: str = "S256"
+
+    @classmethod
+    def generate(cls, length: int = 64) -> PKCEChallenge:
+        """Generate a new PKCE code verifier and challenge.
+
+        Parameters
+        ----------
+        length : int
+            Number of bytes for the random verifier (default 64).
+            RFC 7636 recommends at least 32 bytes.
+
+        Returns
+        -------
+        PKCEChallenge
+            A new PKCE challenge pair.
+        """
+        verifier = secrets.token_urlsafe(length)
+        digest = hashlib.sha256(verifier.encode("ascii")).digest()
+        challenge = urlsafe_b64encode(digest).rstrip(b"=").decode("ascii")
+        return cls(verifier=verifier, challenge=challenge)
diff --git a/pywry/pywry/auth/providers.py b/pywry/pywry/auth/providers.py
new file mode 100644
index 0000000..e507572
--- /dev/null
+++ b/pywry/pywry/auth/providers.py
@@ -0,0 +1,811 @@
+"""OAuth2 provider abstractions.
+
+Defines the OAuthProvider ABC and concrete implementations for
+Google, GitHub, Microsoft, and generic OIDC providers.
+"""
+
+# pylint: disable=logging-too-many-args
+
+from __future__ import annotations
+
+import logging
+import time
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Any
+from urllib.parse import urlencode
+
+import httpx
+
+from ..exceptions import AuthenticationError, TokenError, TokenRefreshError
+from ..state.types import OAuthTokenSet
+
+
+try:
+    from authlib.jose import JsonWebKey, JsonWebToken  # type: ignore[import-untyped]
+
+    _HAS_AUTHLIB = True
+except ImportError:
+    _HAS_AUTHLIB = False
+
+
+if TYPE_CHECKING:
+    from .pkce import PKCEChallenge
+
+logger = logging.getLogger("pywry.auth")
+
+
+class OAuthProvider(ABC):
+    """Abstract base class for OAuth2 providers.
+
+    Parameters
+    ----------
+    client_id : str
+        The OAuth2 client ID.
+    client_secret : str
+        The OAuth2 client secret (empty string for public clients).
+    scopes : list[str]
+        Requested OAuth2 scopes.
+    authorize_url : str
+        The provider's authorization endpoint.
+    token_url : str
+        The provider's token exchange endpoint.
+    userinfo_url : str
+        The provider's userinfo endpoint (optional for non-OIDC).
+    revocation_url : str
+        The provider's token revocation endpoint (RFC 7009).
+    """
+
+    def __init__(
+        self,
+        client_id: str,
+        client_secret: str = "",
+        scopes: list[str] | None = None,
+        authorize_url: str = "",
+        token_url: str = "",
+        userinfo_url: str = "",
+        revocation_url: str = "",
+    ) -> None:
+        """Initialize OAuth provider."""
+        self.client_id = client_id
+        self.client_secret = client_secret
+        self.scopes = scopes or []
+        self.authorize_url = authorize_url
+        self.token_url = token_url
+        self.userinfo_url = userinfo_url
+        self.revocation_url = revocation_url
+        self._http_client: httpx.AsyncClient | None = None
+
+    async def _get_client(self) -> httpx.AsyncClient:
+        """Get or create the shared HTTP client."""
+        if self._http_client is None or self._http_client.is_closed:
+            self._http_client = httpx.AsyncClient(timeout=30.0)
+        return self._http_client
+
+    async def close(self) -> None:
+        """Close the shared HTTP client. Call from app shutdown lifecycle."""
+        if self._http_client is not None and not self._http_client.is_closed:
+            await self._http_client.aclose()
+            self._http_client = None
+
+    def build_authorize_url(
+        self,
+        redirect_uri: str,
+        state: str,
+        pkce: PKCEChallenge | None = None,
+        extra_params: dict[str, str] | None = None,
+    ) -> str:
+        """Build the full authorization URL.
+
+        Parameters
+        ----------
+        redirect_uri : str
+            The callback URL to redirect to after authorization.
+        state : str
+            CSRF protection nonce.
+        pkce : PKCEChallenge, optional
+            PKCE challenge for public clients.
+        extra_params : dict, optional
+            Additional query parameters.
+
+        Returns
+        -------
+        str
+            The full authorization URL.
+        """
+        params: dict[str, str] = {
+            "response_type": "code",
+            "client_id": self.client_id,
+            "redirect_uri": redirect_uri,
+            "state": state,
+            "scope": " ".join(self.scopes),
+        }
+        if pkce:
+            params["code_challenge"] = pkce.challenge
+            params["code_challenge_method"] = pkce.method
+        if extra_params:
+            params.update(extra_params)
+        return f"{self.authorize_url}?{urlencode(params)}"
+
+    @abstractmethod
+    async def exchange_code(
+        self,
+        code: str,
+        redirect_uri: str,
+        pkce_verifier: str | None = None,
+        nonce: str | None = None,
+    ) -> OAuthTokenSet:
+        """Exchange authorization code for tokens.
+
+        Parameters
+        ----------
+        code : str
+            The authorization code from the callback.
+        redirect_uri : str
+            The redirect URI used in the authorization request.
+        pkce_verifier : str, optional
+            The PKCE code verifier if PKCE was used.
+        nonce : str, optional
+            The nonce sent in the authorize request (for ID token validation).
+
+        Returns
+        -------
+        OAuthTokenSet
+            The token set from the provider.
+
+        Raises
+        ------
+        TokenError
+            If the code exchange fails.
+        """
+
+    @abstractmethod
+    async def refresh_tokens(self, refresh_token: str) -> OAuthTokenSet:
+        """Refresh an expired access token.
+
+        Parameters
+        ----------
+        refresh_token : str
+            The refresh token.
+
+        Returns
+        -------
+        OAuthTokenSet
+            A new token set with a fresh access token.
+
+        Raises
+        ------
+        TokenRefreshError
+            If the refresh fails.
+        """
+
+    async def get_userinfo(self, access_token: str) -> dict[str, Any]:
+        """Fetch user profile information from the provider.
+
+        Parameters
+        ----------
+        access_token : str
+            A valid access token.
+
+        Returns
+        -------
+        dict[str, Any]
+            User profile data from the provider.
+        """
+        if not self.userinfo_url:
+            return {}
+        client = await self._get_client()
+        resp = await client.get(
+            self.userinfo_url,
+            headers={"Authorization": f"Bearer {access_token}"},
+            timeout=10.0,
+        )
+        resp.raise_for_status()
+        return resp.json()  # type: ignore[no-any-return]
+
+    async def revoke_token(self, token: str) -> bool:
+        """Revoke a token at the provider (RFC 7009).
+
+        Posts to the ``revocation_url`` if one is configured.
+        Subclasses with non-standard revocation APIs should override.
+
+        Parameters
+        ----------
+        token : str
+            The token to revoke (access or refresh).
+
+        Returns
+        -------
+        bool
+            True if revocation succeeded, False if no endpoint
+            is configured or the request failed.
+        """
+        if not self.revocation_url:
+            return False
+        try:
+            client = await self._get_client()
+            resp = await client.post(
+                self.revocation_url,
+                data={"token": token, "client_id": self.client_id},
+                timeout=10.0,
+            )
+        except httpx.HTTPError:
+            return False
+        else:
+            return resp.is_success
+
+
+class GenericOIDCProvider(OAuthProvider):
+    """Generic OpenID Connect provider.
+
+    Supports auto-discovery from ``/.well-known/openid-configuration``
+    if an ``issuer_url`` is provided.
+
+    Parameters
+    ----------
+    client_id : str
+        The OAuth2 client ID.
+    client_secret : str
+        The OAuth2 client secret.
+    issuer_url : str
+        The OIDC issuer URL (used for auto-discovery).
+    scopes : list[str], optional
+        Requested scopes (defaults to ``["openid", "email", "profile"]``).
+    """
+
+    def __init__(
+        self,
+        client_id: str,
+        client_secret: str = "",
+        issuer_url: str = "",
+        scopes: list[str] | None = None,
+        authorize_url: str = "",
+        token_url: str = "",
+        userinfo_url: str = "",
+        revocation_url: str = "",
+        *,
+        require_id_token_validation: bool = True,
+    ) -> None:
+        """Initialize OIDC provider."""
+        super().__init__(
+            client_id=client_id,
+            client_secret=client_secret,
+            scopes=scopes or ["openid", "email", "profile"],
+            authorize_url=authorize_url,
+            token_url=token_url,
+            userinfo_url=userinfo_url,
+            revocation_url=revocation_url,
+        )
+        self.issuer_url = issuer_url
+        self.require_id_token_validation = require_id_token_validation
+        self._discovered = False
+        self._jwks_uri: str = ""
+        self._jwks_data: dict[str, Any] | None = None
+
+    async def _discover(self) -> None:
+        """Auto-discover OIDC endpoints from the well-known configuration."""
+        if self._discovered or not self.issuer_url:
+            return
+        url = f"{self.issuer_url.rstrip('/')}/.well-known/openid-configuration"
+        try:
+            client = await self._get_client()
+            resp = await client.get(url, timeout=10.0)
+            resp.raise_for_status()
+            config = resp.json()
+            # Validate issuer exactly matches configured issuer
+            discovered_issuer = config.get("issuer", "")
+            expected = self.issuer_url.rstrip("/")
+            if discovered_issuer.rstrip("/") != expected:
+                msg = f"OIDC issuer mismatch: expected '{expected}', got '{discovered_issuer}'"
+                raise AuthenticationError(msg, provider=self.__class__.__name__)
+            if not self.authorize_url:
+                self.authorize_url = config.get("authorization_endpoint", "")
+            if not self.token_url:
+                self.token_url = config.get("token_endpoint", "")
+            if not self.userinfo_url:
+                self.userinfo_url = config.get("userinfo_endpoint", "")
+            if not self.revocation_url:
+                self.revocation_url = config.get("revocation_endpoint", "")
+            self._jwks_uri = config.get("jwks_uri", "")
+            self._discovered = True
+        except httpx.HTTPError as exc:
+            logger.warning("OIDC discovery failed for %s: %s", self.issuer_url, exc)
+
+    async def _fetch_jwks(self) -> dict[str, Any]:
+        """Fetch the JWKS key set from the provider."""
+        if self._jwks_data is not None:
+            return self._jwks_data
+        if not self._jwks_uri:
+            msg = "JWKS URI not available (run discovery first)"
+            raise TokenError(msg, provider=self.__class__.__name__)
+        client = await self._get_client()
+        resp = await client.get(self._jwks_uri, timeout=10.0)
+        resp.raise_for_status()
+        self._jwks_data = resp.json()
+        return self._jwks_data
+
+    async def validate_id_token(
+        self,
+        id_token: str,
+        nonce: str | None = None,
+    ) -> dict[str, Any]:
+        """Validate an OIDC ID token.
+
+        Checks signature (via JWKS), issuer, audience, expiry, and nonce.
+
+        Parameters
+        ----------
+        id_token : str
+            The raw ID token JWT string.
+        nonce : str, optional
+            Expected nonce value (if one was sent in the authorize request).
+
+        Returns
+        -------
+        dict[str, Any]
+            The validated claims from the ID token.
+
+        Raises
+        ------
+        TokenError
+            If validation fails for any reason.
+        """
+        if not _HAS_AUTHLIB:
+            msg = (
+                "authlib is required for OIDC ID token validation. "
+                "Install with: pip install authlib"
+            )
+            raise TokenError(msg, provider=self.__class__.__name__)
+
+        await self._discover()
+        jwks_data = await self._fetch_jwks()
+
+        jwt = JsonWebToken(["RS256", "RS384", "RS512", "ES256", "ES384", "ES512"])
+
+        claims_options: dict[str, Any] = {
+            "iss": {"essential": True, "value": self.issuer_url.rstrip("/")},
+            "aud": {"essential": True, "value": self.client_id},
+            "exp": {"essential": True},
+        }
+        if nonce:
+            claims_options["nonce"] = {"essential": True, "value": nonce}
+
+        try:
+            key_set = JsonWebKey.import_key_set(jwks_data)
+            claims = jwt.decode(
+                id_token,
+                key_set,
+                claims_options=claims_options,
+            )
+            claims.validate()
+        except Exception as exc:
+            msg = f"ID token validation failed: {exc}"
+            raise TokenError(msg, provider=self.__class__.__name__) from exc
+
+        return dict(claims)
+
+    async def exchange_code(
+        self,
+        code: str,
+        redirect_uri: str,
+        pkce_verifier: str | None = None,
+        nonce: str | None = None,
+    ) -> OAuthTokenSet:
+        """Exchange authorization code for tokens via OIDC token endpoint.
+
+        Parameters
+        ----------
+        code : str
+            The authorization code from the callback.
+        redirect_uri : str
+            The redirect URI used in the authorization request.
+        pkce_verifier : str, optional
+            The PKCE code verifier if PKCE was used.
+        nonce : str, optional
+            The nonce sent in the authorize request (for ID token validation).
+        """
+        await self._discover()
+        if not self.token_url:
+            msg = "Token URL not configured and discovery failed"
+            raise TokenError(msg, provider=self.__class__.__name__)
+
+        data: dict[str, str] = {
+            "grant_type": "authorization_code",
+            "code": code,
+            "redirect_uri": redirect_uri,
+            "client_id": self.client_id,
+        }
+        if self.client_secret:
+            data["client_secret"] = self.client_secret
+        if pkce_verifier:
+            data["code_verifier"] = pkce_verifier
+
+        try:
+            client = await self._get_client()
+            resp = await client.post(
+                self.token_url,
+                data=data,
+                headers={"Accept": "application/json"},
+                timeout=30.0,
+            )
+            resp.raise_for_status()
+            raw = resp.json()
+        except httpx.HTTPStatusError as exc:
+            msg = f"Token exchange failed: {exc.response.status_code}"
+            raise TokenError(msg, provider=self.__class__.__name__) from exc
+        except httpx.HTTPError as exc:
+            msg = f"Token exchange request failed: {exc}"
+            raise TokenError(msg, provider=self.__class__.__name__) from exc
+
+        # Validate ID token if present and validation is required
+        id_token_raw = raw.get("id_token")
+        if id_token_raw and self.require_id_token_validation:
+            await self.validate_id_token(id_token_raw, nonce=nonce)
+
+        return OAuthTokenSet(
+            access_token=raw["access_token"],
+            token_type=raw.get("token_type", "Bearer"),
+            refresh_token=raw.get("refresh_token"),
+            expires_in=raw.get("expires_in"),
+            id_token=id_token_raw,
+            scope=raw.get("scope", ""),
+            raw=raw,
+            issued_at=time.time(),
+        )
+
+    async def refresh_tokens(self, refresh_token: str) -> OAuthTokenSet:
+        """Refresh tokens via OIDC token endpoint."""
+        await self._discover()
+        if not self.token_url:
+            msg = "Token URL not configured and discovery failed"
+            raise TokenRefreshError(msg, provider=self.__class__.__name__)
+
+        data: dict[str, str] = {
+            "grant_type": "refresh_token",
+            "refresh_token": refresh_token,
+            "client_id": self.client_id,
+        }
+        if self.client_secret:
+            data["client_secret"] = self.client_secret
+
+        try:
+            client = await self._get_client()
+            resp = await client.post(
+                self.token_url,
+                data=data,
+                headers={"Accept": "application/json"},
+                timeout=30.0,
+            )
+            resp.raise_for_status()
+            raw = resp.json()
+        except httpx.HTTPStatusError as exc:
+            msg = f"Token refresh failed: {exc.response.status_code}"
+            raise TokenRefreshError(msg, provider=self.__class__.__name__) from exc
+        except httpx.HTTPError as exc:
+            msg = f"Token refresh request failed: {exc}"
+            raise TokenRefreshError(msg, provider=self.__class__.__name__) from exc
+
+        return OAuthTokenSet(
+            access_token=raw["access_token"],
+            token_type=raw.get("token_type", "Bearer"),
+            refresh_token=raw.get("refresh_token", refresh_token),
+            expires_in=raw.get("expires_in"),
+            id_token=raw.get("id_token"),
+            scope=raw.get("scope", ""),
+            raw=raw,
+            issued_at=time.time(),
+        )
+
+    async def revoke_token(self, token: str) -> bool:
+        """Revoke a token via the OIDC revocation endpoint.
+
+        Triggers endpoint auto-discovery before delegating to the
+        base implementation.
+        """
+        await self._discover()
+        return await super().revoke_token(token)
+
+
+class GoogleProvider(GenericOIDCProvider):
+    """Google OAuth2 provider with preset endpoints.
+
+    Parameters
+    ----------
+    client_id : str
+        Google OAuth2 client ID.
+    client_secret : str
+        Google OAuth2 client secret.
+    scopes : list[str], optional
+        Requested scopes (defaults to openid, email, profile).
+    """
+
+    def __init__(
+        self,
+        client_id: str,
+        client_secret: str = "",
+        scopes: list[str] | None = None,
+    ) -> None:
+        """Initialize Google provider."""
+        super().__init__(
+            client_id=client_id,
+            client_secret=client_secret,
+            scopes=scopes or ["openid", "email", "profile"],
+            authorize_url="https://accounts.google.com/o/oauth2/v2/auth",
+            token_url="https://oauth2.googleapis.com/token",  # noqa: S106
+            userinfo_url="https://openidconnect.googleapis.com/v1/userinfo",
+            revocation_url="https://oauth2.googleapis.com/revoke",
+        )
+
+    def build_authorize_url(
+        self,
+        redirect_uri: str,
+        state: str,
+        pkce: PKCEChallenge | None = None,
+        extra_params: dict[str, str] | None = None,
+    ) -> str:
+        """Build Google authorization URL with access_type=offline."""
+        params = {"access_type": "offline", "prompt": "consent"}
+        if extra_params:
+            params.update(extra_params)
+        return super().build_authorize_url(redirect_uri, state, pkce, params)
+
+
+class GitHubProvider(OAuthProvider):
+    """GitHub OAuth2 provider.
+
+    GitHub uses a non-standard token exchange (no OIDC) and
+    a separate API endpoint for user info.
+
+    Parameters
+    ----------
+    client_id : str
+        GitHub OAuth2 client ID.
+    client_secret : str
+        GitHub OAuth2 client secret.
+    scopes : list[str], optional
+        Requested scopes (defaults to ``["read:user", "user:email"]``).
+    """
+
+    def __init__(
+        self,
+        client_id: str,
+        client_secret: str = "",
+        scopes: list[str] | None = None,
+    ) -> None:
+        """Initialize GitHub provider."""
+        super().__init__(
+            client_id=client_id,
+            client_secret=client_secret,
+            scopes=scopes or ["read:user", "user:email"],
+            authorize_url="https://github.com/login/oauth/authorize",
+            token_url="https://github.com/login/oauth/access_token",  # noqa: S106
+            userinfo_url="https://api.github.com/user",
+        )
+
+    async def exchange_code(
+        self,
+        code: str,
+        redirect_uri: str,
+        pkce_verifier: str | None = None,
+        nonce: str | None = None,
+    ) -> OAuthTokenSet:
+        """Exchange authorization code for a GitHub access token."""
+        data: dict[str, str] = {
+            "client_id": self.client_id,
+            "client_secret": self.client_secret,
+            "code": code,
+            "redirect_uri": redirect_uri,
+        }
+
+        try:
+            client = await self._get_client()
+            resp = await client.post(
+                self.token_url,
+                data=data,
+                headers={"Accept": "application/json"},
+                timeout=30.0,
+            )
+            resp.raise_for_status()
+            raw = resp.json()
+        except httpx.HTTPStatusError as exc:
+            msg = f"GitHub token exchange failed: {exc.response.status_code}"
+            raise TokenError(msg, provider="github") from exc
+        except httpx.HTTPError as exc:
+            msg = f"GitHub token exchange request failed: {exc}"
+            raise TokenError(msg, provider="github") from exc
+
+        if "error" in raw:
+            msg = f"GitHub token error: {raw.get('error_description', raw['error'])}"
+            raise TokenError(msg, provider="github")
+
+        return OAuthTokenSet(
+            access_token=raw["access_token"],
+            token_type=raw.get("token_type", "bearer"),
+            refresh_token=raw.get("refresh_token"),
+            expires_in=raw.get("expires_in"),
+            scope=raw.get("scope", ""),
+            raw=raw,
+            issued_at=time.time(),
+        )
+
+    async def refresh_tokens(self, refresh_token: str) -> OAuthTokenSet:
+        """Refresh GitHub tokens (GitHub uses token rotation)."""
+        data: dict[str, str] = {
+            "client_id": self.client_id,
+            "client_secret": self.client_secret,
+            "grant_type": "refresh_token",
+            "refresh_token": refresh_token,
+        }
+
+        try:
+            client = await self._get_client()
+            resp = await client.post(
+                self.token_url,
+                data=data,
+                headers={"Accept": "application/json"},
+                timeout=30.0,
+            )
+            resp.raise_for_status()
+            raw = resp.json()
+        except httpx.HTTPError as exc:
+            msg = f"GitHub token refresh failed: {exc}"
+            raise TokenRefreshError(msg, provider="github") from exc
+
+        if "error" in raw:
+            msg = f"GitHub refresh error: {raw.get('error_description', raw['error'])}"
+            raise TokenRefreshError(msg, provider="github")
+
+        return OAuthTokenSet(
+            access_token=raw["access_token"],
+            token_type=raw.get("token_type", "bearer"),
+            refresh_token=raw.get("refresh_token"),
+            expires_in=raw.get("expires_in"),
+            scope=raw.get("scope", ""),
+            raw=raw,
+            issued_at=time.time(),
+        )
+
+    async def revoke_token(self, token: str) -> bool:
+        """Revoke a GitHub token via the Applications API.
+
+        Uses ``DELETE /applications/{client_id}/token`` with HTTP
+        Basic authentication (client_id / client_secret).
+
+        Parameters
+        ----------
+        token : str
+            The access token to revoke.
+
+        Returns
+        -------
+        bool
+            True if GitHub accepted the revocation.
+        """
+        if not self.client_secret:
+            logger.warning("GitHub token revocation requires a client_secret")
+            return False
+        url = f"https://api.github.com/applications/{self.client_id}/token"
+        try:
+            client = await self._get_client()
+            resp = await client.request(
+                "DELETE",
+                url,
+                auth=(self.client_id, self.client_secret),
+                json={"access_token": token},
+                timeout=10.0,
+            )
+        except httpx.HTTPError:
+            return False
+        else:
+            # GitHub returns 204 No Content on success
+            return resp.status_code == 204
+
+
+class MicrosoftProvider(GenericOIDCProvider):
+    """Microsoft / Azure AD OAuth2 provider.
+
+    Parameters
+    ----------
+    client_id : str
+        Azure AD application (client) ID.
+    client_secret : str
+        Azure AD client secret.
+    tenant_id : str
+        Azure AD tenant ID (default "common" for multi-tenant).
+    scopes : list[str], optional
+        Requested scopes.
+    """
+
+    def __init__(
+        self,
+        client_id: str,
+        client_secret: str = "",
+        tenant_id: str = "common",
+        scopes: list[str] | None = None,
+    ) -> None:
+        """Initialize Microsoft provider."""
+        base = f"https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0"
+        super().__init__(
+            client_id=client_id,
+            client_secret=client_secret,
+            scopes=scopes or ["openid", "email", "profile", "offline_access"],
+            authorize_url=f"{base}/authorize",
+            token_url=f"{base}/token",
+            userinfo_url="https://graph.microsoft.com/oidc/userinfo",
+            revocation_url="",  # Microsoft doesn't support standard revocation
+        )
+        self.tenant_id = tenant_id
+
+
+def create_provider_from_settings(settings: Any) -> OAuthProvider:
+    """Create an OAuthProvider instance from OAuth2Settings.
+
+    Parameters
+    ----------
+    settings : OAuth2Settings
+        The OAuth2 configuration settings.
+
+    Returns
+    -------
+    OAuthProvider
+        A configured provider instance.
+
+    Raises
+    ------
+    AuthenticationError
+        If the provider type is unknown or settings are invalid.
+    """
+    provider_type = getattr(settings, "provider", "custom")
+    client_id = getattr(settings, "client_id", "")
+    client_secret = getattr(settings, "client_secret", "")
+    scopes_str = getattr(settings, "scopes", "")
+    scopes = [s.strip() for s in scopes_str.split() if s.strip()] if scopes_str else None
+
+    if provider_type == "google":
+        return GoogleProvider(
+            client_id=client_id,
+            client_secret=client_secret,
+            scopes=scopes,
+        )
+    if provider_type == "github":
+        return GitHubProvider(
+            client_id=client_id,
+            client_secret=client_secret,
+            scopes=scopes,
+        )
+    if provider_type == "microsoft":
+        tenant_id = getattr(settings, "tenant_id", "common")
+        return MicrosoftProvider(
+            client_id=client_id,
+            client_secret=client_secret,
+            tenant_id=tenant_id,
+            scopes=scopes,
+        )
+    if provider_type == "oidc":
+        issuer_url = getattr(settings, "issuer_url", "")
+        return GenericOIDCProvider(
+            client_id=client_id,
+            client_secret=client_secret,
+            issuer_url=issuer_url,
+            scopes=scopes,
+            authorize_url=getattr(settings, "authorize_url", ""),
+            token_url=getattr(settings, "token_url", ""),
+            userinfo_url=getattr(settings, "userinfo_url", ""),
+        )
+    if provider_type == "custom":
+        authorize_url = getattr(settings, "authorize_url", "")
+        token_url = getattr(settings, "token_url", "")
+        if not authorize_url or not token_url:
+            msg = "Custom provider requires authorize_url and token_url"
+            raise AuthenticationError(msg, provider="custom")
+        return GenericOIDCProvider(
+            client_id=client_id,
+            client_secret=client_secret,
+            scopes=scopes,
+            authorize_url=authorize_url,
+            token_url=token_url,
+            userinfo_url=getattr(settings, "userinfo_url", ""),
+        )
+
+    msg = f"Unknown OAuth2 provider type: {provider_type}"
+    raise AuthenticationError(msg, provider=provider_type)
diff --git a/pywry/pywry/auth/session.py b/pywry/pywry/auth/session.py
new file mode 100644
index 0000000..cf536db
--- /dev/null
+++ b/pywry/pywry/auth/session.py
@@ -0,0 +1,258 @@
+"""OAuth2 session manager with automatic token refresh.
+
+Manages the lifecycle of OAuth2 tokens including persistence,
+validation, and background refresh scheduling. Uses threading.Timer
+for refresh scheduling to match the thread-based auth flow pattern.
+"""
+
+# pylint: disable=logging-too-many-args
+
+from __future__ import annotations
+
+import contextlib
+import logging
+import threading
+
+from typing import TYPE_CHECKING
+
+from ..exceptions import TokenExpiredError, TokenRefreshError
+from ..state.sync_helpers import run_async
+
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from ..state.base import SessionStore
+    from ..state.types import OAuthTokenSet
+    from .providers import OAuthProvider
+    from .token_store import TokenStore
+
+
+logger = logging.getLogger("pywry.auth")
+
+
+class SessionManager:
+    """Manages OAuth2 token lifecycle with automatic refresh.
+
+    Parameters
+    ----------
+    provider : OAuthProvider
+        The OAuth2 provider for token refresh.
+    token_store : TokenStore
+        Store for persisting tokens.
+    session_key : str
+        Key used to identify stored tokens (e.g., user ID).
+    session_store : SessionStore, optional
+        Session store for internal session management.
+    refresh_buffer_seconds : int
+        Seconds before token expiry to trigger refresh (default ``60``).
+    on_reauth_required : callable, optional
+        Callback invoked when refresh fails and re-authentication is needed.
+        Signature: ``on_reauth_required() -> None``.
+    """
+
+    def __init__(
+        self,
+        provider: OAuthProvider,
+        token_store: TokenStore,
+        session_key: str = "default",
+        session_store: SessionStore | None = None,
+        refresh_buffer_seconds: int = 60,
+        on_reauth_required: Callable[[], None] | None = None,
+    ) -> None:
+        """Initialize the session manager."""
+        self.provider = provider
+        self.token_store = token_store
+        self.session_key = session_key
+        self.session_store = session_store
+        self.refresh_buffer_seconds = refresh_buffer_seconds
+        self.on_reauth_required = on_reauth_required
+
+        self._refresh_timer: threading.Timer | None = None
+        self._lock = threading.Lock()
+        self._current_tokens: OAuthTokenSet | None = None
+
+    async def initialize(self) -> OAuthTokenSet | None:
+        """Load existing tokens from store and validate.
+
+        Returns
+        -------
+        OAuthTokenSet or None
+            The stored tokens if valid, or None if no tokens
+            are stored or they have expired.
+        """
+        tokens = await self.token_store.load(self.session_key)
+        if tokens is None:
+            return None
+
+        if tokens.is_expired:
+            # Try to refresh
+            if tokens.refresh_token:
+                try:
+                    tokens = await self.provider.refresh_tokens(tokens.refresh_token)
+                    await self.token_store.save(self.session_key, tokens)
+                    self._current_tokens = tokens
+                    self._schedule_refresh(tokens)
+                except Exception as exc:
+                    logger.warning("Token refresh on init failed: %s", exc)
+                    return None
+                return tokens
+            return None
+
+        self._current_tokens = tokens
+        self._schedule_refresh(tokens)
+        return tokens
+
+    async def save_tokens(self, tokens: OAuthTokenSet) -> None:
+        """Persist tokens and schedule background refresh.
+
+        Parameters
+        ----------
+        tokens : OAuthTokenSet
+            The token set to save.
+        """
+        await self.token_store.save(self.session_key, tokens)
+        with self._lock:
+            self._current_tokens = tokens
+        self._schedule_refresh(tokens)
+        logger.debug("Tokens saved for session %s", self.session_key)
+
+    async def get_access_token(self) -> str:
+        """Get a valid access token, refreshing if near expiry.
+
+        Returns
+        -------
+        str
+            A valid access token.
+
+        Raises
+        ------
+        TokenExpiredError
+            If the token is expired and cannot be refreshed.
+        """
+        with self._lock:
+            tokens = self._current_tokens
+
+        if tokens is None:
+            tokens = await self.token_store.load(self.session_key)
+
+        if tokens is None:
+            msg = "No tokens available"
+            raise TokenExpiredError(msg)
+
+        if tokens.is_expired:
+            tokens = await self.refresh()
+
+        return tokens.access_token
+
+    async def refresh(self) -> OAuthTokenSet:
+        """Refresh the access token.
+
+        Uses the stored refresh token to obtain a new access token.
+        Falls back to ``on_reauth_required`` if refresh fails.
+
+        Returns
+        -------
+        OAuthTokenSet
+            A new token set.
+
+        Raises
+        ------
+        TokenRefreshError
+            If refresh fails and no re-auth callback is set.
+        """
+        with self._lock:
+            tokens = self._current_tokens
+
+        if tokens is None:
+            tokens = await self.token_store.load(self.session_key)
+
+        if tokens is None or not tokens.refresh_token:
+            if self.on_reauth_required:
+                self.on_reauth_required()
+                msg = "Re-authentication required"
+            else:
+                msg = "No refresh token available"
+            raise TokenRefreshError(msg)
+
+        try:
+            new_tokens = await self.provider.refresh_tokens(tokens.refresh_token)
+            await self.token_store.save(self.session_key, new_tokens)
+            with self._lock:
+                self._current_tokens = new_tokens
+            self._schedule_refresh(new_tokens)
+            logger.info("Tokens refreshed for session %s", self.session_key)
+        except Exception as exc:
+            logger.exception("Token refresh failed")
+            if self.on_reauth_required:
+                self.on_reauth_required()
+            raise TokenRefreshError(
+                f"Token refresh failed: {exc}",
+                provider=self.provider.__class__.__name__,
+            ) from exc
+
+        return new_tokens
+
+    async def logout(self) -> None:
+        """Clear all tokens and cancel scheduled refresh.
+
+        Optionally revokes the token at the provider.
+        """
+        self._cancel_refresh_timer()
+
+        with self._lock:
+            tokens = self._current_tokens
+            self._current_tokens = None
+
+        # Best-effort token revocation
+        if tokens and tokens.access_token:
+            with contextlib.suppress(Exception):
+                await self.provider.revoke_token(tokens.access_token)
+
+        await self.token_store.delete(self.session_key)
+        logger.info("Session %s logged out", self.session_key)
+
+    def _schedule_refresh(self, tokens: OAuthTokenSet) -> None:
+        """Schedule a background token refresh before expiry.
+
+        Parameters
+        ----------
+        tokens : OAuthTokenSet
+            The current tokens (used to calculate refresh timing).
+        """
+        self._cancel_refresh_timer()
+
+        if tokens.expires_at is None:
+            return  # No expiry, no need to refresh
+
+        import time
+
+        delay = tokens.expires_at - time.time() - self.refresh_buffer_seconds
+        if delay <= 0:
+            # Already near/past expiry — refresh immediately
+            delay = 1.0
+
+        logger.debug(
+            "Scheduling token refresh in %.0fs for session %s",
+            delay,
+            self.session_key,
+        )
+
+        self._refresh_timer = threading.Timer(delay, self._do_background_refresh)
+        self._refresh_timer.daemon = True
+        self._refresh_timer.start()
+
+    def _do_background_refresh(self) -> None:
+        """Execute a background token refresh (runs on Timer thread)."""
+        try:
+            run_async(self.refresh(), timeout=30.0)
+        except Exception:
+            logger.exception("Background token refresh failed")
+            if self.on_reauth_required:
+                self.on_reauth_required()
+
+    def _cancel_refresh_timer(self) -> None:
+        """Cancel any pending refresh timer."""
+        if self._refresh_timer is not None:
+            self._refresh_timer.cancel()
+            self._refresh_timer = None
diff --git a/pywry/pywry/auth/token_store.py b/pywry/pywry/auth/token_store.py
new file mode 100644
index 0000000..87df149
--- /dev/null
+++ b/pywry/pywry/auth/token_store.py
@@ -0,0 +1,349 @@
+"""Pluggable token storage backends.
+
+Provides TokenStore ABC and concrete implementations for
+in-memory, OS keyring, and Redis-backed token persistence.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import logging
+import threading
+import time
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from ..state.types import OAuthTokenSet
+
+
+logger = logging.getLogger("pywry.auth")
+
+
+class TokenStore(ABC):
+    """Abstract base class for OAuth2 token storage.
+
+    All methods are async to support both local and network-backed stores.
+    """
+
+    @abstractmethod
+    async def save(self, key: str, tokens: OAuthTokenSet) -> None:
+        """Save tokens under the given key.
+
+        Parameters
+        ----------
+        key : str
+            Unique identifier (e.g., user ID or session key).
+        tokens : OAuthTokenSet
+            The token set to persist.
+        """
+
+    @abstractmethod
+    async def load(self, key: str) -> OAuthTokenSet | None:
+        """Load tokens for the given key.
+
+        Parameters
+        ----------
+        key : str
+            Unique identifier.
+
+        Returns
+        -------
+        OAuthTokenSet or None
+            The stored token set, or None if not found.
+        """
+
+    @abstractmethod
+    async def delete(self, key: str) -> None:
+        """Delete tokens for the given key.
+
+        Parameters
+        ----------
+        key : str
+            Unique identifier.
+        """
+
+    @abstractmethod
+    async def exists(self, key: str) -> bool:
+        """Check if tokens exist for the given key.
+
+        Parameters
+        ----------
+        key : str
+            Unique identifier.
+
+        Returns
+        -------
+        bool
+            True if tokens are stored for this key.
+        """
+
+    @abstractmethod
+    async def list_keys(self) -> list[str]:
+        """List all stored token keys.
+
+        Returns
+        -------
+        list[str]
+            All keys with stored tokens.
+        """
+
+
+def _serialize_tokens(tokens: OAuthTokenSet) -> str:
+    """Serialize an OAuthTokenSet to JSON."""
+    return json.dumps(
+        {
+            "access_token": tokens.access_token,
+            "token_type": tokens.token_type,
+            "refresh_token": tokens.refresh_token,
+            "expires_in": tokens.expires_in,
+            "id_token": tokens.id_token,
+            "scope": tokens.scope,
+            "raw": tokens.raw,
+            "issued_at": tokens.issued_at,
+        }
+    )
+
+
+def _deserialize_tokens(data: str) -> OAuthTokenSet:
+    """Deserialize an OAuthTokenSet from JSON."""
+    obj = json.loads(data)
+    return OAuthTokenSet(
+        access_token=obj["access_token"],
+        token_type=obj.get("token_type", "Bearer"),
+        refresh_token=obj.get("refresh_token"),
+        expires_in=obj.get("expires_in"),
+        id_token=obj.get("id_token"),
+        scope=obj.get("scope", ""),
+        raw=obj.get("raw", {}),
+        issued_at=obj.get("issued_at", time.time()),
+    )
+
+
+class MemoryTokenStore(TokenStore):
+    """In-memory token store for development and single-process use.
+
+    Thread-safe via asyncio.Lock, same pattern as MemorySessionStore.
+    """
+
+    def __init__(self) -> None:
+        """Initialize the memory token store."""
+        self._tokens: dict[str, str] = {}
+        self._lock = asyncio.Lock()
+
+    async def save(self, key: str, tokens: OAuthTokenSet) -> None:
+        """Save tokens in memory."""
+        async with self._lock:
+            self._tokens[key] = _serialize_tokens(tokens)
+
+    async def load(self, key: str) -> OAuthTokenSet | None:
+        """Load tokens from memory."""
+        async with self._lock:
+            data = self._tokens.get(key)
+            if data is None:
+                return None
+            return _deserialize_tokens(data)
+
+    async def delete(self, key: str) -> None:
+        """Delete tokens from memory."""
+        async with self._lock:
+            self._tokens.pop(key, None)
+
+    async def exists(self, key: str) -> bool:
+        """Check if tokens exist in memory."""
+        async with self._lock:
+            return key in self._tokens
+
+    async def list_keys(self) -> list[str]:
+        """List all token keys in memory."""
+        async with self._lock:
+            return list(self._tokens.keys())
+
+
+class KeyringTokenStore(TokenStore):
+    """OS keyring-backed token store for persistent native credentials.
+
+    Requires the ``keyring`` package: ``pip install pywry[auth]``
+
+    Parameters
+    ----------
+    service_name : str
+        Service name for keyring storage (default "pywry-oauth").
+    """
+
+    def __init__(self, service_name: str = "pywry-oauth") -> None:
+        """Initialize the keyring token store."""
+        try:
+            import keyring as _keyring
+        except ImportError:
+            msg = "Install keyring for persistent token storage: pip install pywry[auth]"
+            raise ImportError(msg) from None
+        self._service_name = service_name
+        self._keyring = _keyring
+
+    async def save(self, key: str, tokens: OAuthTokenSet) -> None:
+        """Save tokens to the OS keyring."""
+        data = _serialize_tokens(tokens)
+        loop = asyncio.get_event_loop()
+        await loop.run_in_executor(None, self._keyring.set_password, self._service_name, key, data)
+
+    async def load(self, key: str) -> OAuthTokenSet | None:
+        """Load tokens from the OS keyring."""
+        loop = asyncio.get_event_loop()
+        data = await loop.run_in_executor(None, self._keyring.get_password, self._service_name, key)
+        if data is None:
+            return None
+        return _deserialize_tokens(data)
+
+    async def delete(self, key: str) -> None:
+        """Delete tokens from the OS keyring."""
+        loop = asyncio.get_event_loop()
+        with contextlib.suppress(Exception):
+            await loop.run_in_executor(None, self._keyring.delete_password, self._service_name, key)
+
+    async def exists(self, key: str) -> bool:
+        """Check if tokens exist in the OS keyring."""
+        result = await self.load(key)
+        return result is not None
+
+    async def list_keys(self) -> list[str]:
+        """List keys (not supported by all keyring backends).
+
+        Returns an empty list as the keyring API does not provide
+        a standard way to enumerate entries.
+        """
+        return []
+
+
+class RedisTokenStore(TokenStore):
+    """Redis-backed token store for multi-worker deployments.
+
+    Uses Redis hash keys with optional TTL based on token ``expires_in``.
+
+    Parameters
+    ----------
+    redis_url : str
+        Redis connection URL.
+    prefix : str
+        Key prefix for namespacing (default "pywry").
+    pool_size : int
+        Connection pool size (default 10).
+    """
+
+    def __init__(
+        self,
+        redis_url: str = "redis://localhost:6379/0",
+        prefix: str = "pywry",
+        pool_size: int = 10,
+    ) -> None:
+        """Initialize the Redis token store."""
+        try:
+            from redis.asyncio import Redis as RedisClient
+        except ImportError:
+            msg = "Redis backend requires the 'redis' package. Install with: pip install redis"
+            raise ImportError(msg) from None
+
+        self._prefix = prefix
+        self._redis: Any = RedisClient.from_url(
+            redis_url,
+            max_connections=pool_size,
+            decode_responses=True,
+        )
+
+    def _key(self, key: str) -> str:
+        """Build a Redis key with prefix."""
+        return f"{self._prefix}:oauth:tokens:{key}"
+
+    async def save(self, key: str, tokens: OAuthTokenSet) -> None:
+        """Save tokens to Redis with optional TTL."""
+        redis_key = self._key(key)
+        data = _serialize_tokens(tokens)
+        if tokens.expires_in is not None and tokens.expires_in > 0:
+            # Set TTL slightly longer than token expiry to allow refresh
+            ttl = tokens.expires_in + 300  # 5 min buffer
+            await self._redis.setex(redis_key, ttl, data)
+        else:
+            await self._redis.set(redis_key, data)
+
+    async def load(self, key: str) -> OAuthTokenSet | None:
+        """Load tokens from Redis."""
+        data = await self._redis.get(self._key(key))
+        if data is None:
+            return None
+        return _deserialize_tokens(data)
+
+    async def delete(self, key: str) -> None:
+        """Delete tokens from Redis."""
+        await self._redis.delete(self._key(key))
+
+    async def exists(self, key: str) -> bool:
+        """Check if tokens exist in Redis."""
+        return bool(await self._redis.exists(self._key(key)))
+
+    async def list_keys(self) -> list[str]:
+        """List all token keys in Redis."""
+        pattern = f"{self._prefix}:oauth:tokens:*"
+        prefix_len = len(f"{self._prefix}:oauth:tokens:")
+        return [key[prefix_len:] async for key in self._redis.scan_iter(match=pattern)]
+
+
+_token_store_instance: TokenStore | None = None
+_token_store_lock = threading.Lock()
+
+
+def get_token_store(backend: str = "memory", **kwargs: Any) -> TokenStore:
+    """Factory function for token stores.
+
+    Returns a singleton instance. Call ``reset_token_store()`` to clear
+    the cached instance (e.g. in tests).
+
+    Parameters
+    ----------
+    backend : str
+        Storage backend: "memory", "keyring", or "redis".
+    **kwargs : Any
+        Additional keyword arguments passed to the store constructor.
+
+    Returns
+    -------
+    TokenStore
+        A configured token store instance.
+    """
+    global _token_store_instance  # noqa: PLW0603
+
+    with _token_store_lock:
+        if _token_store_instance is not None:
+            return _token_store_instance
+
+        if backend == "memory":
+            _token_store_instance = MemoryTokenStore()
+        elif backend == "keyring":
+            service_name = kwargs.get("service_name", "pywry-oauth")
+            _token_store_instance = KeyringTokenStore(service_name=service_name)
+        elif backend == "redis":
+            redis_url = kwargs.get("redis_url", "redis://localhost:6379/0")
+            prefix = kwargs.get("prefix", "pywry")
+            pool_size = kwargs.get("pool_size", 10)
+            _token_store_instance = RedisTokenStore(
+                redis_url=redis_url,
+                prefix=prefix,
+                pool_size=pool_size,
+            )
+        else:
+            msg = f"Unknown token store backend: {backend}"
+            raise ValueError(msg)
+
+        return _token_store_instance
+
+
+def reset_token_store() -> None:
+    """Reset the singleton token store instance.
+
+    Useful for tests that need a fresh token store between runs.
+    """
+    global _token_store_instance  # noqa: PLW0603
+
+    with _token_store_lock:
+        _token_store_instance = None
diff --git a/pywry/pywry/cli.py b/pywry/pywry/cli.py
index 4b88679..cb81873 100644
--- a/pywry/pywry/cli.py
+++ b/pywry/pywry/cli.py
@@ -357,58 +357,41 @@ def format_config_show(settings: PyWrySettings) -> str:
     str
         Formatted configuration string.
     """
+    from .config import _REDACTED, _SENSITIVE_FIELDS
+
     lines = []
     lines.append("PyWry Configuration\n" + "=" * 40 + "\n")
 
-    # Security (CSP)
-    lines.append("[csp]")
-    for field, value in settings.csp.model_dump().items():
-        lines.append(f"  {field} = {value!r}")
-
-    # Theme
-    lines.append("\n[theme]")
-    for field, value in settings.theme.model_dump().items():
-        lines.append(f"  {field} = {value!r}")
-
-    # Timeout
-    lines.append("\n[timeout]")
-    for field, value in settings.timeout.model_dump().items():
-        lines.append(f"  {field} = {value!r}")
-
-    # Assets
-    lines.append("\n[asset]")
-    for field, value in settings.asset.model_dump().items():
-        lines.append(f"  {field} = {value!r}")
-
-    # Logging
-    lines.append("\n[log]")
-    for field, value in settings.log.model_dump().items():
-        lines.append(f"  {field} = {value!r}")
-
-    # Window
-    lines.append("\n[window]")
-    for field, value in settings.window.model_dump().items():
-        lines.append(f"  {field} = {value!r}")
-
-    # Hot Reload
-    lines.append("\n[hot_reload]")
-    for field, value in settings.hot_reload.model_dump().items():
-        lines.append(f"  {field} = {value!r}")
-
-    # Server
-    lines.append("\n[server]")
-    for field, value in settings.server.model_dump().items():
-        lines.append(f"  {field} = {value!r}")
-
-    # Deploy
-    lines.append("\n[deploy]")
-    for field, value in settings.deploy.model_dump().items():
-        lines.append(f"  {field} = {value!r}")
-
-    # MCP
-    lines.append("\n[mcp]")
-    for field, value in settings.mcp.model_dump().items():
-        lines.append(f"  {field} = {value!r}")
+    section_names = [
+        "csp",
+        "theme",
+        "timeout",
+        "asset",
+        "log",
+        "window",
+        "hot_reload",
+        "server",
+        "deploy",
+        "mcp",
+    ]
+    all_data = settings.model_dump(
+        exclude=dict.fromkeys(section_names, _SENSITIVE_FIELDS),
+    )
+
+    for section_name in section_names:
+        section_data = all_data.get(section_name, {})
+        if lines[-1] != "":
+            lines.append("")
+        lines.append(f"[{section_name}]")
+        for field_name, field_value in section_data.items():
+            lines.append(f"  {field_name} = {field_value!r}")
+        # Append redacted placeholders for any sensitive fields defined
+        # on this section's model class.
+        section_cls = type(getattr(settings, section_name))
+        lines.extend(
+            f"  {rn} = '{_REDACTED}'"
+            for rn in sorted(_SENSITIVE_FIELDS & section_cls.model_fields.keys())
+        )
 
     return "\n".join(lines)
 
diff --git a/pywry/pywry/commands/__init__.py b/pywry/pywry/commands/__init__.py
index 840dda2..5b9674b 100644
--- a/pywry/pywry/commands/__init__.py
+++ b/pywry/pywry/commands/__init__.py
@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import contextlib
 import json
 import subprocess
 import sys
@@ -262,6 +263,20 @@ def handle_window_close(label: str) -> dict[str, Any]:
     """
     debug(f"Window '{label}' closing - destroying resources")
 
+    # Fire on_close lifecycle callbacks
+    try:
+        from ..window_manager.lifecycle import get_lifecycle
+
+        lifecycle = get_lifecycle()
+        resources = lifecycle._windows.get(label)
+        if resources is not None:
+            resources.close_reason = "user_closed"
+            for callback in resources.on_close:
+                with contextlib.suppress(Exception):
+                    callback(label, "user_closed")
+    except Exception:
+        debug(f"Error during window close handler for {label}")
+
     # Dispatch close event first (in case handlers want to save state)
     get_registry().dispatch(label, "pywry:close", {"label": label})
 
diff --git a/pywry/pywry/config.py b/pywry/pywry/config.py
index b77c877..100b565 100644
--- a/pywry/pywry/config.py
+++ b/pywry/pywry/config.py
@@ -11,6 +11,8 @@
 Example: PYWRY_CSP__CONNECT_SRC, PYWRY_TIMEOUT__STARTUP
 """
 
+# pylint: disable=too-many-lines
+
 from __future__ import annotations
 
 import os
@@ -101,6 +103,17 @@ def _deep_merge(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any
     return result
 
 
+# Field names that contain sensitive data and must be redacted in output.
+_SENSITIVE_FIELDS: set[str] = {
+    "client_secret",
+    "ssl_keyfile_password",
+    "internal_api_token",
+    "redis_url",
+}
+
+_REDACTED = "********"
+
+
 class SecuritySettings(BaseSettings):
     """Content Security Policy settings.
 
@@ -464,6 +477,139 @@ def parse_comma_separated(cls, v: Any) -> list[str]:
             return [s.strip() for s in v.split(",") if s.strip()]
         return v or []
 
+    # OAuth2 integration
+    oauth2_login_path: str = Field(
+        default="/auth/login",
+        description="Path for the OAuth2 login endpoint in deploy mode",
+    )
+    oauth2_callback_path: str = Field(
+        default="/auth/callback",
+        description="Path for the OAuth2 callback endpoint in deploy mode",
+    )
+    auth_public_paths: Annotated[list[str], NoDecode] = Field(
+        default_factory=lambda: ["/auth/login", "/auth/callback", "/auth/status"],
+        description="Paths that do not require authentication (pre-auth routes)",
+    )
+
+    # Security: explicit redirect URI and HTTPS enforcement
+    auth_redirect_uri: str = Field(
+        default="",
+        description=(
+            "Explicit OAuth2 redirect URI for deploy mode. "
+            "When set, overrides request-derived Host header to prevent poisoning. "
+            "Example: https://myapp.example.com/auth/callback"
+        ),
+    )
+    force_https: bool = Field(
+        default=False,
+        description=(
+            "Enforce HTTPS for redirect URIs and cookies in deploy mode. "
+            "Should be True in production. When False, allows localhost HTTP for development."
+        ),
+    )
+
+    @field_validator("auth_public_paths", mode="before")
+    @classmethod
+    def parse_public_paths(cls, v: Any) -> list[str]:
+        """Parse comma-separated strings from env vars."""
+        if isinstance(v, str):
+            return [s.strip() for s in v.split(",") if s.strip()]
+        return v or []
+
+
+class OAuth2Settings(BaseSettings):
+    """OAuth2 authentication configuration.
+
+    Environment prefix: PYWRY_OAUTH2__
+    Example: PYWRY_OAUTH2__CLIENT_ID=your-client-id
+    Example: PYWRY_OAUTH2__PROVIDER=google
+
+    TOML section: [tool.pywry.oauth2]
+    """
+
+    model_config = SettingsConfigDict(
+        env_prefix="PYWRY_OAUTH2__",
+        extra="ignore",
+    )
+
+    # Provider selection
+    provider: Literal["google", "github", "microsoft", "oidc", "custom"] = Field(
+        default="custom",
+        description="OAuth2 provider type: google, github, microsoft, oidc, or custom",
+    )
+
+    # Client credentials
+    client_id: str = Field(
+        default="",
+        description="OAuth2 client ID from the provider",
+    )
+    client_secret: str = Field(
+        default="",
+        description="OAuth2 client secret (empty for public clients with PKCE)",
+    )
+
+    # Scopes
+    scopes: str = Field(
+        default="openid email profile",
+        description="Space-separated OAuth2 scopes to request",
+    )
+
+    # Endpoint URLs (required for custom/oidc providers)
+    authorize_url: str = Field(
+        default="",
+        description="Authorization endpoint URL (required for custom provider)",
+    )
+    token_url: str = Field(
+        default="",
+        description="Token exchange endpoint URL (required for custom provider)",
+    )
+    userinfo_url: str = Field(
+        default="",
+        description="User info endpoint URL (optional)",
+    )
+    issuer_url: str = Field(
+        default="",
+        description="OIDC issuer URL for auto-discovery (used by oidc provider)",
+    )
+
+    # Provider-specific
+    tenant_id: str = Field(
+        default="common",
+        description="Azure AD tenant ID (for Microsoft provider)",
+    )
+
+    # PKCE
+    use_pkce: bool = Field(
+        default=True,
+        description="Use PKCE (Proof Key for Code Exchange) for public clients",
+    )
+
+    # Token storage
+    token_store_backend: Literal["memory", "keyring", "redis"] = Field(
+        default="memory",
+        description="Token storage backend: memory, keyring, or redis",
+    )
+
+    # Timeouts
+    auth_timeout_seconds: float = Field(
+        default=120.0,
+        ge=10.0,
+        description="Maximum seconds to wait for OAuth2 callback",
+    )
+    refresh_buffer_seconds: int = Field(
+        default=60,
+        ge=10,
+        description="Seconds before token expiry to trigger background refresh",
+    )
+
+    @field_validator("client_id")
+    @classmethod
+    def validate_custom_provider(cls, v: str, info: Any) -> str:  # pylint: disable=unused-argument
+        """Validate that required fields are set for custom providers."""
+        # Validation happens at usage time rather than init time
+        # to allow partial configuration via env vars
+        return v
+
 
 class ServerSettings(BaseSettings):
     """Inline server settings for notebook/web mode.
@@ -758,6 +904,10 @@ class PyWrySettings(BaseSettings):
     server: ServerSettings = Field(default_factory=ServerSettings)
     deploy: DeploySettings = Field(default_factory=DeploySettings)
     mcp: MCPSettings = Field(default_factory=MCPSettings)
+    oauth2: OAuth2Settings | None = Field(
+        default=None,
+        description="OAuth2 authentication settings (None to disable)",
+    )
 
     # Tracks where each value came from (for CLI display)
     _sources: ClassVar[dict[str, str]] = {}
@@ -769,28 +919,44 @@ def __init__(self, **data: Any) -> None:
         # Merge TOML config with explicit data (explicit takes precedence)
         merged = _deep_merge(toml_config, data)
 
+        # Auto-detect OAuth2 env vars: if PYWRY_OAUTH2__CLIENT_ID is set
+        # and oauth2 wasn't explicitly provided, instantiate OAuth2Settings
+        # so env-var based configuration works out of the box.
+        if ("oauth2" not in merged or merged["oauth2"] is None) and os.environ.get(
+            "PYWRY_OAUTH2__CLIENT_ID"
+        ):
+            merged["oauth2"] = OAuth2Settings()
+
         super().__init__(**merged)
 
     def to_toml(self) -> str:
         """Export settings as TOML string."""
         lines = ["# PyWry Configuration", "# Generated by: pywry config --toml", ""]
 
-        sections = [
-            ("csp", self.csp),
-            ("theme", self.theme),
-            ("timeout", self.timeout),
-            ("asset", self.asset),
-            ("log", self.log),
-            ("window", self.window),
-            ("hot_reload", self.hot_reload),
-            ("server", self.server),
-            ("deploy", self.deploy),
-            ("mcp", self.mcp),
+        section_names = [
+            "csp",
+            "theme",
+            "timeout",
+            "asset",
+            "log",
+            "window",
+            "hot_reload",
+            "server",
+            "deploy",
+            "mcp",
         ]
 
-        for section_name, section in sections:
+        if self.oauth2 is not None:
+            section_names.append("oauth2")
+
+        all_data = self.model_dump(
+            exclude=dict.fromkeys(section_names, _SENSITIVE_FIELDS),
+        )
+
+        for section_name in section_names:
+            section_data = all_data.get(section_name, {})
             lines.append(f"[{section_name}]")
-            for field_name, field_value in section.model_dump().items():
+            for field_name, field_value in section_data.items():
                 if isinstance(field_value, list):
                     value_str = "[" + ", ".join(f'"{v}"' for v in field_value) + "]"
                 elif isinstance(field_value, bool):
@@ -800,6 +966,13 @@ def to_toml(self) -> str:
                 else:
                     value_str = str(field_value)
                 lines.append(f"{field_name} = {value_str}")
+            # Append redacted placeholders for any sensitive fields defined
+            # on this section's model class.
+            section_cls = type(getattr(self, section_name))
+            lines.extend(
+                f'{rn} = "{_REDACTED}"'
+                for rn in sorted(_SENSITIVE_FIELDS & section_cls.model_fields.keys())
+            )
             lines.append("")
 
         return "\n".join(lines)
@@ -812,22 +985,28 @@ def to_env(self) -> str:
             "",
         ]
 
-        sections = [
-            ("CSP", self.csp),
-            ("THEME", self.theme),
-            ("TIMEOUT", self.timeout),
-            ("ASSET", self.asset),
-            ("LOG", self.log),
-            ("WINDOW", self.window),
-            ("HOT_RELOAD", self.hot_reload),
-            ("SERVER", self.server),
-            ("DEPLOY", self.deploy),
-            ("MCP", self.mcp),
+        env_sections = [
+            ("CSP", "csp"),
+            ("THEME", "theme"),
+            ("TIMEOUT", "timeout"),
+            ("ASSET", "asset"),
+            ("LOG", "log"),
+            ("WINDOW", "window"),
+            ("HOT_RELOAD", "hot_reload"),
+            ("SERVER", "server"),
+            ("DEPLOY", "deploy"),
+            ("MCP", "mcp"),
         ]
 
-        for section_name, section in sections:
-            for field_name, field_value in section.model_dump().items():
-                env_name = f"PYWRY_{section_name}__{field_name.upper()}"
+        # Dump from top-level model to avoid tainted section instances.
+        all_data = self.model_dump(
+            exclude={attr: _SENSITIVE_FIELDS for _, attr in env_sections},
+        )
+
+        for env_prefix, attr_name in env_sections:
+            section_data = all_data.get(attr_name, {})
+            for field_name, field_value in section_data.items():
+                env_name = f"PYWRY_{env_prefix}__{field_name.upper()}"
                 if isinstance(field_value, list):
                     value_str = ",".join(str(v) for v in field_value)
                 elif isinstance(field_value, bool):
@@ -835,6 +1014,10 @@ def to_env(self) -> str:
                 else:
                     value_str = str(field_value)
                 lines.append(f'export {env_name}="{value_str}"')
+            section_cls = type(getattr(self, attr_name))
+            for redacted_name in sorted(_SENSITIVE_FIELDS & section_cls.model_fields.keys()):
+                env_name = f"PYWRY_{env_prefix}__{redacted_name.upper()}"
+                lines.append(f'export {env_name}="{_REDACTED}"')
 
         return "\n".join(lines)
 
@@ -842,28 +1025,39 @@ def show(self) -> str:
         """Format settings as a readable table."""
         lines = ["PyWry Configuration", "=" * 60, ""]
 
-        sections = [
-            ("Security (CSP)", self.csp),
-            ("Theme", self.theme),
-            ("Timeouts", self.timeout),
-            ("Assets", self.asset),
-            ("Logging", self.log),
-            ("Window Defaults", self.window),
-            ("Hot Reload", self.hot_reload),
-            ("Server (Notebook/Web)", self.server),
-            ("Deploy (Scalable)", self.deploy),
-            ("MCP (AI Agents)", self.mcp),
+        show_sections = [
+            ("Security (CSP)", "csp"),
+            ("Theme", "theme"),
+            ("Timeouts", "timeout"),
+            ("Assets", "asset"),
+            ("Logging", "log"),
+            ("Window Defaults", "window"),
+            ("Hot Reload", "hot_reload"),
+            ("Server (Notebook/Web)", "server"),
+            ("Deploy (Scalable)", "deploy"),
+            ("MCP (AI Agents)", "mcp"),
         ]
 
-        for section_name, section in sections:
-            lines.append(f"\n{section_name}")
+        # Dump from top-level model to avoid tainted section instances.
+        all_data = self.model_dump(
+            exclude={attr: _SENSITIVE_FIELDS for _, attr in show_sections},
+        )
+
+        for display_name, attr_name in show_sections:
+            section_data = all_data.get(attr_name, {})
+            lines.append(f"\n{display_name}")
             lines.append("-" * 40)
-            for field_name, field_value in section.model_dump().items():
+            for field_name, field_value in section_data.items():
                 # Truncate long values
                 value_str = str(field_value)
                 if len(value_str) > 50:
                     value_str = value_str[:47] + "..."
                 lines.append(f"  {field_name:20} = {value_str}")
+            section_cls = type(getattr(self, attr_name))
+            lines.extend(
+                f"  {rn:20} = {_REDACTED}"
+                for rn in sorted(_SENSITIVE_FIELDS & section_cls.model_fields.keys())
+            )
 
         return "\n".join(lines)
 
diff --git a/pywry/pywry/exceptions.py b/pywry/pywry/exceptions.py
index 6ba5b7d..e8138d2 100644
--- a/pywry/pywry/exceptions.py
+++ b/pywry/pywry/exceptions.py
@@ -176,3 +176,99 @@ def __init__(self, message: str, exit_code: int | None = None, **context: Any) -
         """
         super().__init__(message, exit_code=exit_code, **context)
         self.exit_code = exit_code
+
+
+class AuthenticationError(PyWryException):
+    """Base exception for all authentication failures.
+
+    Raised when an authentication operation fails, including
+    OAuth2 flows, token validation, or session management.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        provider: str | None = None,
+        flow_id: str | None = None,
+        **context: Any,
+    ) -> None:
+        """Initialize authentication error.
+
+        Parameters
+        ----------
+        message : str
+            Human-readable error message.
+        provider : str, optional
+            The OAuth2 provider name (e.g., "google", "github").
+        flow_id : str, optional
+            The unique identifier of the auth flow that failed.
+        **context : Any
+            Additional context.
+        """
+        super().__init__(message, provider=provider, flow_id=flow_id, **context)
+        self.provider = provider
+        self.flow_id = flow_id
+
+
+class AuthFlowCancelled(AuthenticationError):
+    """Authentication flow was cancelled.
+
+    Raised when the user closes the authentication window
+    or explicitly aborts the login flow.
+    """
+
+
+class AuthFlowTimeout(AuthenticationError):
+    """Authentication flow timed out.
+
+    Raised when the blocking wait for OAuth2 callback
+    exceeds the configured timeout.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        timeout: float,
+        provider: str | None = None,
+        flow_id: str | None = None,
+        **context: Any,
+    ) -> None:
+        """Initialize timeout error.
+
+        Parameters
+        ----------
+        message : str
+            Human-readable error message.
+        timeout : float
+            The timeout value in seconds.
+        provider : str, optional
+            The OAuth2 provider name.
+        flow_id : str, optional
+            The unique identifier of the auth flow.
+        **context : Any
+            Additional context.
+        """
+        super().__init__(message, provider=provider, flow_id=flow_id, timeout=timeout, **context)
+        self.timeout = timeout
+
+
+class TokenError(AuthenticationError):
+    """Base exception for token-related failures.
+
+    Raised when token operations (validation, refresh, exchange) fail.
+    """
+
+
+class TokenExpiredError(TokenError):
+    """Token has expired.
+
+    Raised when an access or refresh token is past its expiry time.
+    """
+
+
+class TokenRefreshError(TokenError):
+    """Token refresh failed.
+
+    Raised when attempting to refresh an expired access token
+    using a refresh token fails.
+    """
diff --git a/pywry/pywry/frontend/src/auth-helpers.js b/pywry/pywry/frontend/src/auth-helpers.js
new file mode 100644
index 0000000..e55a2fe
--- /dev/null
+++ b/pywry/pywry/frontend/src/auth-helpers.js
@@ -0,0 +1,135 @@
+// PyWry Auth Helpers
+// Provides window.pywry.auth namespace for frontend authentication support
+
+(function() {
+  'use strict';
+
+  // Initialize auth namespace
+  window.pywry = window.pywry || {};
+  window.pywry.auth = {
+    _stateChangeHandlers: [],
+
+    /**
+     * Get the current authentication state.
+     * @returns {{ authenticated: boolean, user_id?: string, roles?: string[], token_type?: string }}
+     */
+    getState: function() {
+      var authData = window.__PYWRY_AUTH__;
+      if (!authData) {
+        return { authenticated: false };
+      }
+      return {
+        authenticated: true,
+        user_id: authData.user_id || null,
+        roles: authData.roles || [],
+        token_type: authData.token_type || 'Bearer'
+      };
+    },
+
+    /**
+     * Check if the user is currently authenticated.
+     * @returns {boolean}
+     */
+    isAuthenticated: function() {
+      return !!window.__PYWRY_AUTH__;
+    },
+
+    /**
+     * Initiate a login flow.
+     * In deploy mode, navigates to /auth/login.
+     * In native mode, sends a login request event to the backend.
+     */
+    login: function() {
+      if (window.pywry && window.pywry.sendEvent) {
+        window.pywry.sendEvent('auth:login-request', {});
+      } else {
+        // Fallback: navigate to login URL
+        window.location.href = '/auth/login';
+      }
+    },
+
+    /**
+     * Initiate a logout flow.
+     * In deploy mode, posts to /auth/logout.
+     * In native mode, sends a logout event to the backend.
+     */
+    logout: function() {
+      if (window.pywry && window.pywry.sendEvent) {
+        window.pywry.sendEvent('auth:logout-request', {});
+      } else {
+        // Fallback: POST to logout endpoint
+        fetch('/auth/logout', { method: 'POST', credentials: 'same-origin' })
+          .then(function() {
+            window.__PYWRY_AUTH__ = null;
+            window.pywry.auth._notifyStateChange();
+            window.location.reload();
+          })
+          .catch(function(err) {
+            console.error('Logout failed:', err);
+          });
+      }
+    },
+
+    /**
+     * Register a callback for authentication state changes.
+     * @param {function} callback - Called with the new auth state
+     */
+    onAuthStateChange: function(callback) {
+      if (typeof callback === 'function') {
+        this._stateChangeHandlers.push(callback);
+      }
+    },
+
+    /**
+     * Notify all state change handlers.
+     * @private
+     */
+    _notifyStateChange: function() {
+      var state = this.getState();
+      for (var i = 0; i < this._stateChangeHandlers.length; i++) {
+        try {
+          this._stateChangeHandlers[i](state);
+        } catch (e) {
+          console.error('Auth state change handler error:', e);
+        }
+      }
+    }
+  };
+
+  // Listen for auth events from the backend
+  if (window.pywry && window.pywry.on) {
+    window.pywry.on('auth:token-refresh', function(data) {
+      if (window.__PYWRY_AUTH__) {
+        window.__PYWRY_AUTH__.token_type = data.token_type || window.__PYWRY_AUTH__.token_type;
+      }
+      window.pywry.auth._notifyStateChange();
+    });
+
+    window.pywry.on('auth:logout', function() {
+      window.__PYWRY_AUTH__ = null;
+      window.pywry.auth._notifyStateChange();
+    });
+
+    window.pywry.on('auth:state-changed', function(data) {
+      if (data && data.authenticated) {
+        window.__PYWRY_AUTH__ = {
+          user_id: data.user_id,
+          roles: data.roles || [],
+          token_type: data.token_type || 'Bearer'
+        };
+      } else {
+        window.__PYWRY_AUTH__ = null;
+      }
+      window.pywry.auth._notifyStateChange();
+    });
+  }
+
+  // Dispatch custom DOM event for framework integration
+  document.addEventListener('DOMContentLoaded', function() {
+    if (window.__PYWRY_AUTH__) {
+      document.dispatchEvent(new CustomEvent('pywry:auth-ready', {
+        detail: window.pywry.auth.getState()
+      }));
+    }
+  });
+})();
diff --git a/pywry/pywry/inline.py b/pywry/pywry/inline.py
index 6eed60d..eddd158 100644
--- a/pywry/pywry/inline.py
+++ b/pywry/pywry/inline.py
@@ -1236,11 +1236,30 @@ def _get_app() -> FastAPI:  # noqa: C901, PLR0915  # pylint: disable=too-many-st
     app = FastAPI(lifespan=_lifespan)
     settings = get_settings().server
 
-    # CORS middleware with configurable settings
+    # ── CORS policy ──────────────────────────────────────────────────
+    # When auth is enabled, disallow wildcard origins with credentials
+    # (violates CORS spec and browsers will reject the response).
+    pywry_settings = get_settings()
+    deploy_settings = pywry_settings.deploy
+
+    cors_origins = list(settings.cors_origins)
+    cors_allow_credentials = settings.cors_allow_credentials
+
+    if deploy_settings.auth_enabled:
+        if cors_origins == ["*"] and cors_allow_credentials:
+            import logging as _cors_log
+
+            _cors_log.getLogger("pywry.auth").warning(
+                "cors_origins=['*'] with auth_enabled=True is insecure. "
+                "Setting cors_allow_credentials=False. Configure explicit "
+                "cors_origins for credentialed cross-origin requests."
+            )
+            cors_allow_credentials = False
+
     app.add_middleware(
         CORSMiddleware,
-        allow_origins=settings.cors_origins,
-        allow_credentials=settings.cors_allow_credentials,
+        allow_origins=cors_origins,
+        allow_credentials=cors_allow_credentials,
         allow_methods=settings.cors_allow_methods,
         allow_headers=settings.cors_allow_headers,
     )
@@ -1248,6 +1267,73 @@ def _get_app() -> FastAPI:  # noqa: C901, PLR0915  # pylint: disable=too-many-st
     _state.app = app
     _state.widget_prefix = settings.widget_prefix.rstrip("/")  # Store normalized prefix
 
+    # ── OAuth2 / Auth middleware integration ──────────────────────────
+
+    if deploy_settings.auth_enabled and pywry_settings.oauth2 is not None:
+        try:
+            from .auth.providers import create_provider_from_settings
+            from .auth.deploy_routes import create_auth_router
+            from .auth.token_store import get_token_store
+            from .state.auth import AuthConfig, AuthMiddleware
+            from .state._factory import get_session_store
+
+            # Build provider
+            oauth2_provider = create_provider_from_settings(pywry_settings.oauth2)
+
+            # Build config objects
+            auth_config = AuthConfig(
+                enabled=True,
+                session_cookie=deploy_settings.auth_session_cookie,
+                auth_header=deploy_settings.auth_header,
+                session_ttl=deploy_settings.session_ttl,
+            )
+
+            # Token store
+            token_backend = pywry_settings.oauth2.token_store_backend
+            token_store = get_token_store(backend=token_backend)
+
+            # Session store
+            session_store = get_session_store()
+
+            # Mount auth routes
+            auth_router = create_auth_router(
+                provider=oauth2_provider,
+                session_store=session_store,
+                token_store=token_store,
+                deploy_settings=deploy_settings,
+                auth_config=auth_config,
+                use_pkce=pywry_settings.oauth2.use_pkce,
+            )
+            app.include_router(auth_router)
+
+            # Add AuthMiddleware (after CORS — Starlette processes in reverse)
+            # Skip public paths (pre-auth routes)
+            public_paths = set(deploy_settings.auth_public_paths)
+            app.add_middleware(
+                AuthMiddleware,
+                session_store=session_store,
+                config=auth_config,
+                public_paths=public_paths,
+            )
+
+            import logging
+
+            logging.getLogger("pywry.auth").info(  # pylint: disable=logging-too-many-args
+                "OAuth2 auth enabled with %s provider", pywry_settings.oauth2.provider
+            )
+        except Exception as exc:
+            import logging
+
+            logging.getLogger("pywry.auth").critical(  # pylint: disable=logging-too-many-args
+                "FATAL: Failed to set up OAuth2 auth routes: %s. "
+                "Refusing to start in partially secured mode.",
+                exc,
+            )
+            raise RuntimeError(
+                f"OAuth2 auth initialization failed: {exc}. "
+                "Cannot start with auth_enabled=True and broken auth setup."
+            ) from exc
+
     # Initialize internal API token for protecting internal HTTP endpoints (not widget serving)
     if settings.internal_api_token:
         _state.internal_api_token = settings.internal_api_token
diff --git a/pywry/pywry/mcp/skills/authentication.md b/pywry/pywry/mcp/skills/authentication.md
new file mode 100644
index 0000000..e007816
--- /dev/null
+++ b/pywry/pywry/mcp/skills/authentication.md
@@ -0,0 +1,139 @@
+# Authentication & OAuth2
+
+> Add OAuth2 authentication to PyWry apps — Google, GitHub, Microsoft, or any OIDC provider.
+
+## Two Modes
+
+### Native Mode (Desktop)
+Opens a dedicated auth window → user logs in at provider → callback captured on ephemeral localhost server → tokens returned.
+
+```python
+from pywry import PyWry
+
+app = PyWry()
+result = app.login()  # Blocks until auth completes
+
+if result.success:
+    app.show("<h1>Welcome!</h1>")
+    app.block()
+```
+
+### Deploy Mode (Production)
+Auth routes mounted automatically when `auth_enabled=True` and `oauth2` settings are configured.
+
+```bash
+PYWRY_DEPLOY__AUTH_ENABLED=true
+PYWRY_OAUTH2__PROVIDER=google
+PYWRY_OAUTH2__CLIENT_ID=your-id
+PYWRY_OAUTH2__CLIENT_SECRET=your-secret
+```
+
+Routes: `GET /auth/login`, `GET /auth/callback`, `POST /auth/refresh`, `POST /auth/logout`, `GET /auth/status`, `GET /auth/userinfo`
+
+## Configuration
+
+### Environment Variables
+
+```bash
+# Provider: google, github, microsoft, oidc, custom
+PYWRY_OAUTH2__PROVIDER=google
+
+# Credentials
+PYWRY_OAUTH2__CLIENT_ID=your-client-id
+PYWRY_OAUTH2__CLIENT_SECRET=your-client-secret
+
+# Scopes (space-separated)
+PYWRY_OAUTH2__SCOPES=openid email profile
+
+# PKCE (recommended for public clients)
+PYWRY_OAUTH2__USE_PKCE=true
+
+# Token storage: memory (default), keyring (native), redis (deploy)
+PYWRY_OAUTH2__TOKEN_STORE_BACKEND=memory
+
+# Custom provider endpoints
+PYWRY_OAUTH2__AUTHORIZE_URL=https://provider.com/authorize
+PYWRY_OAUTH2__TOKEN_URL=https://provider.com/token
+
+# OIDC auto-discovery
+PYWRY_OAUTH2__ISSUER_URL=https://accounts.google.com
+```
+
+### TOML Configuration
+
+```toml
+[tool.pywry.oauth2]
+provider = "github"
+client_id = "your-id"
+scopes = "read:user user:email"
+use_pkce = true
+token_store_backend = "memory"
+```
+
+## Provider Setup
+
+### Google
+```python
+from pywry.auth import GoogleProvider
+provider = GoogleProvider(client_id="...", client_secret="...")
+result = app.login(provider=provider)
+```
+
+### GitHub
+```python
+from pywry.auth import GitHubProvider
+provider = GitHubProvider(client_id="...", client_secret="...")
+result = app.login(provider=provider)
+```
+
+### Microsoft (Azure AD)
+```python
+from pywry.auth import MicrosoftProvider
+provider = MicrosoftProvider(client_id="...", tenant_id="your-tenant")
+result = app.login(provider=provider)
+```
+
+### Custom OIDC
+```python
+from pywry.auth import GenericOIDCProvider
+provider = GenericOIDCProvider(
+    client_id="...",
+    issuer_url="https://your-idp.com",  # Auto-discovers endpoints
+)
+result = app.login(provider=provider)
+```
+
+## Frontend Auth State
+
+When authenticated, `window.__PYWRY_AUTH__` is set with `{ user_id, roles, token_type }`.
+
+```javascript
+// Check auth
+window.pywry.auth.isAuthenticated()
+
+// Get state
+window.pywry.auth.getState()  // { authenticated, user_id, roles, token_type }
+
+// React to changes
+window.pywry.auth.onAuthStateChange((state) => {
+    console.log('Auth changed:', state);
+});
+```
+
+## Token Storage Backends
+
+| Backend | Use Case | Persistence |
+|---------|----------|-------------|
+| `memory` | Development, single-process | None (lost on restart) |
+| `keyring` | Native desktop apps | OS credential manager |
+| `redis` | Deploy mode, multi-worker | Redis with TTL |
+
+Install keyring support: `pip install pywry[auth]`
+
+## Security Notes
+
+- PKCE is enabled by default (public client best practice)
+- CSRF protection via `state` parameter validation
+- Tokens are never injected into HTML — passed via secure cookies or IPC
+- Session cookies are `HttpOnly`, `Secure`, `SameSite=Lax`
+- Background token refresh happens automatically before expiry
diff --git a/pywry/pywry/runtime.py b/pywry/pywry/runtime.py
index 639cd70..683be6b 100644
--- a/pywry/pywry/runtime.py
+++ b/pywry/pywry/runtime.py
@@ -798,6 +798,13 @@ def start() -> bool:
     env["PYWRY_ON_WINDOW_CLOSE"] = _ON_WINDOW_CLOSE  # Pass close behavior to subprocess
     env["PYWRY_WINDOW_MODE"] = _WINDOW_MODE  # Pass window mode to subprocess
 
+    # On Windows, CREATE_NEW_PROCESS_GROUP prevents the subprocess from
+    # receiving CTRL_C_EVENT when the user presses Ctrl+C in the terminal.
+    # The parent handles shutdown cleanly via the IPC "quit" command.
+    creation_flags = 0
+    if sys.platform == "win32":
+        creation_flags = subprocess.CREATE_NEW_PROCESS_GROUP
+
     try:
         _process = subprocess.Popen(  # pylint: disable=R1732
             cmd,
@@ -809,6 +816,7 @@ def start() -> bool:
             bufsize=1,
             env=env,
             encoding="utf-8",
+            creationflags=creation_flags,
         )
     except Exception as e:
         log_error(f"Failed to start subprocess: {e}")
diff --git a/pywry/pywry/state/auth.py b/pywry/pywry/state/auth.py
index e1c3cd9..a6a05ad 100644
--- a/pywry/pywry/state/auth.py
+++ b/pywry/pywry/state/auth.py
@@ -104,7 +104,7 @@ def generate_session_token(
         secret.encode(),
         payload.encode(),
         hashlib.sha256,
-    ).hexdigest()[:16]
+    ).hexdigest()
 
     return f"{payload}:{signature}"
 
@@ -147,7 +147,7 @@ def validate_session_token(  # pylint: disable=no-else-return
             secret.encode(),
             payload.encode(),
             hashlib.sha256,
-        ).hexdigest()[:16]
+        ).hexdigest()
 
         if not hmac.compare_digest(signature, expected_sig):
             return (False, None, "Invalid signature")
@@ -359,6 +359,7 @@ def __init__(
         app: Any,
         session_store: SessionStore,
         config: AuthConfig,
+        public_paths: set[str] | None = None,
     ) -> None:
         """Initialize the middleware.
 
@@ -370,10 +371,13 @@ def __init__(
             Session store for validation.
         config : AuthConfig
             Authentication configuration.
+        public_paths : set of str, optional
+            Paths that do not require authentication (e.g., login/callback routes).
         """
         self.app = app
         self.session_store = session_store
         self.config = config
+        self.public_paths = public_paths or set()
 
     async def __call__(
         self,
@@ -386,6 +390,12 @@ async def __call__(
             await self.app(scope, receive, send)
             return
 
+        # Skip auth for public paths (e.g., /auth/login, /auth/callback)
+        path = scope.get("path", "")
+        if any(path.startswith(p) for p in self.public_paths):
+            await self.app(scope, receive, send)
+            return
+
         # Add session to scope
         scope["session"] = None
 
diff --git a/pywry/pywry/state/sync_helpers.py b/pywry/pywry/state/sync_helpers.py
index fd36f7d..b15dfed 100644
--- a/pywry/pywry/state/sync_helpers.py
+++ b/pywry/pywry/state/sync_helpers.py
@@ -9,6 +9,7 @@
 import asyncio
 import threading
 
+from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any, TypeVar
 
 
@@ -133,6 +134,55 @@ def run_async(coro: Coroutine[Any, Any, T], timeout: float | None = 5.0) -> T:
     return future.result(timeout=timeout)
 
 
+@dataclass
+class WaitResult:
+    """Result of a wait_for_event operation."""
+
+    completed: bool = False
+    cancelled: bool = False
+    timed_out: bool = False
+
+
+def wait_for_event(
+    event: threading.Event,
+    timeout: float | None = None,
+    cancellation: threading.Event | None = None,
+    poll_interval: float = 0.1,
+) -> WaitResult:
+    """Wait for a threading.Event with optional cancellation support.
+
+    Polls both the target event and an optional cancellation event
+    every ``poll_interval`` seconds.
+
+    Parameters
+    ----------
+    event : threading.Event
+        The event to wait for.
+    timeout : float or None
+        Maximum seconds to wait. None for no timeout.
+    cancellation : threading.Event, optional
+        If set, the wait is cancelled.
+    poll_interval : float
+        Polling interval in seconds (default 0.1).
+
+    Returns
+    -------
+    WaitResult
+        The result indicating completion, cancellation, or timeout.
+    """
+    elapsed = 0.0
+    while True:
+        if cancellation is not None and cancellation.is_set():
+            return WaitResult(cancelled=True)
+
+        if event.wait(timeout=poll_interval):
+            return WaitResult(completed=True)
+
+        elapsed += poll_interval
+        if timeout is not None and elapsed >= timeout:
+            return WaitResult(timed_out=True)
+
+
 def run_async_fire_and_forget(coro: Coroutine[Any, Any, Any]) -> None:
     """Schedule an async coroutine without waiting for result.
 
diff --git a/pywry/pywry/state/types.py b/pywry/pywry/state/types.py
index 8ae45fe..f13e1d0 100644
--- a/pywry/pywry/state/types.py
+++ b/pywry/pywry/state/types.py
@@ -5,6 +5,8 @@
 
 from __future__ import annotations
 
+import time
+
 from dataclasses import dataclass, field
 from enum import Enum
 from typing import Any, Literal
@@ -143,3 +145,84 @@ class UserSession:
 # Access control permission types
 Permission = Literal["read", "write", "admin"]
 ResourceType = Literal["widget", "session", "user", "system"]
+
+
+@dataclass
+class OAuthTokenSet:
+    """OAuth2 token set returned by a provider.
+
+    Attributes
+    ----------
+    access_token : str
+        The access token for API requests.
+    token_type : str
+        Token type, typically "Bearer".
+    refresh_token : str or None
+        Optional refresh token for obtaining new access tokens.
+    expires_in : int or None
+        Token lifetime in seconds from issuance.
+    id_token : str or None
+        Optional OIDC ID token (JWT).
+    scope : str
+        Space-separated list of granted scopes.
+    raw : dict[str, Any]
+        The raw token response from the provider.
+    issued_at : float
+        Unix timestamp when the token was issued.
+    """
+
+    access_token: str
+    token_type: str = "Bearer"  # noqa: S105
+    refresh_token: str | None = None
+    expires_in: int | None = None
+    id_token: str | None = None
+    scope: str = ""
+    raw: dict[str, Any] = field(default_factory=dict)
+    issued_at: float = field(default_factory=time.time)
+
+    @property
+    def is_expired(self) -> bool:
+        """Check if the access token has expired."""
+        if self.expires_in is None:
+            return False
+        return time.time() > (self.issued_at + self.expires_in)
+
+    @property
+    def expires_at(self) -> float | None:
+        """Get the expiry timestamp, or None if no expiry."""
+        if self.expires_in is None:
+            return None
+        return self.issued_at + self.expires_in
+
+
+@dataclass
+class AuthFlowResult:
+    """Result of an OAuth2 authentication flow.
+
+    Attributes
+    ----------
+    success : bool
+        Whether authentication completed successfully.
+    tokens : OAuthTokenSet or None
+        The token set if authentication succeeded.
+    error : str or None
+        Error message if authentication failed.
+    user_info : dict[str, Any] or None
+        User profile information from the provider.
+    """
+
+    success: bool
+    tokens: OAuthTokenSet | None = None
+    error: str | None = None
+    user_info: dict[str, Any] | None = None
+
+
+class AuthFlowState(str, Enum):
+    """State of an OAuth2 authentication flow."""
+
+    PENDING = "pending"
+    IN_PROGRESS = "in_progress"
+    COMPLETED = "completed"
+    CANCELLED = "cancelled"
+    FAILED = "failed"
+    TIMED_OUT = "timed_out"
diff --git a/pywry/pywry/toolbar.py b/pywry/pywry/toolbar.py
index 572fe9d..0a98b4c 100644
--- a/pywry/pywry/toolbar.py
+++ b/pywry/pywry/toolbar.py
@@ -1,4 +1,5 @@
 # pylint: disable=too-many-lines,unused-argument,line-too-long
+# flake8: noqa: PLR0912
 """Pydantic models for PyWry toolbar components.
 
 This module provides strongly-typed models for toolbar configurations:
@@ -260,6 +261,56 @@ def _generate_component_id(component_type: str = "item") -> str:
     return f"{component_type}-{uuid.uuid4().hex[:8]}"
 
 
+def _resolve_script_content(script: str | Path | None) -> str | None:
+    """Resolve a script field to its content string.
+
+    Handles ``Path`` objects, file-path strings, and inline JavaScript.
+    The heuristic mirrors the original ``collect_scripts`` logic:
+
+    * If the value is a ``Path`` **or** a string that does *not* start with
+      a recognised JS keyword/token, try to read it as a file.
+    * If the file does not exist, fall back to treating it as inline JS.
+    * If the string starts with a JS keyword/token, use it as-is.
+
+    Parameters
+    ----------
+    script : str | Path | None
+        The raw ``script`` field value.
+
+    Returns
+    -------
+    str | None
+        Resolved JavaScript source, or ``None`` when there is nothing.
+    """
+    if not script:
+        return None
+
+    if isinstance(script, Path) or (
+        isinstance(script, str)
+        and not script.strip().startswith(
+            (
+                "(",
+                "{",
+                "function",
+                "//",
+                "/*",
+                "var ",
+                "let ",
+                "const ",
+                "if ",
+                "for ",
+                "while ",
+            )
+        )
+    ):
+        script_path = Path(script) if isinstance(script, str) else script
+        if script_path.exists():
+            return script_path.read_text(encoding="utf-8")
+        return str(script)
+
+    return str(script)
+
+
 class Option(BaseModel):
     """A single option for select/multiselect inputs."""
 
@@ -2125,7 +2176,13 @@ def build_html(self, parent_id: str | None = None) -> str:
                     else:
                         children_html += child.build_html()
 
-        return f"<div {' '.join(attrs)}>{self.content}{children_html}</div>"
+        # Resolve own script
+        script_tag = ""
+        resolved = _resolve_script_content(self.script)
+        if resolved:
+            script_tag = f"<script>{resolved}</script>"
+
+        return f"<div {' '.join(attrs)}>{self.content}{children_html}{script_tag}</div>"
 
     def collect_scripts(self) -> list[str]:
         """Collect scripts from this div and all nested children (depth-first).
@@ -2138,35 +2195,9 @@ def collect_scripts(self) -> list[str]:
         scripts: list[str] = []
 
         # This div's script first (parent before children)
-        if self.script:
-            if isinstance(self.script, Path) or (
-                isinstance(self.script, str)
-                and not self.script.strip().startswith(  # pylint: disable=E1101
-                    (
-                        "(",
-                        "{",
-                        "function",
-                        "//",
-                        "/*",
-                        "var ",
-                        "let ",
-                        "const ",
-                        "if ",
-                        "for ",
-                        "while ",
-                    )
-                )
-            ):
-                # Might be a file path - try to read it
-                script_path = Path(self.script) if isinstance(self.script, str) else self.script
-                # pylint: disable=E1101
-                if script_path.exists():
-                    scripts.append(script_path.read_text(encoding="utf-8"))
-                else:
-                    # Treat as inline script
-                    scripts.append(str(self.script))
-            else:
-                scripts.append(str(self.script))
+        resolved = _resolve_script_content(self.script)
+        if resolved:
+            scripts.append(resolved)
 
         # Children's scripts (depth-first)
         if self.children:
@@ -2820,7 +2851,13 @@ def build_html(self) -> str:
             f'<div class="pywry-toolbar-content"{content_style}>{"".join(item_htmls)}</div>'
         )
 
-        return f"<div {' '.join(attrs)}{outer_style}>{toggle_html}{content_html}{resize_handle_html}</div>"
+        # Resolve own script
+        script_tag = ""
+        resolved = _resolve_script_content(self.script)
+        if resolved:
+            script_tag = f"<script>{resolved}</script>"
+
+        return f"<div {' '.join(attrs)}{outer_style}>{toggle_html}{content_html}{resize_handle_html}{script_tag}</div>"
 
     def collect_scripts(self) -> list[str]:
         """Collect scripts from toolbar and all nested Div children (depth-first).
@@ -2835,33 +2872,9 @@ def collect_scripts(self) -> list[str]:
         scripts: list[str] = []
 
         # Toolbar script first (parent context available to children)
-        if self.script:
-            if isinstance(self.script, Path) or (
-                isinstance(self.script, str)
-                and not self.script.strip().startswith(  # pylint: disable=E1101
-                    (
-                        "(",
-                        "{",
-                        "function",
-                        "//",
-                        "/*",
-                        "var ",
-                        "let ",
-                        "const ",
-                        "if ",
-                        "for ",
-                        "while ",
-                    )
-                )
-            ):
-                script_path = Path(self.script) if isinstance(self.script, str) else self.script
-                # pylint: disable=E1101
-                if script_path.exists():
-                    scripts.append(script_path.read_text(encoding="utf-8"))
-                else:
-                    scripts.append(str(self.script))
-            else:
-                scripts.append(str(self.script))
+        resolved = _resolve_script_content(self.script)
+        if resolved:
+            scripts.append(resolved)
 
         # Children's scripts (depth-first)
         for item in self.items:
diff --git a/pywry/pywry/widget_protocol.py b/pywry/pywry/widget_protocol.py
index b036459..94471ae 100644
--- a/pywry/pywry/widget_protocol.py
+++ b/pywry/pywry/widget_protocol.py
@@ -9,8 +9,6 @@
 
 from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
 
-from .state_mixins import _UNSET, _Unset
-
 
 if TYPE_CHECKING:
     from collections.abc import Callable
@@ -642,134 +640,6 @@ def is_alive(self) -> bool:
         resources = self.resources
         return resources is not None and not resources.is_destroyed
 
-    # ─────────────────────────────────────────────────────────────────────────
-    # Notification helpers
-    # ─────────────────────────────────────────────────────────────────────────
-
-    def alert(
-        self,
-        message: str,
-        alert_type: str = "info",
-        title: str | None = None,
-        duration: int | None = None,
-        callback_event: str | None = None,
-        position: str = "top-right",
-    ) -> None:
-        """Show a toast notification in this window.
-
-        Parameters
-        ----------
-        message : str
-            The message to display.
-        alert_type : str
-            Alert type: 'info', 'success', 'warning', 'error', or 'confirm'.
-        title : str, optional
-            Optional title for the toast.
-        duration : int, optional
-            Auto-dismiss duration in ms. Defaults based on type.
-        callback_event : str, optional
-            Event name to emit when confirm dialog is answered.
-        position : str
-            Toast position: 'top-right', 'top-left', 'bottom-right', 'bottom-left'.
-
-        Examples
-        --------
-        >>> handle.alert("File saved successfully")
-        >>> handle.alert("Export complete", alert_type="success", title="Done")
-        >>> handle.alert(
-        ...     "Are you sure?", alert_type="confirm", callback_event="app:confirm"
-        ... )
-        """
-        payload: dict[str, Any] = {
-            "message": message,
-            "type": alert_type,
-            "position": position,
-        }
-        if title is not None:
-            payload["title"] = title
-        if duration is not None:
-            payload["duration"] = duration
-        if callback_event is not None:
-            payload["callback_event"] = callback_event
-        self.emit("pywry:alert", payload)
-
-    # ─────────────────────────────────────────────────────────────────────────
-    # Toolbar state helpers
-    # ─────────────────────────────────────────────────────────────────────────
-
-    def request_toolbar_state(self, toolbar_id: str | None = None) -> None:
-        """Request the current state of all toolbar components.
-
-        The response will be emitted as a 'toolbar:state-response' event
-        containing component IDs and their current values.
-
-        Parameters
-        ----------
-        toolbar_id : str, optional
-            If provided, only request state for the specified toolbar.
-
-        Examples
-        --------
-        >>> handle.request_toolbar_state()
-        """
-        payload: dict[str, Any] = {}
-        if toolbar_id:
-            payload["toolbarId"] = toolbar_id
-        self.emit("toolbar:request-state", payload)
-
-    def set_toolbar_value(
-        self,
-        component_id: str,
-        value: Any = _UNSET,
-        toolbar_id: str | None = None,
-        **attrs: Any,
-    ) -> None:
-        """Set a toolbar component's value and/or attributes.
-
-        Parameters
-        ----------
-        component_id : str
-            The component_id of the toolbar item to update.
-        value : Any, optional
-            The new value for the component. Pass explicitly to set it.
-        toolbar_id : str, optional
-            The toolbar ID (if applicable).
-        **attrs : Any
-            Additional attributes to set on the component:
-            label, disabled, variant, options, style, placeholder, min, max, step.
-
-        Examples
-        --------
-        >>> handle.set_toolbar_value("theme-select", "light")
-        >>> handle.set_toolbar_value("submit-btn", disabled=True, label="Loading...")
-        """
-        payload: dict[str, Any] = {"componentId": component_id}
-        if not isinstance(value, _Unset):
-            payload["value"] = value
-        if toolbar_id:
-            payload["toolbarId"] = toolbar_id
-        payload.update(attrs)
-        self.emit("toolbar:set-value", payload)
-
-    def set_toolbar_values(self, values: dict[str, Any], toolbar_id: str | None = None) -> None:
-        """Set multiple toolbar component values at once.
-
-        Parameters
-        ----------
-        values : dict[str, Any]
-            Mapping of component_id to new value.
-        toolbar_id : str, optional
-            The toolbar ID (if applicable).
-
-        Examples
-        --------
-        >>> handle.set_toolbar_values({"theme-select": "light", "zoom-input": 100})
-        """
-        payload: dict[str, Any] = {"values": values}
-        if toolbar_id:
-            payload["toolbarId"] = toolbar_id
-        self.emit("toolbar:set-values", payload)
-
     def __str__(self) -> str:
         """Return the window label."""
         return self._label
diff --git a/pywry/pywry/window_manager/lifecycle.py b/pywry/pywry/window_manager/lifecycle.py
index 4c781b0..eb9b401 100644
--- a/pywry/pywry/window_manager/lifecycle.py
+++ b/pywry/pywry/window_manager/lifecycle.py
@@ -13,6 +13,7 @@
 
 
 if TYPE_CHECKING:
+    from collections.abc import Callable
     from pathlib import Path
 
     from ..models import HtmlContent, WindowConfig
@@ -42,6 +43,10 @@ class WindowResources:
     # Timestamp when content was last set via IPC (to debounce content-request)
     content_set_at: datetime | None = None
 
+    # Lifecycle callbacks - invoked with (label, close_reason)
+    on_close: list[Callable[[str, str], None]] = field(default_factory=list)
+    close_reason: str | None = None
+
 
 class WindowLifecycle:
     """Manages window lifecycle with aggressive cleanup.
@@ -416,6 +421,14 @@ def destroy(self, label: str) -> bool:
 
         debug(f"Destroying window '{label}'")
 
+        # Fire on_close callbacks before cleanup
+        resources.close_reason = "programmatic"
+        for callback in resources.on_close:
+            try:
+                callback(label, "programmatic")
+            except Exception as exc:
+                warn(f"on_close callback error for '{label}': {exc}")
+
         # Clear all stored data
         resources.html_content = None
         resources.scripts_injected.clear()
diff --git a/pywry/tests/conftest.py b/pywry/tests/conftest.py
index a4acd43..f17eade 100644
--- a/pywry/tests/conftest.py
+++ b/pywry/tests/conftest.py
@@ -644,3 +644,72 @@ def session_store_with_fallback(unique_prefix: str = "test:"):
         # Fall back to memory
         store = MemorySessionStore()
         yield store, "memory"
+
+
+# =============================================================================
+# OAuth2 / Auth Fixtures
+# =============================================================================
+
+
+@pytest.fixture
+def mock_oauth_provider():
+    """Create a mock OAuth2 provider for tests.
+
+    Returns a MagicMock implementing the OAuthProvider interface with
+    sensible defaults: successful token exchange, user info, etc.
+    """
+    from unittest.mock import AsyncMock, MagicMock
+
+    from pywry.state.types import OAuthTokenSet
+
+    provider = MagicMock()
+    provider.__class__.__name__ = "MockProvider"
+    provider.build_authorize_url.return_value = "https://mock.idp/authorize?state=test"
+
+    tokens = OAuthTokenSet(
+        access_token="at_fixture",
+        token_type="Bearer",
+        refresh_token="rt_fixture",
+        expires_in=3600,
+        issued_at=time.time(),
+    )
+    provider.exchange_code = AsyncMock(return_value=tokens)
+    provider.get_userinfo = AsyncMock(
+        return_value={"sub": "fixture_user", "email": "fixture@test.com"}
+    )
+    provider.refresh_tokens = AsyncMock(return_value=tokens)
+    provider.revoke_token = AsyncMock()
+    return provider
+
+
+@pytest.fixture
+def auth_settings():
+    """Create OAuth2Settings for tests."""
+    from pywry.config import OAuth2Settings
+
+    return OAuth2Settings(
+        provider="google",
+        client_id="test-client-id",
+        client_secret="test-client-secret",
+        scopes="openid email profile",
+    )
+
+
+@pytest.fixture
+def memory_token_store():
+    """Create a MemoryTokenStore for tests."""
+    from pywry.auth.token_store import MemoryTokenStore
+
+    return MemoryTokenStore()
+
+
+@pytest.fixture
+def auth_session_manager(mock_oauth_provider, memory_token_store):  # pylint: disable=redefined-outer-name
+    """Create a SessionManager wired to mock provider and memory store."""
+    from pywry.auth.session import SessionManager
+
+    return SessionManager(
+        provider=mock_oauth_provider,
+        token_store=memory_token_store,
+        session_key="test_user",
+    )
diff --git a/pywry/tests/test_alerts.py b/pywry/tests/test_alerts.py
index 1344109..713b304 100644
--- a/pywry/tests/test_alerts.py
+++ b/pywry/tests/test_alerts.py
@@ -9,11 +9,10 @@
 - E2E tests for inline notebook alerts
 """
 
-# pylint: disable=too-many-lines,unsubscriptable-object
+# pylint: disable=too-many-lines,unsubscriptable-object,too-many-lines
 
 from __future__ import annotations
 
-import sys
 import time
 
 from collections.abc import Callable
@@ -23,12 +22,7 @@
 import pytest
 
 # Import shared test utilities from tests.conftest
-from tests.conftest import (
-    _clear_registries,
-    _stop_runtime_sync,
-    show_and_wait_ready,
-    wait_for_result,
-)
+from tests.conftest import show_and_wait_ready, wait_for_result
 
 
 F = TypeVar("F", bound=Callable[..., Any])
@@ -46,6 +40,8 @@ def retry_on_subprocess_failure(max_attempts: int = 3, delay: float = 1.0) -> Ca
     def decorator(func: F) -> F:
         @wraps(func)
         def wrapper(*args: Any, **kwargs: Any) -> Any:
+            from pywry import runtime
+
             last_error: Exception | None = None
             for attempt in range(max_attempts):
                 try:
@@ -53,21 +49,11 @@ def wrapper(*args: Any, **kwargs: Any) -> Any:
                 except (TimeoutError, AssertionError) as e:
                     last_error = e
                     if attempt < max_attempts - 1:
-                        # Stop runtime and poll until the subprocess is fully
-                        # terminated (matches _stop_runtime_sync in conftest).
-                        _stop_runtime_sync()
-                        # Clear stale callback/lifecycle state before the next
-                        # attempt so leftover registrations don't interfere.
-                        _clear_registries()
-                        # Progressive backoff.  On Windows, the OS needs extra
-                        # time after process termination before the WebView2
-                        # "Chrome_WidgetWin_0" window class registration is
-                        # released and a new subprocess can re-register it.
-                        extra = 5.0 if sys.platform == "win32" else 0.0
-                        time.sleep(delay * (attempt + 1) + extra)
-            if last_error is None:
-                raise RuntimeError("retry_on_subprocess_failure: no attempts were made")
-            raise last_error
+                        # Clean up and wait before retry
+                        runtime.stop()
+                        # Progressive backoff for CI stability
+                        time.sleep(delay * (attempt + 1))
+            raise last_error  # type: ignore[misc]
 
         return wrapper  # type: ignore[return-value]
 
diff --git a/pywry/tests/test_auth_callback_server.py b/pywry/tests/test_auth_callback_server.py
new file mode 100644
index 0000000..408d028
--- /dev/null
+++ b/pywry/tests/test_auth_callback_server.py
@@ -0,0 +1,205 @@
+"""Unit tests for OAuth2 ephemeral callback server."""
+
+# pylint: disable=consider-using-with
+
+from __future__ import annotations
+
+import contextlib
+import threading
+import time
+
+from urllib.parse import urlencode
+from urllib.request import urlopen
+
+from pywry.auth.callback_server import OAuthCallbackServer
+
+
+class TestOAuthCallbackServer:
+    """Tests for OAuthCallbackServer."""
+
+    def test_start_and_stop(self) -> None:
+        """Server starts, binds to a port, and stops cleanly."""
+        server = OAuthCallbackServer()
+        redirect_uri = server.start()
+
+        assert redirect_uri.startswith("http://127.0.0.1:")
+        assert redirect_uri.endswith("/callback")
+        assert server._actual_port > 0
+
+        server.stop()
+
+    def test_redirect_uri_property(self) -> None:
+        """redirect_uri matches the started server port."""
+        server = OAuthCallbackServer()
+        server.start()
+        try:
+            assert f":{server._actual_port}/callback" in server.redirect_uri
+        finally:
+            server.stop()
+
+    def test_wait_for_callback_timeout(self) -> None:
+        """wait_for_callback returns None on timeout."""
+        server = OAuthCallbackServer()
+        server.start()
+        try:
+            result = server.wait_for_callback(timeout=0.2)
+            assert result is None
+        finally:
+            server.stop()
+
+    def test_callback_with_code(self) -> None:
+        """Callback captures authorization code and state."""
+        server = OAuthCallbackServer()
+        server.start()
+
+        try:
+            params = urlencode({"code": "test_code_123", "state": "test_state"})
+            callback_url = f"{server.redirect_uri}?{params}"
+
+            # Send the callback in a background thread
+            def send_request() -> None:
+                time.sleep(0.1)
+                with contextlib.suppress(Exception):
+                    urlopen(callback_url, timeout=5)  # noqa: S310
+
+            t = threading.Thread(target=send_request, daemon=True)
+            t.start()
+
+            result = server.wait_for_callback(timeout=5.0)
+            assert result is not None
+            assert result["code"] == "test_code_123"
+            assert result["state"] == "test_state"
+            assert result["error"] is None
+        finally:
+            server.stop()
+
+    def test_callback_with_error(self) -> None:
+        """Callback captures provider error."""
+        server = OAuthCallbackServer()
+        server.start()
+
+        try:
+            params = urlencode(
+                {
+                    "error": "access_denied",
+                    "error_description": "User cancelled",
+                }
+            )
+            callback_url = f"{server.redirect_uri}?{params}"
+
+            def send_request() -> None:
+                time.sleep(0.1)
+                with contextlib.suppress(Exception):
+                    urlopen(callback_url, timeout=5)  # noqa: S310
+
+            t = threading.Thread(target=send_request, daemon=True)
+            t.start()
+
+            result = server.wait_for_callback(timeout=5.0)
+            assert result is not None
+            assert result["error"] == "access_denied"
+            assert result["error_description"] == "User cancelled"
+            assert result["code"] is None
+        finally:
+            server.stop()
+
+    def test_waiting_page(self) -> None:
+        """Root path returns the waiting page."""
+        server = OAuthCallbackServer()
+        server.start()
+
+        try:
+            resp = urlopen(f"http://127.0.0.1:{server._actual_port}/", timeout=5)
+            content = resp.read().decode("utf-8")
+            assert "Waiting for authentication" in content
+        finally:
+            server.stop()
+
+    def test_only_first_callback_captured(self) -> None:
+        """Only the first callback result is captured."""
+        server = OAuthCallbackServer()
+        server.start()
+
+        try:
+            params1 = urlencode({"code": "first", "state": "s1"})
+            params2 = urlencode({"code": "second", "state": "s2"})
+
+            # Send first callback
+            with contextlib.suppress(Exception):
+                urlopen(f"{server.redirect_uri}?{params1}", timeout=5)  # noqa: S310
+
+            # Send second callback
+            with contextlib.suppress(Exception):
+                urlopen(f"{server.redirect_uri}?{params2}", timeout=5)  # noqa: S310
+
+            result = server.wait_for_callback(timeout=2.0)
+            assert result is not None
+            assert result["code"] == "first"
+        finally:
+            server.stop()
+
+    def test_custom_host_port(self) -> None:
+        """Custom host and port are used."""
+        server = OAuthCallbackServer(host="127.0.0.1", port=0)
+        redirect_uri = server.start()
+
+        try:
+            assert "127.0.0.1" in redirect_uri
+        finally:
+            server.stop()
+
+    def test_stop_idempotent(self) -> None:
+        """Calling stop() multiple times is safe."""
+        server = OAuthCallbackServer()
+        server.start()
+        server.stop()
+        server.stop()  # Should not raise
+
+    def test_callback_xss_escaping(self) -> None:
+        """Error messages in callback HTML are HTML-escaped to prevent XSS."""
+        server = OAuthCallbackServer()
+        server.start()
+
+        try:
+            xss_payload = '<script>alert("xss")</script>'
+            params = urlencode(
+                {
+                    "error": "access_denied",
+                    "error_description": xss_payload,
+                }
+            )
+            callback_url = f"{server.redirect_uri}?{params}"
+
+            def send_request() -> None:
+                time.sleep(0.1)
+                with contextlib.suppress(Exception):
+                    urlopen(callback_url, timeout=5)  # noqa: S310
+
+            t = threading.Thread(target=send_request, daemon=True)
+            t.start()
+
+            result = server.wait_for_callback(timeout=5.0)
+            assert result is not None
+            assert result["error"] == "access_denied"
+            # The raw XSS payload must NOT appear in the error_description rendered
+            # (but we can't inspect the HTML directly from the result dict;
+            #  the important thing is the server didn't crash)
+        finally:
+            server.stop()
+
+    def test_callback_csp_header(self) -> None:
+        """Callback responses include Content-Security-Policy header."""
+        from urllib.request import Request
+
+        server = OAuthCallbackServer()
+        server.start()
+
+        try:
+            # Hit the root waiting page and check CSP header
+            req = Request(f"http://127.0.0.1:{server._actual_port}/")
+            resp = urlopen(req, timeout=5)  # noqa: S310
+            csp = resp.headers.get("Content-Security-Policy", "")
+            assert "default-src" in csp
+            assert "'none'" in csp or "style-src" in csp
+        finally:
+            server.stop()
diff --git a/pywry/tests/test_auth_deploy_routes.py b/pywry/tests/test_auth_deploy_routes.py
new file mode 100644
index 0000000..3e04835
--- /dev/null
+++ b/pywry/tests/test_auth_deploy_routes.py
@@ -0,0 +1,423 @@
+"""Integration tests for OAuth2 deploy mode FastAPI routes."""
+
+from __future__ import annotations
+
+import time
+
+from unittest.mock import AsyncMock, MagicMock
+
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from pywry.auth.deploy_routes import (
+    _login_rate_limiter,
+    _pending_auth_states,
+    cleanup_expired_states,
+    create_auth_router,
+)
+from pywry.auth.token_store import MemoryTokenStore
+from pywry.state.auth import AuthConfig
+from pywry.state.types import OAuthTokenSet
+
+
+# ── Helpers ──────────────────────────────────────────────────────────
+
+
+def _make_mock_provider() -> MagicMock:
+    """Create a mock OAuthProvider."""
+    provider = MagicMock()
+    provider.__class__.__name__ = "MockProvider"
+
+    tokens = OAuthTokenSet(
+        access_token="at_deploy_test",
+        token_type="Bearer",
+        refresh_token="rt_deploy_test",
+        expires_in=3600,
+        issued_at=time.time(),
+    )
+    provider.exchange_code = AsyncMock(return_value=tokens)
+    provider.get_userinfo = AsyncMock(return_value={"sub": "user1", "email": "user@test.com"})
+    provider.refresh_tokens = AsyncMock(
+        return_value=OAuthTokenSet(
+            access_token="at_refreshed",
+            token_type="Bearer",
+            refresh_token="rt_new",
+            expires_in=3600,
+            issued_at=time.time(),
+        )
+    )
+    provider.revoke_token = AsyncMock()
+    provider.build_authorize_url.return_value = "https://mock.idp/authorize?state=test"
+    return provider
+
+
+def _make_mock_deploy_settings() -> MagicMock:
+    """Create a mock DeploySettings."""
+    settings = MagicMock()
+    settings.auth_session_cookie = "pywry_session"
+    settings.default_roles = ["viewer"]
+    settings.admin_users = ["admin@test.com"]
+    return settings
+
+
+def _make_mock_session_store() -> MagicMock:
+    """Create a mock SessionStore."""
+    store = MagicMock()
+    store.create_session = AsyncMock()
+    store.get_session = AsyncMock(return_value=None)
+    store.delete_session = AsyncMock()
+    return store
+
+
+def _create_test_app(
+    provider: MagicMock | None = None,
+    session_store: MagicMock | None = None,
+    token_store: MemoryTokenStore | None = None,
+    deploy_settings: MagicMock | None = None,
+    auth_config: AuthConfig | None = None,
+) -> FastAPI:
+    """Create a FastAPI app with the auth router mounted."""
+    app = FastAPI()
+    provider = provider or _make_mock_provider()
+    session_store = session_store or _make_mock_session_store()
+    token_store = token_store or MemoryTokenStore()
+    deploy_settings = deploy_settings or _make_mock_deploy_settings()
+    auth_config = auth_config or AuthConfig(
+        enabled=True,
+        token_secret="test-secret-key-for-testing",
+        session_ttl=3600,
+    )
+
+    router = create_auth_router(
+        provider=provider,
+        session_store=session_store,
+        token_store=token_store,
+        deploy_settings=deploy_settings,
+        auth_config=auth_config,
+    )
+    app.include_router(router)
+    return app
+
+
+# ── Tests ────────────────────────────────────────────────────────────
+
+
+class TestLoginRoute:
+    """Tests for GET /auth/login."""
+
+    def test_login_redirects(self) -> None:
+        """Login endpoint redirects to provider."""
+        app = _create_test_app()
+        client = TestClient(app, follow_redirects=False)
+        resp = client.get("/auth/login")
+        assert resp.status_code == 302
+        assert "mock.idp" in resp.headers["location"]
+
+    def test_login_stores_pending_state(self) -> None:
+        """Login endpoint stores pending auth state."""
+        _pending_auth_states.clear()
+        app = _create_test_app()
+        client = TestClient(app, follow_redirects=False)
+        client.get("/auth/login")
+        assert len(_pending_auth_states) >= 1
+
+
+class TestCallbackRoute:
+    """Tests for GET /auth/callback."""
+
+    def test_callback_missing_state(self) -> None:
+        """Callback without state returns 400."""
+        app = _create_test_app()
+        client = TestClient(app)
+        resp = client.get("/auth/callback?code=test_code")
+        assert resp.status_code == 400
+        assert resp.json()["error"] == "invalid_state"
+
+    def test_callback_invalid_state(self) -> None:
+        """Callback with unknown state returns 400."""
+        app = _create_test_app()
+        client = TestClient(app)
+        resp = client.get("/auth/callback?code=test_code&state=bogus")
+        assert resp.status_code == 400
+        assert resp.json()["error"] == "invalid_state"
+
+    def test_callback_provider_error(self) -> None:
+        """Callback with error param returns 400."""
+        app = _create_test_app()
+        client = TestClient(app)
+        resp = client.get("/auth/callback?error=access_denied&error_description=User+denied")
+        assert resp.status_code == 400
+        data = resp.json()
+        assert data["error"] == "access_denied"
+
+    def test_callback_missing_code(self) -> None:
+        """Callback without code returns 400."""
+        _pending_auth_states.clear()
+        _pending_auth_states["valid_state"] = {
+            "pkce_verifier": None,
+            "redirect_uri": "http://testserver/auth/callback",
+            "nonce": "test_nonce",
+            "created_at": time.time(),
+        }
+        app = _create_test_app()
+        client = TestClient(app)
+        resp = client.get("/auth/callback?state=valid_state")
+        assert resp.status_code == 400
+        assert resp.json()["error"] == "missing_code"
+
+    def test_callback_success(self) -> None:
+        """Successful callback creates session and redirects."""
+        _pending_auth_states.clear()
+        _pending_auth_states["good_state"] = {
+            "pkce_verifier": "verifier123",
+            "redirect_uri": "http://testserver/auth/callback",
+            "nonce": "test_nonce",
+            "created_at": time.time(),
+        }
+
+        session_store = _make_mock_session_store()
+        token_store = MemoryTokenStore()
+        app = _create_test_app(
+            session_store=session_store,
+            token_store=token_store,
+        )
+        client = TestClient(app, follow_redirects=False)
+        resp = client.get("/auth/callback?code=auth_code_123&state=good_state")
+
+        assert resp.status_code == 302
+        assert resp.headers["location"] == "/"
+        assert "pywry_session" in resp.headers.get("set-cookie", "")
+
+        # Verify session was created
+        session_store.create_session.assert_called_once()
+
+    def test_callback_exchange_failure(self) -> None:
+        """Token exchange failure returns 500 with generic error (no exception leak)."""
+        _pending_auth_states.clear()
+        _pending_auth_states["fail_state"] = {
+            "pkce_verifier": None,
+            "redirect_uri": "http://testserver/auth/callback",
+            "nonce": "test_nonce",
+            "created_at": time.time(),
+        }
+
+        provider = _make_mock_provider()
+        provider.exchange_code = AsyncMock(side_effect=Exception("Network error"))
+
+        app = _create_test_app(provider=provider)
+        client = TestClient(app)
+        resp = client.get("/auth/callback?code=bad_code&state=fail_state")
+        assert resp.status_code == 500
+        data = resp.json()
+        assert data["error"] == "token_exchange_failed"
+        # Must NOT leak internal exception message
+        assert "Network error" not in data.get("error_description", "")
+        assert data["error_description"] == "An internal error occurred"
+
+    def test_callback_consumes_state(self) -> None:
+        """State is single-use (removed after callback)."""
+        _pending_auth_states.clear()
+        _pending_auth_states["once_state"] = {
+            "pkce_verifier": None,
+            "redirect_uri": "http://testserver/auth/callback",
+            "nonce": "test_nonce",
+            "created_at": time.time(),
+        }
+
+        app = _create_test_app()
+        client = TestClient(app, follow_redirects=False)
+        # First call succeeds
+        resp1 = client.get("/auth/callback?code=code1&state=once_state")
+        assert resp1.status_code == 302
+
+        # Second call fails
+        resp2 = client.get("/auth/callback?code=code2&state=once_state")
+        assert resp2.status_code == 400
+
+
+class TestAuthenticatedRoutes:
+    """Tests for routes requiring authentication."""
+
+    def _make_authenticated_app(self) -> tuple[FastAPI, MagicMock, MemoryTokenStore]:
+        """Create an app with session middleware that injects a mock session."""
+        provider = _make_mock_provider()
+        session_store = _make_mock_session_store()
+        token_store = MemoryTokenStore()
+        deploy_settings = _make_mock_deploy_settings()
+        auth_config = AuthConfig(
+            enabled=True,
+            token_secret="test-secret",
+            session_ttl=3600,
+        )
+
+        app = FastAPI()
+        router = create_auth_router(
+            provider=provider,
+            session_store=session_store,
+            token_store=token_store,
+            deploy_settings=deploy_settings,
+            auth_config=auth_config,
+        )
+        app.include_router(router)
+
+        return app, provider, token_store
+
+    def test_status_unauthenticated(self) -> None:
+        """Status returns authenticated=false when no session."""
+        app, _, _ = self._make_authenticated_app()
+        client = TestClient(app)
+        resp = client.get("/auth/status")
+        assert resp.status_code == 200
+        assert resp.json()["authenticated"] is False
+
+    def test_userinfo_unauthenticated(self) -> None:
+        """Userinfo returns 401 when no session."""
+        app, _, _ = self._make_authenticated_app()
+        client = TestClient(app)
+        resp = client.get("/auth/userinfo")
+        assert resp.status_code == 401
+
+    def test_refresh_unauthenticated(self) -> None:
+        """Refresh returns 401 when no session."""
+        app, _, _ = self._make_authenticated_app()
+        client = TestClient(app)
+        resp = client.post("/auth/refresh", headers={"origin": "http://testserver"})
+        assert resp.status_code == 401
+
+    def test_logout_no_session(self) -> None:
+        """Logout without session still returns success."""
+        app, _, _ = self._make_authenticated_app()
+        client = TestClient(app)
+        resp = client.post("/auth/logout", headers={"origin": "http://testserver"})
+        assert resp.status_code == 200
+        assert resp.json()["success"] is True
+
+
+class TestCleanupExpiredStates:
+    """Tests for cleanup_expired_states utility."""
+
+    def test_cleanup_removes_old_states(self) -> None:
+        """Expired states are removed."""
+        _pending_auth_states.clear()
+        _pending_auth_states["old"] = {"created_at": time.time() - 700}
+        _pending_auth_states["fresh"] = {"created_at": time.time()}
+
+        removed = cleanup_expired_states(max_age=600.0)
+        assert removed == 1
+        assert "old" not in _pending_auth_states
+        assert "fresh" in _pending_auth_states
+
+    def test_cleanup_empty(self) -> None:
+        """No-op when no states exist."""
+        _pending_auth_states.clear()
+        removed = cleanup_expired_states()
+        assert removed == 0
+
+    def test_admin_role_for_admin_user(self) -> None:
+        """Admin users get admin role in session."""
+        _pending_auth_states.clear()
+        _pending_auth_states["admin_state"] = {
+            "pkce_verifier": None,
+            "redirect_uri": "http://testserver/auth/callback",
+            "nonce": "test_nonce",
+            "created_at": time.time(),
+        }
+
+        provider = _make_mock_provider()
+        provider.get_userinfo = AsyncMock(return_value={"sub": "admin1", "email": "admin@test.com"})
+
+        session_store = _make_mock_session_store()
+        deploy_settings = _make_mock_deploy_settings()
+
+        app = _create_test_app(
+            provider=provider,
+            session_store=session_store,
+            deploy_settings=deploy_settings,
+        )
+        client = TestClient(app, follow_redirects=False)
+        resp = client.get("/auth/callback?code=admin_code&state=admin_state")
+        assert resp.status_code == 302
+
+        # Verify the created session has admin role
+        session_store.create_session.assert_called_once()
+        call_kwargs = session_store.create_session.call_args[1]
+        assert "admin" in call_kwargs["roles"]
+
+
+class TestCSRFOriginVerification:
+    """Tests for CSRF origin verification on POST routes."""
+
+    def _make_app(self):
+        return _create_test_app()
+
+    def test_refresh_rejects_missing_origin(self) -> None:
+        """POST /auth/refresh without Origin header returns 403."""
+        app = self._make_app()
+        client = TestClient(app)
+        resp = client.post("/auth/refresh")
+        assert resp.status_code == 403
+        assert resp.json()["error"] == "csrf_failed"
+
+    def test_logout_rejects_missing_origin(self) -> None:
+        """POST /auth/logout without Origin header returns 403."""
+        app = self._make_app()
+        client = TestClient(app)
+        resp = client.post("/auth/logout")
+        assert resp.status_code == 403
+        assert resp.json()["error"] == "csrf_failed"
+
+    def test_refresh_rejects_cross_origin(self) -> None:
+        """POST /auth/refresh with cross-origin Origin returns 403."""
+        app = self._make_app()
+        client = TestClient(app)
+        resp = client.post(
+            "/auth/refresh",
+            headers={"origin": "https://evil.example.com"},
+        )
+        assert resp.status_code == 403
+
+    def test_logout_accepts_same_origin(self) -> None:
+        """POST /auth/logout with matching Origin is accepted (passes CSRF)."""
+        app = self._make_app()
+        client = TestClient(app)
+        # testserver base URL is http://testserver
+        resp = client.post(
+            "/auth/logout",
+            headers={"origin": "http://testserver"},
+        )
+        # Should pass CSRF and reach logout logic (200 success, no session)
+        assert resp.status_code == 200
+        assert resp.json()["success"] is True
+
+
+class TestLoginRateLimiting:
+    """Tests for rate limiting on /auth/login."""
+
+    def test_login_rate_limit_exceeded(self) -> None:
+        """Login returns 429 after too many attempts."""
+        _login_rate_limiter.reset()
+        app = _create_test_app()
+        client = TestClient(app, follow_redirects=False)
+
+        # Exhaust the rate limit (default 10 per 60s)
+        for _ in range(10):
+            resp = client.get("/auth/login")
+            assert resp.status_code == 302
+
+        # 11th request should be rate limited
+        resp = client.get("/auth/login")
+        assert resp.status_code == 429
+        assert resp.json()["error"] == "rate_limited"
+
+        _login_rate_limiter.reset()
+
+    def test_login_within_limit(self) -> None:
+        """Login succeeds within rate limit."""
+        _login_rate_limiter.reset()
+        app = _create_test_app()
+        client = TestClient(app, follow_redirects=False)
+
+        resp = client.get("/auth/login")
+        assert resp.status_code == 302
+
+        _login_rate_limiter.reset()
diff --git a/pywry/tests/test_auth_flow_integration.py b/pywry/tests/test_auth_flow_integration.py
new file mode 100644
index 0000000..9b248ec
--- /dev/null
+++ b/pywry/tests/test_auth_flow_integration.py
@@ -0,0 +1,279 @@
+"""Integration tests for OAuth2 flow manager."""
+
+# pylint: disable=consider-using-with
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import threading
+import time
+
+from typing import Any
+from unittest.mock import AsyncMock, MagicMock
+from urllib.parse import urlencode
+from urllib.request import urlopen
+
+import pytest
+
+from pywry.auth.callback_server import OAuthCallbackServer
+from pywry.auth.flow import AuthFlowManager
+from pywry.auth.token_store import MemoryTokenStore
+from pywry.exceptions import (
+    AuthenticationError,
+    AuthFlowCancelled,
+    AuthFlowTimeout,
+)
+from pywry.state.types import AuthFlowState, OAuthTokenSet
+
+
+# ── Helpers ──────────────────────────────────────────────────────────
+
+
+def _make_mock_provider(**kwargs: Any) -> MagicMock:
+    """Create a mock OAuthProvider."""
+    provider = MagicMock()
+    provider.__class__.__name__ = "MockProvider"
+    provider.build_authorize_url.return_value = "https://mock.idp/authorize?state=test"
+
+    tokens = OAuthTokenSet(
+        access_token="at_mock",
+        token_type="Bearer",
+        refresh_token="rt_mock",
+        expires_in=3600,
+        issued_at=time.time(),
+    )
+    provider.exchange_code = AsyncMock(return_value=tokens)
+    provider.get_userinfo = AsyncMock(return_value={"sub": "user123", "email": "test@example.com"})
+    provider.refresh_tokens = AsyncMock(return_value=tokens)
+    provider.revoke_token = AsyncMock()
+
+    for k, v in kwargs.items():
+        setattr(provider, k, v)
+
+    return provider
+
+
+def _send_callback_to_server(
+    port: int, code: str = "test_code", state: str = "test_state", delay: float = 0.3
+) -> None:
+    """Send a simulated OAuth callback to the server."""
+
+    def _send() -> None:
+        time.sleep(delay)
+        params = urlencode({"code": code, "state": state})
+        url = f"http://127.0.0.1:{port}/callback?{params}"
+        with contextlib.suppress(Exception):
+            urlopen(url, timeout=5)  # noqa: S310
+
+    t = threading.Thread(target=_send, daemon=True)
+    t.start()
+
+
+# ── Tests ────────────────────────────────────────────────────────────
+
+
+class TestAuthFlowManagerNative:
+    """Tests for native mode auth flow."""
+
+    def test_initial_state(self) -> None:
+        """Flow starts in PENDING state."""
+        provider = _make_mock_provider()
+        flow = AuthFlowManager(provider=provider)
+        assert flow.flow_state == AuthFlowState.PENDING
+
+    def test_run_native_timeout(self) -> None:
+        """Flow times out if no callback received."""
+        provider = _make_mock_provider()
+        flow = AuthFlowManager(provider=provider, auth_timeout=0.5)
+
+        with pytest.raises(AuthFlowTimeout):
+            flow.run_native()
+
+        assert flow.flow_state == AuthFlowState.TIMED_OUT
+
+    def test_cancel_flow(self) -> None:
+        """Cancelling flow raises AuthFlowCancelled."""
+        provider = _make_mock_provider()
+        flow = AuthFlowManager(provider=provider, auth_timeout=5.0)
+
+        # Cancel after a brief delay
+        def cancel_soon() -> None:
+            time.sleep(0.3)
+            flow.cancel()
+
+        t = threading.Thread(target=cancel_soon, daemon=True)
+        t.start()
+
+        with pytest.raises(AuthFlowCancelled):
+            flow.run_native()
+
+        assert flow.flow_state == AuthFlowState.CANCELLED
+
+    def test_run_native_success(self) -> None:
+        """Successful native flow returns tokens and user_info."""
+        provider = _make_mock_provider()
+        flow = AuthFlowManager(provider=provider, auth_timeout=10.0, use_pkce=True)
+
+        # We need to intercept the callback server to send the response
+        original_start = OAuthCallbackServer.start
+
+        def patched_start(self_server: OAuthCallbackServer) -> str:  # pylint: disable=unused-variable
+            uri = original_start(self_server)
+            # Now we know the port — send callback with correct state
+            # The state is generated inside run_native, so we need to
+            # grab it from the authorize URL
+            return uri
+
+        # Instead of patching start, we'll intercept build_authorize_url
+        # to capture the state, then send the callback with that state
+        captured_state: list[str] = []
+
+        def capture_authorize_url(
+            redirect_uri: str,  # pylint: disable=unused-argument
+            state: str,
+            pkce: Any = None,  # pylint: disable=unused-argument
+            extra_params: Any = None,  # pylint: disable=unused-argument
+        ) -> str:
+            captured_state.append(state)
+            return f"https://mock.idp/authorize?state={state}&redirect_uri={redirect_uri}"
+
+        provider.build_authorize_url.side_effect = capture_authorize_url
+
+        def send_callback_later() -> None:
+            """Wait for the server to start, then send callback."""
+            time.sleep(0.5)
+            # Find the port from the flow's callback server
+            if flow._callback_server and flow._callback_server._actual_port:
+                port = flow._callback_server._actual_port
+                state = captured_state[0] if captured_state else "unknown"
+                _send_callback_to_server(port, code="auth_code", state=state, delay=0.0)
+
+        t = threading.Thread(target=send_callback_later, daemon=True)
+        t.start()
+
+        result = flow.run_native()
+
+        assert result.success is True
+        assert result.tokens is not None
+        assert result.tokens.access_token == "at_mock"
+        assert result.user_info.get("sub") == "user123"
+        assert flow.flow_state == AuthFlowState.COMPLETED
+
+    def test_run_native_stores_tokens(self) -> None:
+        """Native flow stores tokens when token_store is provided."""
+        provider = _make_mock_provider()
+        token_store = MemoryTokenStore()
+        flow = AuthFlowManager(
+            provider=provider,
+            token_store=token_store,
+            auth_timeout=10.0,
+        )
+
+        captured_state: list[str] = []
+
+        def capture_authorize_url(
+            redirect_uri: str,  # pylint: disable=unused-argument
+            state: str,
+            **kwargs: Any,  # pylint: disable=unused-argument
+        ) -> str:
+            captured_state.append(state)
+            return f"https://mock.idp/authorize?state={state}"
+
+        provider.build_authorize_url.side_effect = capture_authorize_url
+
+        def send_callback_later() -> None:
+            time.sleep(0.5)
+            if flow._callback_server and flow._callback_server._actual_port:
+                port = flow._callback_server._actual_port
+                state = captured_state[0] if captured_state else ""
+                _send_callback_to_server(port, code="code", state=state, delay=0.0)
+
+        t = threading.Thread(target=send_callback_later, daemon=True)
+        t.start()
+
+        result = flow.run_native()
+        assert result.success
+
+        # Verify tokens were stored
+        stored = asyncio.run(token_store.load("user123"))
+        assert stored is not None
+        assert stored.access_token == "at_mock"
+
+    def test_run_native_provider_error(self) -> None:
+        """Provider error in callback raises AuthenticationError."""
+        provider = _make_mock_provider()
+        flow = AuthFlowManager(provider=provider, auth_timeout=10.0)
+
+        def send_error_callback() -> None:
+            time.sleep(0.5)
+            if flow._callback_server and flow._callback_server._actual_port:
+                port = flow._callback_server._actual_port
+                params = urlencode({"error": "access_denied", "error_description": "User denied"})
+                with contextlib.suppress(Exception):
+                    urlopen(f"http://127.0.0.1:{port}/callback?{params}", timeout=5)
+
+        t = threading.Thread(target=send_error_callback, daemon=True)
+        t.start()
+
+        with pytest.raises(AuthenticationError, match=r"access_denied|User denied"):
+            flow.run_native()
+
+        assert flow.flow_state == AuthFlowState.FAILED
+
+    def test_run_native_state_mismatch(self) -> None:
+        """State mismatch raises AuthenticationError."""
+        provider = _make_mock_provider()
+        flow = AuthFlowManager(provider=provider, auth_timeout=10.0)
+
+        def send_wrong_state() -> None:
+            time.sleep(0.5)
+            if flow._callback_server and flow._callback_server._actual_port:
+                port = flow._callback_server._actual_port
+                _send_callback_to_server(port, code="code", state="wrong_state", delay=0.0)
+
+        t = threading.Thread(target=send_wrong_state, daemon=True)
+        t.start()
+
+        with pytest.raises(AuthenticationError, match=r"[Ss]tate"):
+            flow.run_native()
+
+    def test_show_window_called(self) -> None:
+        """show_window callback is called with authorize URL."""
+        provider = _make_mock_provider()
+        flow = AuthFlowManager(provider=provider, auth_timeout=0.5)
+
+        show_window = MagicMock(return_value="auth-window")
+        close_window = MagicMock()
+
+        with pytest.raises(AuthFlowTimeout):
+            flow.run_native(
+                show_window=show_window,
+                close_window=close_window,
+            )
+
+        show_window.assert_called_once()
+        args = show_window.call_args
+        assert "https://mock.idp" in args[0][0]  # URL
+        assert isinstance(args[0][1], dict)  # config
+
+        # close_window should be called in finally block
+        close_window.assert_called_once_with("auth-window")
+
+
+class TestAuthFlowManagerDeploy:
+    """Tests for deploy mode auth flow."""
+
+    def test_run_deploy(self) -> None:
+        """Deploy mode returns /auth/login URL."""
+        provider = _make_mock_provider()
+        flow = AuthFlowManager(provider=provider)
+        url = flow.run_deploy(base_url="http://localhost:8080")
+        assert url == "http://localhost:8080/auth/login"
+
+    def test_run_deploy_no_base(self) -> None:
+        """Deploy mode with empty base returns relative URL."""
+        provider = _make_mock_provider()
+        flow = AuthFlowManager(provider=provider)
+        url = flow.run_deploy()
+        assert url == "/auth/login"
diff --git a/pywry/tests/test_auth_providers.py b/pywry/tests/test_auth_providers.py
new file mode 100644
index 0000000..157ac58
--- /dev/null
+++ b/pywry/tests/test_auth_providers.py
@@ -0,0 +1,582 @@
+"""Unit tests for OAuth2 provider abstractions."""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import time
+
+from base64 import urlsafe_b64encode
+from unittest.mock import AsyncMock, MagicMock, patch
+from urllib.parse import parse_qs, urlparse
+
+import pytest
+
+from pywry.auth.pkce import PKCEChallenge
+from pywry.auth.providers import (
+    GenericOIDCProvider,
+    GitHubProvider,
+    GoogleProvider,
+    MicrosoftProvider,
+    create_provider_from_settings,
+)
+from pywry.exceptions import AuthenticationError, TokenError, TokenRefreshError
+from pywry.state.types import OAuthTokenSet
+
+
+# ── PKCE Tests ──────────────────────────────────────────────────────
+
+
+class TestPKCEChallenge:
+    """Tests for PKCEChallenge generation."""
+
+    def test_generate_returns_challenge(self) -> None:
+        """PKCEChallenge.generate() returns a valid challenge pair."""
+        pkce = PKCEChallenge.generate()
+        assert pkce.verifier
+        assert pkce.challenge
+        assert pkce.method == "S256"
+
+    def test_verifier_is_url_safe(self) -> None:
+        """Verifier contains only URL-safe characters."""
+        pkce = PKCEChallenge.generate()
+        # URL-safe base64 chars: A-Z, a-z, 0-9, -, _
+        import re
+
+        assert re.match(r"^[A-Za-z0-9_-]+$", pkce.verifier)
+
+    def test_challenge_matches_verifier_sha256(self) -> None:
+        """Challenge is the base64url SHA-256 of the verifier."""
+        pkce = PKCEChallenge.generate()
+        expected_digest = hashlib.sha256(pkce.verifier.encode("ascii")).digest()
+        expected_challenge = urlsafe_b64encode(expected_digest).rstrip(b"=").decode("ascii")
+        assert pkce.challenge == expected_challenge
+
+    def test_generate_uniqueness(self) -> None:
+        """Each generation produces unique values."""
+        a = PKCEChallenge.generate()
+        b = PKCEChallenge.generate()
+        assert a.verifier != b.verifier
+        assert a.challenge != b.challenge
+
+    def test_generate_custom_length(self) -> None:
+        """Custom length produces different sized verifiers."""
+        short = PKCEChallenge.generate(length=32)
+        long = PKCEChallenge.generate(length=96)
+        # Longer length should generally produce longer verifier
+        assert len(short.verifier) < len(long.verifier)
+
+    def test_frozen_dataclass(self) -> None:
+        """PKCEChallenge is immutable."""
+        pkce = PKCEChallenge.generate()
+        with pytest.raises(AttributeError):
+            pkce.verifier = "new"  # type: ignore[misc]
+
+
+# ── Provider URL Building ───────────────────────────────────────────
+
+
+class TestOAuthProviderURLBuilding:
+    """Tests for OAuthProvider.build_authorize_url()."""
+
+    def test_build_url_basic(self) -> None:
+        """Basic URL building with required params."""
+        provider = GoogleProvider(client_id="test-id", client_secret="test-secret")
+        url = provider.build_authorize_url(
+            redirect_uri="http://localhost:8080/callback",
+            state="test-state",
+        )
+        parsed = urlparse(url)
+        params = parse_qs(parsed.query)
+
+        assert parsed.scheme == "https"
+        assert "accounts.google.com" in parsed.netloc
+        assert params["client_id"] == ["test-id"]
+        assert params["redirect_uri"] == ["http://localhost:8080/callback"]
+        assert params["state"] == ["test-state"]
+        assert params["response_type"] == ["code"]
+
+    def test_build_url_with_pkce(self) -> None:
+        """URL includes PKCE challenge when provided."""
+        provider = GoogleProvider(client_id="test-id")
+        pkce = PKCEChallenge.generate()
+        url = provider.build_authorize_url(
+            redirect_uri="http://localhost/cb",
+            state="s",
+            pkce=pkce,
+        )
+        params = parse_qs(urlparse(url).query)
+        assert params["code_challenge"] == [pkce.challenge]
+        assert params["code_challenge_method"] == ["S256"]
+
+    def test_build_url_with_scopes(self) -> None:
+        """URL includes scopes."""
+        provider = GenericOIDCProvider(
+            client_id="c",
+            scopes=["openid", "email"],
+            authorize_url="https://idp.example.com/authorize",
+        )
+        url = provider.build_authorize_url(redirect_uri="http://localhost/cb", state="s")
+        params = parse_qs(urlparse(url).query)
+        assert params["scope"] == ["openid email"]
+
+    def test_google_includes_access_type(self) -> None:
+        """Google provider adds access_type=offline."""
+        provider = GoogleProvider(client_id="test-id")
+        url = provider.build_authorize_url(redirect_uri="http://localhost/cb", state="s")
+        params = parse_qs(urlparse(url).query)
+        assert params["access_type"] == ["offline"]
+        assert params["prompt"] == ["consent"]
+
+    def test_extra_params(self) -> None:
+        """Extra params are included."""
+        provider = GitHubProvider(client_id="test-id")
+        url = provider.build_authorize_url(
+            redirect_uri="http://localhost/cb",
+            state="s",
+            extra_params={"login": "user@example.com"},
+        )
+        params = parse_qs(urlparse(url).query)
+        assert params["login"] == ["user@example.com"]
+
+
+# ── Provider Preset URLs ────────────────────────────────────────────
+
+
+class TestProviderPresets:
+    """Tests for preset provider URLs."""
+
+    def test_google_urls(self) -> None:
+        """Google provider has correct preset URLs."""
+        g = GoogleProvider(client_id="c")
+        assert "accounts.google.com" in g.authorize_url
+        assert "googleapis.com/token" in g.token_url
+        assert "googleapis.com" in g.userinfo_url
+
+    def test_github_urls(self) -> None:
+        """GitHub provider has correct preset URLs."""
+        gh = GitHubProvider(client_id="c")
+        assert "github.com/login/oauth/authorize" in gh.authorize_url
+        assert "github.com/login/oauth/access_token" in gh.token_url
+        assert "api.github.com/user" in gh.userinfo_url
+
+    def test_microsoft_urls(self) -> None:
+        """Microsoft provider has correct preset URLs."""
+        ms = MicrosoftProvider(client_id="c", tenant_id="my-tenant")
+        assert "my-tenant" in ms.authorize_url
+        assert "my-tenant" in ms.token_url
+        assert "graph.microsoft.com" in ms.userinfo_url
+        assert ms.tenant_id == "my-tenant"
+
+    def test_microsoft_default_tenant(self) -> None:
+        """Microsoft defaults to 'common' tenant."""
+        ms = MicrosoftProvider(client_id="c")
+        assert "common" in ms.authorize_url
+
+    def test_github_scopes(self) -> None:
+        """GitHub has correct default scopes."""
+        gh = GitHubProvider(client_id="c")
+        assert "read:user" in gh.scopes
+        assert "user:email" in gh.scopes
+
+    def test_google_scopes(self) -> None:
+        """Google has correct default scopes."""
+        g = GoogleProvider(client_id="c")
+        assert "openid" in g.scopes
+        assert "email" in g.scopes
+
+
+# ── Token Exchange (Mocked) ─────────────────────────────────────────
+
+
+class TestTokenExchange:
+    """Tests for OAuthProvider.exchange_code() with mocked HTTP."""
+
+    @pytest.fixture()
+    def mock_response(self) -> dict:
+        """Standard token response."""
+        return {
+            "access_token": "at_test123",
+            "token_type": "Bearer",
+            "refresh_token": "rt_test123",
+            "expires_in": 3600,
+            "scope": "openid email",
+            "id_token": "eyJhbGci...",
+        }
+
+    def test_exchange_code_success(self, mock_response: dict) -> None:
+        """Successful code exchange returns OAuthTokenSet."""
+        provider = GenericOIDCProvider(
+            client_id="c",
+            client_secret="s",
+            token_url="https://idp.example.com/token",
+            require_id_token_validation=False,
+        )
+
+        mock_resp = MagicMock()
+        mock_resp.json.return_value = mock_response
+        mock_resp.raise_for_status = MagicMock()
+
+        with patch("httpx.AsyncClient") as mock_client:
+            mock_instance = AsyncMock()
+            mock_instance.post.return_value = mock_resp
+            mock_instance.__aenter__ = AsyncMock(return_value=mock_instance)
+            mock_instance.__aexit__ = AsyncMock(return_value=False)
+            mock_client.return_value = mock_instance
+
+            tokens = asyncio.run(
+                provider.exchange_code("code123", "http://localhost/cb", "verifier")
+            )
+
+        assert tokens.access_token == "at_test123"
+        assert tokens.refresh_token == "rt_test123"
+        assert tokens.expires_in == 3600
+        assert tokens.token_type == "Bearer"
+
+    def test_exchange_code_error(self) -> None:
+        """Failed code exchange raises TokenError."""
+        provider = GenericOIDCProvider(
+            client_id="c",
+            token_url="https://idp.example.com/token",
+        )
+
+        import httpx
+
+        mock_resp = MagicMock()
+        mock_resp.status_code = 400
+        mock_resp.raise_for_status.side_effect = httpx.HTTPStatusError(
+            "Bad Request", request=MagicMock(), response=mock_resp
+        )
+
+        with patch("httpx.AsyncClient") as mock_client:
+            mock_instance = AsyncMock()
+            mock_instance.post.return_value = mock_resp
+            mock_instance.__aenter__ = AsyncMock(return_value=mock_instance)
+            mock_instance.__aexit__ = AsyncMock(return_value=False)
+            mock_client.return_value = mock_instance
+
+            with pytest.raises(TokenError):
+                asyncio.run(provider.exchange_code("bad_code", "http://localhost/cb"))
+
+    def test_github_exchange_code_with_error_response(self) -> None:
+        """GitHub returns error in JSON body, not HTTP status."""
+        provider = GitHubProvider(client_id="c", client_secret="s")
+
+        mock_resp = MagicMock()
+        mock_resp.json.return_value = {
+            "error": "bad_verification_code",
+            "error_description": "The code passed is incorrect or expired.",
+        }
+        mock_resp.raise_for_status = MagicMock()
+
+        with patch("httpx.AsyncClient") as mock_client:
+            mock_instance = AsyncMock()
+            mock_instance.post.return_value = mock_resp
+            mock_instance.__aenter__ = AsyncMock(return_value=mock_instance)
+            mock_instance.__aexit__ = AsyncMock(return_value=False)
+            mock_client.return_value = mock_instance
+
+            with pytest.raises(TokenError, match="expired"):
+                asyncio.run(provider.exchange_code("bad", "http://localhost/cb"))
+
+    def test_refresh_tokens_success(self, mock_response: dict) -> None:
+        """Successful token refresh."""
+        provider = GenericOIDCProvider(
+            client_id="c",
+            client_secret="s",
+            token_url="https://idp.example.com/token",
+        )
+
+        mock_resp = MagicMock()
+        mock_resp.json.return_value = mock_response
+        mock_resp.raise_for_status = MagicMock()
+
+        with patch("httpx.AsyncClient") as mock_client:
+            mock_instance = AsyncMock()
+            mock_instance.post.return_value = mock_resp
+            mock_instance.__aenter__ = AsyncMock(return_value=mock_instance)
+            mock_instance.__aexit__ = AsyncMock(return_value=False)
+            mock_client.return_value = mock_instance
+
+            tokens = asyncio.run(provider.refresh_tokens("rt_old"))
+
+        assert tokens.access_token == "at_test123"
+
+    def test_refresh_tokens_failure(self) -> None:
+        """Failed token refresh raises TokenRefreshError."""
+        provider = GenericOIDCProvider(
+            client_id="c",
+            token_url="https://idp.example.com/token",
+        )
+
+        import httpx
+
+        mock_resp = MagicMock()
+        mock_resp.status_code = 401
+        mock_resp.raise_for_status.side_effect = httpx.HTTPStatusError(
+            "Unauthorized", request=MagicMock(), response=mock_resp
+        )
+
+        with patch("httpx.AsyncClient") as mock_client:
+            mock_instance = AsyncMock()
+            mock_instance.post.return_value = mock_resp
+            mock_instance.__aenter__ = AsyncMock(return_value=mock_instance)
+            mock_instance.__aexit__ = AsyncMock(return_value=False)
+            mock_client.return_value = mock_instance
+
+            with pytest.raises(TokenRefreshError):
+                asyncio.run(provider.refresh_tokens("rt_bad"))
+
+
+# ── Token Revocation ────────────────────────────────────────────────
+
+
+class TestTokenRevocation:
+    """Tests for OAuthProvider.revoke_token() implementations."""
+
+    def test_base_revoke_no_url(self) -> None:
+        """Base provider without revocation_url returns False."""
+        provider = GenericOIDCProvider(
+            client_id="c",
+            token_url="https://idp.example.com/token",
+        )
+        result = asyncio.run(provider.revoke_token("some_token"))
+        assert result is False
+
+    def test_base_revoke_with_url_success(self) -> None:
+        """Provider with revocation_url posts to it and returns True."""
+        provider = GenericOIDCProvider(
+            client_id="c",
+            token_url="https://idp.example.com/token",
+            revocation_url="https://idp.example.com/revoke",
+        )
+
+        mock_resp = MagicMock()
+        mock_resp.is_success = True
+
+        with patch("httpx.AsyncClient") as mock_client:
+            mock_instance = AsyncMock()
+            mock_instance.post.return_value = mock_resp
+            mock_instance.__aenter__ = AsyncMock(return_value=mock_instance)
+            mock_instance.__aexit__ = AsyncMock(return_value=False)
+            mock_client.return_value = mock_instance
+
+            result = asyncio.run(provider.revoke_token("token_to_revoke"))
+
+        assert result is True
+        mock_instance.post.assert_called_once()
+        call_kwargs = mock_instance.post.call_args
+        assert call_kwargs[1]["data"]["token"] == "token_to_revoke"
+        assert call_kwargs[1]["data"]["client_id"] == "c"
+
+    def test_base_revoke_http_error(self) -> None:
+        """Provider returns False when revocation request fails."""
+        import httpx
+
+        provider = GenericOIDCProvider(
+            client_id="c",
+            token_url="https://idp.example.com/token",
+            revocation_url="https://idp.example.com/revoke",
+        )
+
+        with patch("httpx.AsyncClient") as mock_client:
+            mock_instance = AsyncMock()
+            mock_instance.post.side_effect = httpx.HTTPError("connection failed")
+            mock_instance.__aenter__ = AsyncMock(return_value=mock_instance)
+            mock_instance.__aexit__ = AsyncMock(return_value=False)
+            mock_client.return_value = mock_instance
+
+            result = asyncio.run(provider.revoke_token("token_to_revoke"))
+
+        assert result is False
+
+    def test_google_revoke_uses_correct_url(self) -> None:
+        """Google provider has revocation_url preconfigured."""
+        provider = GoogleProvider(client_id="c", client_secret="s")
+        assert provider.revocation_url == "https://oauth2.googleapis.com/revoke"
+
+    def test_oidc_revoke_triggers_discovery(self) -> None:
+        """OIDC revoke_token calls _discover() before revoking."""
+        provider = GenericOIDCProvider(
+            client_id="c",
+            issuer_url="https://idp.example.com",
+            token_url="https://idp.example.com/token",
+        )
+
+        with patch.object(provider, "_discover", new_callable=AsyncMock) as mock_disc:
+            result = asyncio.run(provider.revoke_token("tok"))
+
+        mock_disc.assert_awaited_once()
+        # No revocation_url discovered (mocked), so returns False
+        assert result is False
+
+    def test_github_revoke_success(self) -> None:
+        """GitHub revoke_token uses DELETE /applications/{id}/token."""
+        provider = GitHubProvider(client_id="gh_id", client_secret="gh_secret")
+
+        mock_resp = MagicMock()
+        mock_resp.status_code = 204
+
+        with patch("httpx.AsyncClient") as mock_client:
+            mock_instance = AsyncMock()
+            mock_instance.request.return_value = mock_resp
+            mock_instance.__aenter__ = AsyncMock(return_value=mock_instance)
+            mock_instance.__aexit__ = AsyncMock(return_value=False)
+            mock_client.return_value = mock_instance
+
+            result = asyncio.run(provider.revoke_token("ghp_abc123"))
+
+        assert result is True
+        call_args = mock_instance.request.call_args
+        assert call_args[0][0] == "DELETE"
+        assert "applications/gh_id/token" in call_args[0][1]
+        assert call_args[1]["json"]["access_token"] == "ghp_abc123"
+        assert call_args[1]["auth"] == ("gh_id", "gh_secret")
+
+    def test_github_revoke_no_secret(self) -> None:
+        """GitHub revoke returns False without client_secret."""
+        provider = GitHubProvider(client_id="gh_id")
+        result = asyncio.run(provider.revoke_token("ghp_abc123"))
+        assert result is False
+
+    def test_github_revoke_failure(self) -> None:
+        """GitHub revoke returns False on non-204 status."""
+        provider = GitHubProvider(client_id="gh_id", client_secret="gh_secret")
+
+        mock_resp = MagicMock()
+        mock_resp.status_code = 404
+
+        with patch("httpx.AsyncClient") as mock_client:
+            mock_instance = AsyncMock()
+            mock_instance.request.return_value = mock_resp
+            mock_instance.__aenter__ = AsyncMock(return_value=mock_instance)
+            mock_instance.__aexit__ = AsyncMock(return_value=False)
+            mock_client.return_value = mock_instance
+
+            result = asyncio.run(provider.revoke_token("ghp_abc123"))
+
+        assert result is False
+
+    def test_microsoft_no_revocation(self) -> None:
+        """Microsoft provider has no revocation endpoint."""
+        provider = MicrosoftProvider(client_id="c", client_secret="s")
+        assert provider.revocation_url == ""
+        result = asyncio.run(provider.revoke_token("tok"))
+        assert result is False
+
+
+# ── Provider Factory ────────────────────────────────────────────────
+
+
+class TestCreateProviderFromSettings:
+    """Tests for create_provider_from_settings()."""
+
+    def _make_settings(self, **kwargs: object) -> MagicMock:
+        """Create a mock settings object."""
+        defaults = {
+            "provider": "custom",
+            "client_id": "test-id",
+            "client_secret": "test-secret",
+            "scopes": "openid email",
+            "authorize_url": "https://example.com/authorize",
+            "token_url": "https://example.com/token",
+            "userinfo_url": "",
+            "issuer_url": "",
+            "tenant_id": "common",
+        }
+        defaults.update(kwargs)
+        mock = MagicMock()
+        for k, v in defaults.items():
+            setattr(mock, k, v)
+        return mock
+
+    def test_google_provider(self) -> None:
+        """Factory creates GoogleProvider."""
+        settings = self._make_settings(provider="google")
+        provider = create_provider_from_settings(settings)
+        assert isinstance(provider, GoogleProvider)
+
+    def test_github_provider(self) -> None:
+        """Factory creates GitHubProvider."""
+        settings = self._make_settings(provider="github")
+        provider = create_provider_from_settings(settings)
+        assert isinstance(provider, GitHubProvider)
+
+    def test_microsoft_provider(self) -> None:
+        """Factory creates MicrosoftProvider."""
+        settings = self._make_settings(provider="microsoft", tenant_id="my-tenant")
+        provider = create_provider_from_settings(settings)
+        assert isinstance(provider, MicrosoftProvider)
+        assert provider.tenant_id == "my-tenant"
+
+    def test_oidc_provider(self) -> None:
+        """Factory creates GenericOIDCProvider for 'oidc'."""
+        settings = self._make_settings(
+            provider="oidc",
+            issuer_url="https://accounts.google.com",
+        )
+        provider = create_provider_from_settings(settings)
+        assert isinstance(provider, GenericOIDCProvider)
+
+    def test_custom_provider(self) -> None:
+        """Factory creates GenericOIDCProvider for 'custom'."""
+        settings = self._make_settings(provider="custom")
+        provider = create_provider_from_settings(settings)
+        assert isinstance(provider, GenericOIDCProvider)
+
+    def test_custom_requires_urls(self) -> None:
+        """Custom provider without URLs raises AuthenticationError."""
+        settings = self._make_settings(
+            provider="custom",
+            authorize_url="",
+            token_url="",
+        )
+        with pytest.raises(AuthenticationError, match="requires"):
+            create_provider_from_settings(settings)
+
+    def test_unknown_provider(self) -> None:
+        """Unknown provider raises AuthenticationError."""
+        settings = self._make_settings(provider="unknown")
+        with pytest.raises(AuthenticationError, match="Unknown"):
+            create_provider_from_settings(settings)
+
+
+# ── OAuthTokenSet ────────────────────────────────────────────────────
+
+
+class TestOAuthTokenSet:
+    """Tests for OAuthTokenSet dataclass."""
+
+    def test_is_expired_false(self) -> None:
+        """Token with future expiry is not expired."""
+        tokens = OAuthTokenSet(
+            access_token="at",
+            expires_in=3600,
+            issued_at=time.time(),
+        )
+        assert not tokens.is_expired
+
+    def test_is_expired_true(self) -> None:
+        """Token with past expiry is expired."""
+        tokens = OAuthTokenSet(
+            access_token="at",
+            expires_in=3600,
+            issued_at=time.time() - 7200,  # 2 hours ago
+        )
+        assert tokens.is_expired
+
+    def test_is_expired_no_expiry(self) -> None:
+        """Token without expires_in is never expired."""
+        tokens = OAuthTokenSet(access_token="at", expires_in=None)
+        assert not tokens.is_expired
+
+    def test_expires_at(self) -> None:
+        """expires_at returns correct timestamp."""
+        now = time.time()
+        tokens = OAuthTokenSet(access_token="at", expires_in=3600, issued_at=now)
+        assert tokens.expires_at == pytest.approx(now + 3600, abs=1)
+
+    def test_expires_at_none(self) -> None:
+        """expires_at returns None when no expiry."""
+        tokens = OAuthTokenSet(access_token="at", expires_in=None)
+        assert tokens.expires_at is None
diff --git a/pywry/tests/test_auth_rbac_integration.py b/pywry/tests/test_auth_rbac_integration.py
index 2655361..294282f 100644
--- a/pywry/tests/test_auth_rbac_integration.py
+++ b/pywry/tests/test_auth_rbac_integration.py
@@ -116,7 +116,7 @@ def test_generate_token_format(self, auth_secret: str) -> None:
         assert parts[0] == "user-123", "First part should be user_id"
         assert parts[1].isdigit(), "Second part should be timestamp"
         assert parts[2] == "0", "Third part should be 0 for no expiry"
-        assert len(parts[3]) == 16, "Signature should be 16 hex characters"
+        assert len(parts[3]) == 64, "Signature should be 64 hex characters (full SHA-256)"
 
     def test_generate_token_with_expiry(self, auth_secret: str) -> None:
         """Test token generation with expiration time."""
diff --git a/pywry/tests/test_auth_session.py b/pywry/tests/test_auth_session.py
new file mode 100644
index 0000000..084738c
--- /dev/null
+++ b/pywry/tests/test_auth_session.py
@@ -0,0 +1,301 @@
+"""Tests for OAuth2 session manager."""
+
+# pylint: disable=redefined-outer-name
+
+from __future__ import annotations
+
+import asyncio
+import time
+
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from pywry.auth.session import SessionManager
+from pywry.auth.token_store import MemoryTokenStore
+from pywry.exceptions import TokenExpiredError, TokenRefreshError
+from pywry.state.types import OAuthTokenSet
+
+
+# ── Fixtures ────────────────────────────────────────────────────────
+
+
+@pytest.fixture()
+def mock_provider() -> MagicMock:
+    """Create a mock OAuth provider."""
+    provider = MagicMock()
+    provider.__class__.__name__ = "MockProvider"
+    provider.revoke_token = AsyncMock()
+    provider.refresh_tokens = AsyncMock(
+        return_value=OAuthTokenSet(
+            access_token="at_refreshed",
+            token_type="Bearer",
+            refresh_token="rt_new",
+            expires_in=3600,
+            issued_at=time.time(),
+        )
+    )
+    return provider
+
+
+@pytest.fixture()
+def token_store() -> MemoryTokenStore:
+    """Create a memory token store."""
+    return MemoryTokenStore()
+
+
+@pytest.fixture()
+def valid_tokens() -> OAuthTokenSet:
+    """Create a valid (non-expired) token set."""
+    return OAuthTokenSet(
+        access_token="at_valid",
+        token_type="Bearer",
+        refresh_token="rt_valid",
+        expires_in=3600,
+        issued_at=time.time(),
+    )
+
+
+@pytest.fixture()
+def expired_tokens() -> OAuthTokenSet:
+    """Create an expired token set."""
+    return OAuthTokenSet(
+        access_token="at_expired",
+        token_type="Bearer",
+        refresh_token="rt_for_refresh",
+        expires_in=3600,
+        issued_at=time.time() - 7200,  # 2 hours ago
+    )
+
+
+def _run(coro):
+    """Run an async coroutine synchronously."""
+    return asyncio.run(coro)
+
+
+# ── Tests ────────────────────────────────────────────────────────────
+
+
+class TestSessionManagerInit:
+    """Tests for SessionManager initialization."""
+
+    def test_initialize_no_stored_tokens(
+        self,
+        mock_provider: MagicMock,
+        token_store: MemoryTokenStore,
+    ) -> None:
+        """Initialize with empty store returns None."""
+        mgr = SessionManager(mock_provider, token_store)
+        result = _run(mgr.initialize())
+        assert result is None
+
+    def test_initialize_with_valid_tokens(
+        self,
+        mock_provider: MagicMock,
+        token_store: MemoryTokenStore,
+        valid_tokens: OAuthTokenSet,
+    ) -> None:
+        """Initialize with valid stored tokens returns them."""
+        _run(token_store.save("default", valid_tokens))
+        mgr = SessionManager(mock_provider, token_store)
+        result = _run(mgr.initialize())
+        assert result is not None
+        assert result.access_token == "at_valid"
+
+    def test_initialize_with_expired_tokens_refreshes(
+        self,
+        mock_provider: MagicMock,
+        token_store: MemoryTokenStore,
+        expired_tokens: OAuthTokenSet,
+    ) -> None:
+        """Initialize with expired tokens tries to refresh."""
+        _run(token_store.save("default", expired_tokens))
+        mgr = SessionManager(mock_provider, token_store)
+        result = _run(mgr.initialize())
+        assert result is not None
+        assert result.access_token == "at_refreshed"
+        mock_provider.refresh_tokens.assert_called_once_with("rt_for_refresh")
+
+    def test_initialize_expired_no_refresh_token(
+        self,
+        mock_provider: MagicMock,
+        token_store: MemoryTokenStore,
+    ) -> None:
+        """Initialize with expired tokens and no refresh token returns None."""
+        no_refresh = OAuthTokenSet(
+            access_token="at_old",
+            expires_in=3600,
+            issued_at=time.time() - 7200,
+        )
+        _run(token_store.save("default", no_refresh))
+        mgr = SessionManager(mock_provider, token_store)
+        result = _run(mgr.initialize())
+        assert result is None
+
+
+class TestSessionManagerTokenAccess:
+    """Tests for get_access_token and refresh."""
+
+    def test_get_access_token_valid(
+        self,
+        mock_provider: MagicMock,
+        token_store: MemoryTokenStore,
+        valid_tokens: OAuthTokenSet,
+    ) -> None:
+        """get_access_token returns token when valid."""
+        mgr = SessionManager(mock_provider, token_store)
+        _run(mgr.save_tokens(valid_tokens))
+        token = _run(mgr.get_access_token())
+        assert token == "at_valid"
+
+    def test_get_access_token_no_tokens(
+        self,
+        mock_provider: MagicMock,
+        token_store: MemoryTokenStore,
+    ) -> None:
+        """get_access_token raises when no tokens available."""
+        mgr = SessionManager(mock_provider, token_store)
+        with pytest.raises(TokenExpiredError, match="No tokens"):
+            _run(mgr.get_access_token())
+
+    def test_refresh_success(
+        self,
+        mock_provider: MagicMock,
+        token_store: MemoryTokenStore,
+        valid_tokens: OAuthTokenSet,
+    ) -> None:
+        """Explicit refresh returns new tokens."""
+        mgr = SessionManager(mock_provider, token_store)
+        _run(mgr.save_tokens(valid_tokens))
+        new_tokens = _run(mgr.refresh())
+        assert new_tokens.access_token == "at_refreshed"
+
+        # Verify tokens were persisted
+        stored = _run(token_store.load("default"))
+        assert stored is not None
+        assert stored.access_token == "at_refreshed"
+
+    def test_refresh_no_refresh_token(
+        self,
+        mock_provider: MagicMock,
+        token_store: MemoryTokenStore,
+    ) -> None:
+        """Refresh without refresh_token raises TokenRefreshError."""
+        no_refresh = OAuthTokenSet(
+            access_token="at_no_refresh",
+            expires_in=3600,
+            issued_at=time.time(),
+        )
+        mgr = SessionManager(mock_provider, token_store)
+        _run(mgr.save_tokens(no_refresh))
+
+        with pytest.raises(TokenRefreshError, match="No refresh token"):
+            _run(mgr.refresh())
+
+    def test_refresh_calls_reauth_callback(
+        self,
+        mock_provider: MagicMock,
+        token_store: MemoryTokenStore,
+    ) -> None:
+        """Refresh failure triggers on_reauth_required callback."""
+        no_refresh = OAuthTokenSet(
+            access_token="at",
+            expires_in=3600,
+            issued_at=time.time(),
+        )
+
+        reauth_called = []
+        mgr = SessionManager(
+            mock_provider,
+            token_store,
+            on_reauth_required=lambda: reauth_called.append(True),
+        )
+        _run(mgr.save_tokens(no_refresh))
+
+        with pytest.raises(TokenRefreshError):
+            _run(mgr.refresh())
+
+        assert reauth_called
+
+
+class TestSessionManagerLogout:
+    """Tests for session logout."""
+
+    def test_logout_clears_tokens(
+        self,
+        mock_provider: MagicMock,
+        token_store: MemoryTokenStore,
+        valid_tokens: OAuthTokenSet,
+    ) -> None:
+        """Logout deletes stored tokens."""
+        mgr = SessionManager(mock_provider, token_store)
+        _run(mgr.save_tokens(valid_tokens))
+        _run(mgr.logout())
+
+        assert not _run(token_store.exists("default"))
+        assert mgr._current_tokens is None
+
+    def test_logout_revokes_token(
+        self,
+        mock_provider: MagicMock,
+        token_store: MemoryTokenStore,
+        valid_tokens: OAuthTokenSet,
+    ) -> None:
+        """Logout attempts token revocation."""
+        mgr = SessionManager(mock_provider, token_store)
+        _run(mgr.save_tokens(valid_tokens))
+        _run(mgr.logout())
+        mock_provider.revoke_token.assert_called_once()
+
+    def test_logout_empty_is_safe(
+        self,
+        mock_provider: MagicMock,
+        token_store: MemoryTokenStore,
+    ) -> None:
+        """Logout with no tokens does not raise."""
+        mgr = SessionManager(mock_provider, token_store)
+        _run(mgr.logout())  # Should not raise
+
+
+class TestSessionManagerRefreshScheduling:
+    """Tests for background refresh scheduling."""
+
+    def test_schedule_refresh_timer(
+        self,
+        mock_provider: MagicMock,
+        token_store: MemoryTokenStore,
+        valid_tokens: OAuthTokenSet,
+    ) -> None:
+        """Saving tokens schedules a refresh timer."""
+        mgr = SessionManager(mock_provider, token_store, refresh_buffer_seconds=60)
+        _run(mgr.save_tokens(valid_tokens))
+        assert mgr._refresh_timer is not None
+        assert mgr._refresh_timer.is_alive()
+        mgr._cancel_refresh_timer()
+
+    def test_no_timer_without_expiry(
+        self,
+        mock_provider: MagicMock,
+        token_store: MemoryTokenStore,
+    ) -> None:
+        """Tokens without expires_in don't schedule a timer."""
+        no_expiry = OAuthTokenSet(
+            access_token="at_forever",
+            expires_in=None,
+            issued_at=time.time(),
+        )
+        mgr = SessionManager(mock_provider, token_store)
+        _run(mgr.save_tokens(no_expiry))
+        assert mgr._refresh_timer is None
+
+    def test_cancel_refresh_timer(
+        self,
+        mock_provider: MagicMock,
+        token_store: MemoryTokenStore,
+        valid_tokens: OAuthTokenSet,
+    ) -> None:
+        """_cancel_refresh_timer stops the timer."""
+        mgr = SessionManager(mock_provider, token_store)
+        _run(mgr.save_tokens(valid_tokens))
+        mgr._cancel_refresh_timer()
+        assert mgr._refresh_timer is None
diff --git a/pywry/tests/test_auth_token_store.py b/pywry/tests/test_auth_token_store.py
new file mode 100644
index 0000000..5ecbd23
--- /dev/null
+++ b/pywry/tests/test_auth_token_store.py
@@ -0,0 +1,174 @@
+"""Unit tests for OAuth2 token storage backends."""
+
+# pylint: disable=redefined-outer-name
+
+from __future__ import annotations
+
+import asyncio
+import json
+import time
+
+from unittest.mock import patch
+
+import pytest
+
+from pywry.auth.token_store import (
+    MemoryTokenStore,
+    _deserialize_tokens,
+    _serialize_tokens,
+    get_token_store,
+    reset_token_store,
+)
+from pywry.state.types import OAuthTokenSet
+
+
+# ── Fixtures ────────────────────────────────────────────────────────
+
+
+@pytest.fixture()
+def sample_tokens() -> OAuthTokenSet:
+    """Create sample tokens for testing."""
+    return OAuthTokenSet(
+        access_token="at_test_123",
+        token_type="Bearer",
+        refresh_token="rt_test_456",
+        expires_in=3600,
+        id_token="id_tok",
+        scope="openid email",
+        issued_at=time.time(),
+    )
+
+
+@pytest.fixture()
+def memory_store() -> MemoryTokenStore:
+    """Create a MemoryTokenStore."""
+    return MemoryTokenStore()
+
+
+# ── Serialization ───────────────────────────────────────────────────
+
+
+class TestSerialization:
+    """Tests for token serialization helpers."""
+
+    def test_round_trip(self, sample_tokens: OAuthTokenSet) -> None:
+        """Tokens survive serialize→deserialize round trip."""
+        data = _serialize_tokens(sample_tokens)
+        restored = _deserialize_tokens(data)
+        assert restored.access_token == sample_tokens.access_token
+        assert restored.token_type == sample_tokens.token_type
+        assert restored.refresh_token == sample_tokens.refresh_token
+        assert restored.expires_in == sample_tokens.expires_in
+        assert restored.scope == sample_tokens.scope
+
+    def test_serialize_is_json(self, sample_tokens: OAuthTokenSet) -> None:
+        """Serialized output is valid JSON."""
+        data = _serialize_tokens(sample_tokens)
+        parsed = json.loads(data)
+        assert parsed["access_token"] == "at_test_123"
+
+    def test_deserialize_missing_fields(self) -> None:
+        """Deserialize handles missing optional fields gracefully."""
+        data = json.dumps({"access_token": "at_minimal"})
+        tokens = _deserialize_tokens(data)
+        assert tokens.access_token == "at_minimal"
+        assert tokens.token_type == "Bearer"
+        assert tokens.refresh_token is None
+
+
+# ── MemoryTokenStore ────────────────────────────────────────────────
+
+
+class TestMemoryTokenStore:
+    """Tests for MemoryTokenStore."""
+
+    def test_save_and_load(
+        self, memory_store: MemoryTokenStore, sample_tokens: OAuthTokenSet
+    ) -> None:
+        """Save and load round-trip."""
+        asyncio.run(memory_store.save("user1", sample_tokens))
+        loaded = asyncio.run(memory_store.load("user1"))
+        assert loaded is not None
+        assert loaded.access_token == sample_tokens.access_token
+        assert loaded.refresh_token == sample_tokens.refresh_token
+
+    def test_load_missing(self, memory_store: MemoryTokenStore) -> None:
+        """Load returns None for missing key."""
+        loaded = asyncio.run(memory_store.load("nonexistent"))
+        assert loaded is None
+
+    def test_exists(self, memory_store: MemoryTokenStore, sample_tokens: OAuthTokenSet) -> None:
+        """exists() returns True after save."""
+        asyncio.run(memory_store.save("u1", sample_tokens))
+        assert asyncio.run(memory_store.exists("u1"))
+        assert not asyncio.run(memory_store.exists("u2"))
+
+    def test_delete(self, memory_store: MemoryTokenStore, sample_tokens: OAuthTokenSet) -> None:
+        """delete() removes tokens."""
+        asyncio.run(memory_store.save("u1", sample_tokens))
+        asyncio.run(memory_store.delete("u1"))
+        assert not asyncio.run(memory_store.exists("u1"))
+
+    def test_delete_missing(self, memory_store: MemoryTokenStore) -> None:
+        """delete() on missing key does not raise."""
+        asyncio.run(memory_store.delete("missing"))
+
+    def test_list_keys(self, memory_store: MemoryTokenStore, sample_tokens: OAuthTokenSet) -> None:
+        """list_keys() returns all stored keys."""
+        asyncio.run(memory_store.save("a", sample_tokens))
+        asyncio.run(memory_store.save("b", sample_tokens))
+        keys = asyncio.run(memory_store.list_keys())
+        assert set(keys) == {"a", "b"}
+
+    def test_overwrite(self, memory_store: MemoryTokenStore, sample_tokens: OAuthTokenSet) -> None:
+        """Saving under the same key overwrites."""
+        asyncio.run(memory_store.save("u1", sample_tokens))
+        new_tokens = OAuthTokenSet(
+            access_token="at_new",
+            expires_in=7200,
+            issued_at=time.time(),
+        )
+        asyncio.run(memory_store.save("u1", new_tokens))
+        loaded = asyncio.run(memory_store.load("u1"))
+        assert loaded is not None
+        assert loaded.access_token == "at_new"
+
+
+# ── KeyringTokenStore ───────────────────────────────────────────────
+
+
+class TestKeyringTokenStore:
+    """Tests for KeyringTokenStore with mocked keyring."""
+
+    def test_import_error(self) -> None:
+        """Missing keyring raises ImportError."""
+        with patch.dict("sys.modules", {"keyring": None}):
+            from pywry.auth.token_store import KeyringTokenStore
+
+            with pytest.raises(ImportError, match="keyring"):
+                KeyringTokenStore()
+
+
+# ── get_token_store factory ─────────────────────────────────────────
+
+
+class TestGetTokenStore:
+    """Tests for the get_token_store factory."""
+
+    def test_memory_backend(self) -> None:
+        """'memory' returns a MemoryTokenStore."""
+        reset_token_store()
+        store = get_token_store("memory")
+        assert isinstance(store, MemoryTokenStore)
+
+    def test_default_is_memory(self) -> None:
+        """Default backend is memory."""
+        reset_token_store()
+        store = get_token_store()
+        assert isinstance(store, MemoryTokenStore)
+
+    def test_unknown_backend_raises(self) -> None:
+        """Unknown backend raises ValueError."""
+        reset_token_store()
+        with pytest.raises(ValueError, match="Unknown"):
+            get_token_store("nonexistent")
diff --git a/pywry/tests/test_inline_e2e.py b/pywry/tests/test_inline_e2e.py
index 72ca9b0..05b7ea6 100644
--- a/pywry/tests/test_inline_e2e.py
+++ b/pywry/tests/test_inline_e2e.py
@@ -176,6 +176,9 @@ def http_get(url: str, timeout: float = 5.0, auth: bool = False) -> tuple[int, s
             return resp.status, resp.read().decode("utf-8")
     except urllib.error.HTTPError as e:
         return e.code, e.read().decode("utf-8")
+    except OSError:
+        # Connection reset/aborted before response could be read (Windows TCP timing).
+        return 0, ""
 
 
 def http_post(url: str, data: dict, timeout: float = 5.0, auth: bool = False) -> tuple[int, str]:
@@ -206,6 +209,10 @@ def http_post(url: str, data: dict, timeout: float = 5.0, auth: bool = False) ->
             return resp.status, resp.read().decode("utf-8")
     except urllib.error.HTTPError as e:
         return e.code, e.read().decode("utf-8")
+    except OSError:
+        # Connection reset/aborted before response could be read (Windows TCP timing).
+        # Treat as a server-side rejection.
+        return 0, ""
 
 
 # =============================================================================
diff --git a/pywry/tests/test_inline_ssl.py b/pywry/tests/test_inline_ssl.py
index 0124d8e..43d048d 100644
--- a/pywry/tests/test_inline_ssl.py
+++ b/pywry/tests/test_inline_ssl.py
@@ -121,6 +121,7 @@ def test_https_server_configuration(ssl_certs):
 
     with patch("pywry.inline.get_settings") as mock_get_settings:
         settings_root = mock_get_settings.return_value
+        settings_root.deploy.auth_enabled = False
         settings_server = settings_root.server
 
         settings_server.ssl_certfile = cert_path
@@ -217,6 +218,7 @@ async def test_e2e_wss_callback_flow(  # noqa: PLR0915  # pylint: disable=too-ma
 
     with patch("pywry.inline.get_settings") as mock_get_settings:
         settings_root = mock_get_settings.return_value
+        settings_root.deploy.auth_enabled = False
         settings_server = settings_root.server
 
         settings_server.ssl_certfile = cert_path
@@ -319,6 +321,7 @@ def test_content_generation_https(ssl_certs):
 
     with patch("pywry.inline.get_settings") as mock_get_settings:
         settings_root = mock_get_settings.return_value
+        settings_root.deploy.auth_enabled = False
         settings_server = settings_root.server
         settings_server.ssl_certfile = cert_path
         settings_server.ssl_keyfile = key_path
@@ -409,6 +412,7 @@ def test_secret_never_in_https_response(ssl_certs):
 
     with patch("pywry.inline.get_settings") as mock_get_settings:
         settings_root = mock_get_settings.return_value
+        settings_root.deploy.auth_enabled = False
         _make_ssl_server_settings(settings_root.server, cert_path, key_path, 8770)
 
         # Create toolbar with secret
@@ -463,6 +467,7 @@ async def test_e2e_wss_secret_reveal_base64_encoded(ssl_certs):
 
     with patch("pywry.inline.get_settings") as mock_get_settings:
         settings_root = mock_get_settings.return_value
+        settings_root.deploy.auth_enabled = False
         _make_ssl_server_settings(settings_root.server, cert_path, key_path, 8771)
 
         # Create toolbar with secret
@@ -540,6 +545,7 @@ async def test_e2e_wss_secret_input_submission(ssl_certs):
 
     with patch("pywry.inline.get_settings") as mock_get_settings:
         settings_root = mock_get_settings.return_value
+        settings_root.deploy.auth_enabled = False
         _make_ssl_server_settings(settings_root.server, cert_path, key_path, 8772)
 
         # Create toolbar with empty secret
@@ -712,6 +718,7 @@ async def test_e2e_wss_custom_secret_handler_reveal(  # noqa: PLR0915  # pylint:
 
     with patch("pywry.inline.get_settings") as mock_get_settings:
         settings_root = mock_get_settings.return_value
+        settings_root.deploy.auth_enabled = False
         _make_ssl_server_settings(settings_root.server, cert_path, key_path, 8774)
 
         # Create toolbar with secret in registry
@@ -848,6 +855,7 @@ async def test_e2e_wss_custom_handler_with_context(  # noqa: PLR0915
 
     with patch("pywry.inline.get_settings") as mock_get_settings:
         settings_root = mock_get_settings.return_value
+        settings_root.deploy.auth_enabled = False
         _make_ssl_server_settings(settings_root.server, cert_path, key_path, 8775)
 
         toolbar = Toolbar(
diff --git a/pywry/tests/test_toolbar.py b/pywry/tests/test_toolbar.py
index cff73b3..4a59876 100644
--- a/pywry/tests/test_toolbar.py
+++ b/pywry/tests/test_toolbar.py
@@ -3,14 +3,14 @@
 Tests cover:
 - Option model
 - Base ToolbarItem functionality
-- Individual item types (Button, Select, MultiSelect, TextInput, NumberInput, DateInput, SliderInput, RangeInput)
+- Individual item types
 - Toolbar container
 - Event validation
 - HTML generation
 - Helper functions
 """
 
-# pylint: disable=too-many-lines,unused-argument
+# pylint: disable=C0302,unused-argument
 
 from __future__ import annotations
 
diff --git a/pywry/tests/test_widget_protocol.py b/pywry/tests/test_widget_protocol.py
index 842c432..e3cfc4d 100644
--- a/pywry/tests/test_widget_protocol.py
+++ b/pywry/tests/test_widget_protocol.py
@@ -585,131 +585,3 @@ def test_inject_css_with_complex_styles(self, native_handle):
             result = native_handle.inject_css(css, "complex-styles")
             assert result is True
             mock_inject.assert_called_once()
-
-
-# =============================================================================
-# NativeWindowHandle Notification and Toolbar State Tests
-# =============================================================================
-
-
-class TestNativeWindowHandleAlertAndToolbar:
-    """Tests for NativeWindowHandle alert and toolbar state methods."""
-
-    def test_alert_emits_pywry_alert_event(self, native_handle, mock_app):
-        """Test alert() emits pywry:alert with correct payload."""
-        native_handle.alert("File saved successfully")
-        mock_app.emit.assert_called_once_with(
-            "pywry:alert",
-            {"message": "File saved successfully", "type": "info", "position": "top-right"},
-            "test-window",
-        )
-
-    def test_alert_with_type_and_title(self, native_handle, mock_app):
-        """Test alert() with success type and title."""
-        native_handle.alert("Export complete", alert_type="success", title="Done")
-        mock_app.emit.assert_called_once_with(
-            "pywry:alert",
-            {
-                "message": "Export complete",
-                "type": "success",
-                "position": "top-right",
-                "title": "Done",
-            },
-            "test-window",
-        )
-
-    def test_alert_with_duration(self, native_handle, mock_app):
-        """Test alert() with custom duration."""
-        native_handle.alert("Warning", alert_type="warning", duration=8000)
-        call_args = mock_app.emit.call_args
-        assert call_args[0][1]["duration"] == 8000
-        assert call_args[0][1]["type"] == "warning"
-
-    def test_alert_with_callback_event(self, native_handle, mock_app):
-        """Test alert() confirm type with callback event."""
-        native_handle.alert(
-            "Are you sure?",
-            alert_type="confirm",
-            callback_event="app:confirm",
-        )
-        call_args = mock_app.emit.call_args
-        assert call_args[0][1]["type"] == "confirm"
-        assert call_args[0][1]["callback_event"] == "app:confirm"
-
-    def test_alert_with_position(self, native_handle, mock_app):
-        """Test alert() with custom position."""
-        native_handle.alert("Notice", position="bottom-left")
-        call_args = mock_app.emit.call_args
-        assert call_args[0][1]["position"] == "bottom-left"
-
-    def test_alert_optional_fields_not_included_when_none(self, native_handle, mock_app):
-        """Test alert() omits None optional fields from payload."""
-        native_handle.alert("Simple message")
-        payload = mock_app.emit.call_args[0][1]
-        assert "title" not in payload
-        assert "duration" not in payload
-        assert "callback_event" not in payload
-
-    def test_request_toolbar_state_emits_event(self, native_handle, mock_app):
-        """Test request_toolbar_state() emits toolbar:request-state."""
-        native_handle.request_toolbar_state()
-        mock_app.emit.assert_called_once_with("toolbar:request-state", {}, "test-window")
-
-    def test_request_toolbar_state_with_toolbar_id(self, native_handle, mock_app):
-        """Test request_toolbar_state() passes toolbar_id."""
-        native_handle.request_toolbar_state(toolbar_id="toolbar-abc123")
-        mock_app.emit.assert_called_once_with(
-            "toolbar:request-state",
-            {"toolbarId": "toolbar-abc123"},
-            "test-window",
-        )
-
-    def test_set_toolbar_value_with_value(self, native_handle, mock_app):
-        """Test set_toolbar_value() emits toolbar:set-value with value."""
-        native_handle.set_toolbar_value("theme-select", "light")
-        mock_app.emit.assert_called_once_with(
-            "toolbar:set-value",
-            {"componentId": "theme-select", "value": "light"},
-            "test-window",
-        )
-
-    def test_set_toolbar_value_without_value(self, native_handle, mock_app):
-        """Test set_toolbar_value() without value only sets other attrs."""
-        native_handle.set_toolbar_value("submit-btn", disabled=True, label="Loading...")
-        call_args = mock_app.emit.call_args
-        assert call_args[0][0] == "toolbar:set-value"
-        payload = call_args[0][1]
-        assert payload["componentId"] == "submit-btn"
-        assert payload["disabled"] is True
-        assert payload["label"] == "Loading..."
-        assert "value" not in payload
-
-    def test_set_toolbar_value_with_toolbar_id(self, native_handle, mock_app):
-        """Test set_toolbar_value() passes toolbar_id."""
-        native_handle.set_toolbar_value("slider", 50, toolbar_id="toolbar-abc")
-        payload = mock_app.emit.call_args[0][1]
-        assert payload["toolbarId"] == "toolbar-abc"
-
-    def test_set_toolbar_value_none_value_not_included(self, native_handle, mock_app):
-        """Test set_toolbar_value() with no value doesn't include it in payload."""
-        native_handle.set_toolbar_value("zoom-input", label="Zoom")
-        payload = mock_app.emit.call_args[0][1]
-        assert "value" not in payload
-        assert payload["label"] == "Zoom"
-
-    def test_set_toolbar_values_emits_event(self, native_handle, mock_app):
-        """Test set_toolbar_values() emits toolbar:set-values."""
-        values = {"theme-select": "light", "zoom-input": 100}
-        native_handle.set_toolbar_values(values)
-        mock_app.emit.assert_called_once_with(
-            "toolbar:set-values",
-            {"values": values},
-            "test-window",
-        )
-
-    def test_set_toolbar_values_with_toolbar_id(self, native_handle, mock_app):
-        """Test set_toolbar_values() passes toolbar_id."""
-        native_handle.set_toolbar_values({"slider": 50}, toolbar_id="toolbar-abc")
-        payload = mock_app.emit.call_args[0][1]
-        assert payload["toolbarId"] == "toolbar-abc"
-        assert payload["values"] == {"slider": 50}
diff --git a/pywry/tests/test_window_proxy.py b/pywry/tests/test_window_proxy.py
index dc4f065..14dde26 100644
--- a/pywry/tests/test_window_proxy.py
+++ b/pywry/tests/test_window_proxy.py
@@ -8,12 +8,13 @@
 
 from __future__ import annotations
 
-import contextlib
 import os
 import sys
 import time
 
-from typing import Any
+from collections.abc import Callable
+from functools import wraps
+from typing import Any, TypeVar
 
 import pytest
 
@@ -29,6 +30,39 @@
 from tests.conftest import ReadyWaiter
 
 
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def retry_on_subprocess_failure(max_attempts: int = 3, delay: float = 1.0) -> Callable[[F], F]:
+    """Retry decorator for tests that may fail due to transient subprocess issues.
+
+    On Windows, WebView2 sometimes fails to start due to resource contention
+    ("Failed to unregister class Chrome_WidgetWin_0"). On Linux with xvfb,
+    WebKit initialization may have timing issues. This decorator retries
+    the test after a delay to allow resources to be released.
+    """
+
+    def decorator(func: F) -> F:
+        @wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            last_error: Exception | None = None
+            for attempt in range(max_attempts):
+                try:
+                    return func(*args, **kwargs)
+                except (TimeoutError, AssertionError) as e:
+                    last_error = e
+                    if attempt < max_attempts - 1:
+                        # Clean up and wait before retry
+                        runtime.stop()
+                        # Progressive backoff for CI stability
+                        time.sleep(delay * (attempt + 1))
+            raise last_error  # type: ignore[misc]
+
+        return wrapper  # type: ignore[return-value]
+
+    return decorator
+
+
 # Note: cleanup_runtime fixture is now in conftest.py and auto-used
 
 
@@ -176,16 +210,10 @@ def test_set_title(self) -> None:
 
         # Change title
         proxy.set_title("New Title")
+        time.sleep(0.1)  # Allow IPC to complete
 
-        # Poll until title propagates through IPC (fire-and-forget is async)
-        deadline = time.time() + 3.0
+        # Verify title changed
         new_title = proxy.title
-        while "New Title" not in new_title and time.time() < deadline:
-            with contextlib.suppress(IPCTimeoutError):
-                new_title = proxy.title
-            if "New Title" not in new_title:
-                time.sleep(0.1)
-
         assert "New Title" in new_title
         app.close()
 
@@ -280,6 +308,7 @@ def test_hide_show(self) -> None:
         assert proxy.is_visible is True
         app.close()
 
+    @retry_on_subprocess_failure(max_attempts=3, delay=1.0)
     @pytest.mark.skipif(
         os.environ.get("CI") == "true" and sys.platform == "linux",
         reason="Always-on-top requires a real window manager (not available on Linux CI)",