From edbbdfd2ba6d61af49774c3651b048980e69ee95 Mon Sep 17 00:00:00 2001
From: Mark Bakhit <archiethemonger@gmail.com>
Date: Mon, 14 Sep 2026 15:53:30 -0700
Subject: [PATCH 01/26] Add persistent session state settings

---
 src/reactpy_django/config.py | 23 ++++++++++++++++++++++-
 1 file changed, 22 insertions(+), 1 deletion(-)

diff --git a/src/reactpy_django/config.py b/src/reactpy_django/config.py
index 0b71ec17..0ccc6f3c 100644
--- a/src/reactpy_django/config.py
+++ b/src/reactpy_django/config.py
@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from itertools import cycle
-from typing import TYPE_CHECKING, Callable
+from typing import TYPE_CHECKING, Callable, Literal
 
 from django.conf import settings
 from django.core.cache import DEFAULT_CACHE_ALIAS
@@ -136,6 +136,27 @@
     "REACTPY_CLEAN_USER_DATA",
     True,
 )
+REACTPY_CLEAN_SESSION_STATE: bool = getattr(
+    settings,
+    "REACTPY_CLEAN_SESSION_STATE",
+    True,
+)
+SessionStateMode = Literal["tab", "user"]
+REACTPY_SESSION_STATE_MODE: SessionStateMode = getattr(
+    settings,
+    "REACTPY_SESSION_STATE_MODE",
+    "tab",  # Default to per-tab (per-component token) scope
+)
+REACTPY_SESSION_STATE_SYNC_INTERVAL: int = getattr(
+    settings,
+    "REACTPY_SESSION_STATE_SYNC_INTERVAL",
+    5,  # Default to 5 seconds
+)
+REACTPY_SESSION_STATE_MAX_AGE: int = getattr(
+    settings,
+    "REACTPY_SESSION_STATE_MAX_AGE",
+    259200,  # Default to 3 days
+)
 REACTPY_DEFAULT_FORM_TEMPLATE: str | None = getattr(
     settings,
     "REACTPY_DEFAULT_FORM_TEMPLATE",

From 1a4beca3ef269b36967c671209b208088e70d9c1 Mon Sep 17 00:00:00 2001
From: Mark Bakhit <archiethemonger@gmail.com>
Date: Mon, 14 Sep 2026 15:53:52 -0700
Subject: [PATCH 02/26] Add SessionStateModel for persistent session state

---
 src/reactpy_django/models.py | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/src/reactpy_django/models.py b/src/reactpy_django/models.py
index ab143736..82b7921a 100644
--- a/src/reactpy_django/models.py
+++ b/src/reactpy_django/models.py
@@ -65,6 +65,29 @@ class UserDataModel(models.Model):
     data = models.BinaryField(null=True, blank=True)
 
 
+class SessionStateModel(models.Model):
+    """A model for storing `session_state` data.
+
+    This is used to persistently store ReactPy state across WebSocket reconnects (and, depending
+    on the configured `REACTPY_SESSION_STATE_MODE`, optionally across page reloads as well).
+
+    The `scope_id` uniquely identifies the scope that the state belongs to. By default it is a
+    per-component (per-tab) token that is stable across WebSocket reconnects. When
+    `REACTPY_SESSION_STATE_MODE` is set to `"user"`, the scope is instead the authenticated user's
+    primary key (falling back to a per-tab token for anonymous users)."""
+
+    scope_id = models.CharField(max_length=255)
+    key = models.CharField(max_length=255)
+    data = models.BinaryField(null=True, blank=True)
+    updated_at = models.DateTimeField(auto_now=True)
+
+    class Meta:
+        unique_together = ("scope_id", "key")
+        indexes = [
+            models.Index(fields=["scope_id", "updated_at"]),
+        ]
+
+
 @receiver(pre_delete, sender=get_user_model(), dispatch_uid="reactpy_delete_user_data")
 def delete_user_data(sender, instance, **kwargs):
     """Delete ReactPy's `UserDataModel` when a Django `User` is deleted."""

From 978436cf8bf9ac07365da96ce8653ac3616c6d42 Mon Sep 17 00:00:00 2001
From: Mark Bakhit <archiethemonger@gmail.com>
Date: Mon, 14 Sep 2026 15:54:06 -0700
Subject: [PATCH 03/26] Add SessionStateModel migration

---
 .../migrations/0008_sessionstatemodel.py      | 30 +++++++++++++++++++
 1 file changed, 30 insertions(+)
 create mode 100644 src/reactpy_django/migrations/0008_sessionstatemodel.py

diff --git a/src/reactpy_django/migrations/0008_sessionstatemodel.py b/src/reactpy_django/migrations/0008_sessionstatemodel.py
new file mode 100644
index 00000000..8bb7976e
--- /dev/null
+++ b/src/reactpy_django/migrations/0008_sessionstatemodel.py
@@ -0,0 +1,30 @@
+# Generated by Django 5.1.4 on 2026-09-14 22:53
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('reactpy_django', '0007_authtoken'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='SessionStateModel',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('scope_id', models.CharField(max_length=255)),
+                ('key', models.CharField(max_length=255)),
+                ('data', models.BinaryField(blank=True, null=True)),
+                ('updated_at', models.DateTimeField(auto_now=True)),
+            ],
+            options={
+                'indexes': [models.Index(fields=['scope_id', 'updated_at'], name='reactpy_dj_scope_i_1cf868_idx')],
+            },
+        ),
+        migrations.AddConstraint(
+            model_name='sessionstatemodel',
+            constraint=models.UniqueConstraint(fields=('scope_id', 'key'), name='reactpy_django_sess_scope_id_key'),
+        ),
+    ]

From 447427c5faa5849277dc43508e624530be2fb8f0 Mon Sep 17 00:00:00 2001
From: Mark Bakhit <archiethemonger@gmail.com>
Date: Mon, 14 Sep 2026 15:54:17 -0700
Subject: [PATCH 04/26] Add SessionState type

---
 src/reactpy_django/types.py | 132 +-----------------------------------
 1 file changed, 3 insertions(+), 129 deletions(-)

diff --git a/src/reactpy_django/types.py b/src/reactpy_django/types.py
index e71f9c63..f5cd2ed4 100644
--- a/src/reactpy_django/types.py
+++ b/src/reactpy_django/types.py
@@ -1,134 +1,8 @@
-from __future__ import annotations
-
-from dataclasses import dataclass
-from typing import (
-    TYPE_CHECKING,
-    Any,
-    Callable,
-    Generic,
-    NamedTuple,
-    Protocol,
-    TypeVar,
-    Union,
-)
-
-from django.http import HttpRequest
-from reactpy.types import Component, Connection, Key
-from typing_extensions import ParamSpec
-
-if TYPE_CHECKING:
-    from collections.abc import MutableMapping, Sequence
-
-    from django.contrib.auth.models import AbstractUser
-    from django.forms import Form, ModelForm
-
-    from reactpy_django.websocket.consumer import ReactpyAsyncWebsocketConsumer
-
-
-FuncParams = ParamSpec("FuncParams")
-Inferred = TypeVar("Inferred")
-ConnectionType = Connection[Union["ReactpyAsyncWebsocketConsumer", HttpRequest]]
-
-
-@dataclass
-class Query(Generic[Inferred]):
-    """Queries generated by the `use_query` hook."""
-
-    data: Inferred
-    loading: bool
-    error: Exception | None
-    refetch: Callable[[], None]
-
-
-@dataclass
-class Mutation(Generic[FuncParams]):
-    """Mutations generated by the `use_mutation` hook."""
-
-    execute: Callable[FuncParams, None]
-    loading: bool
-    error: Exception | None
-    reset: Callable[[], None]
-
-    def __call__(self, *args: FuncParams.args, **kwargs: FuncParams.kwargs) -> None:
-        """Execute the mutation."""
-        self.execute(*args, **kwargs)
-
-
-@dataclass
-class FormEventData:
-    """State of a form provided to Form custom events."""
-
-    form: Form | ModelForm
-    submitted_data: dict[str, Any]
-    set_submitted_data: Callable[[dict[str, Any] | None], None]
-
-
-class AsyncFormEvent(Protocol):
-    async def __call__(self, event: FormEventData) -> None: ...
-
-
-class SyncFormEvent(Protocol):
-    def __call__(self, event: FormEventData) -> None: ...
-
-
-class AsyncPostprocessor(Protocol):
-    async def __call__(self, data: Any) -> Any: ...
-
-
-class SyncPostprocessor(Protocol):
-    def __call__(self, data: Any) -> Any: ...
-
-
-@dataclass
-class ComponentParams:
-    """Container used for serializing component parameters.
-    This dataclass is pickled & stored in the database, then unpickled when needed."""
-
-    args: Sequence
-    kwargs: MutableMapping[str, Any]
-
-
 class UserData(NamedTuple):
     query: Query[dict | None]
     mutation: Mutation[dict]
 
 
-class AsyncMessageReceiver(Protocol):
-    async def __call__(self, message: dict) -> None: ...
-
-
-class AsyncMessageSender(Protocol):
-    async def __call__(self, message: dict) -> None: ...
-
-
-class ViewToComponentConstructor(Protocol):
-    def __call__(
-        self, request: HttpRequest | None = None, *args: Any, key: Key | None = None, **kwargs: Any
-    ) -> Component: ...
-
-
-class ViewToIframeConstructor(Protocol):
-    def __call__(self, *args: Any, key: Key | None = None, **kwargs: Any) -> Component: ...
-
-
-class UseAuthLogin(Protocol):
-    async def __call__(self, user: AbstractUser, rerender: bool = True) -> None: ...
-
-
-class UseAuthLogout(Protocol):
-    async def __call__(self, rerender: bool = True) -> None: ...
-
-
-class UseAuthTuple(NamedTuple):
-    login: UseAuthLogin
-    """Login a user.
-
-        Args:
-            user: The user to login.
-            rerender: If True, the root component will be re-rendered after the user is logged in."""
-
-    logout: UseAuthLogout
-    """Logout the current user.
-
-        Args:
-            rerender: If True, the root component will be re-rendered after the user is logged out."""
+class SessionState(NamedTuple):
+    query: Query[Any]
+    mutation: Mutation[Any]

From a646707529be147b3673646f1f5731c34d57eeb8 Mon Sep 17 00:00:00 2001
From: Mark Bakhit <archiethemonger@gmail.com>
Date: Mon, 14 Sep 2026 15:54:50 -0700
Subject: [PATCH 05/26] Restore types.py and add SessionState type

---
 src/reactpy_django/types.py | 132 +++++++++++++++++++++++++++++++++++-
 1 file changed, 129 insertions(+), 3 deletions(-)

diff --git a/src/reactpy_django/types.py b/src/reactpy_django/types.py
index f5cd2ed4..e71f9c63 100644
--- a/src/reactpy_django/types.py
+++ b/src/reactpy_django/types.py
@@ -1,8 +1,134 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Generic,
+    NamedTuple,
+    Protocol,
+    TypeVar,
+    Union,
+)
+
+from django.http import HttpRequest
+from reactpy.types import Component, Connection, Key
+from typing_extensions import ParamSpec
+
+if TYPE_CHECKING:
+    from collections.abc import MutableMapping, Sequence
+
+    from django.contrib.auth.models import AbstractUser
+    from django.forms import Form, ModelForm
+
+    from reactpy_django.websocket.consumer import ReactpyAsyncWebsocketConsumer
+
+
+FuncParams = ParamSpec("FuncParams")
+Inferred = TypeVar("Inferred")
+ConnectionType = Connection[Union["ReactpyAsyncWebsocketConsumer", HttpRequest]]
+
+
+@dataclass
+class Query(Generic[Inferred]):
+    """Queries generated by the `use_query` hook."""
+
+    data: Inferred
+    loading: bool
+    error: Exception | None
+    refetch: Callable[[], None]
+
+
+@dataclass
+class Mutation(Generic[FuncParams]):
+    """Mutations generated by the `use_mutation` hook."""
+
+    execute: Callable[FuncParams, None]
+    loading: bool
+    error: Exception | None
+    reset: Callable[[], None]
+
+    def __call__(self, *args: FuncParams.args, **kwargs: FuncParams.kwargs) -> None:
+        """Execute the mutation."""
+        self.execute(*args, **kwargs)
+
+
+@dataclass
+class FormEventData:
+    """State of a form provided to Form custom events."""
+
+    form: Form | ModelForm
+    submitted_data: dict[str, Any]
+    set_submitted_data: Callable[[dict[str, Any] | None], None]
+
+
+class AsyncFormEvent(Protocol):
+    async def __call__(self, event: FormEventData) -> None: ...
+
+
+class SyncFormEvent(Protocol):
+    def __call__(self, event: FormEventData) -> None: ...
+
+
+class AsyncPostprocessor(Protocol):
+    async def __call__(self, data: Any) -> Any: ...
+
+
+class SyncPostprocessor(Protocol):
+    def __call__(self, data: Any) -> Any: ...
+
+
+@dataclass
+class ComponentParams:
+    """Container used for serializing component parameters.
+    This dataclass is pickled & stored in the database, then unpickled when needed."""
+
+    args: Sequence
+    kwargs: MutableMapping[str, Any]
+
+
 class UserData(NamedTuple):
     query: Query[dict | None]
     mutation: Mutation[dict]
 
 
-class SessionState(NamedTuple):
-    query: Query[Any]
-    mutation: Mutation[Any]
+class AsyncMessageReceiver(Protocol):
+    async def __call__(self, message: dict) -> None: ...
+
+
+class AsyncMessageSender(Protocol):
+    async def __call__(self, message: dict) -> None: ...
+
+
+class ViewToComponentConstructor(Protocol):
+    def __call__(
+        self, request: HttpRequest | None = None, *args: Any, key: Key | None = None, **kwargs: Any
+    ) -> Component: ...
+
+
+class ViewToIframeConstructor(Protocol):
+    def __call__(self, *args: Any, key: Key | None = None, **kwargs: Any) -> Component: ...
+
+
+class UseAuthLogin(Protocol):
+    async def __call__(self, user: AbstractUser, rerender: bool = True) -> None: ...
+
+
+class UseAuthLogout(Protocol):
+    async def __call__(self, rerender: bool = True) -> None: ...
+
+
+class UseAuthTuple(NamedTuple):
+    login: UseAuthLogin
+    """Login a user.
+
+        Args:
+            user: The user to login.
+            rerender: If True, the root component will be re-rendered after the user is logged in."""
+
+    logout: UseAuthLogout
+    """Logout the current user.
+
+        Args:
+            rerender: If True, the root component will be re-rendered after the user is logged out."""

From 3a72b7d5edba26036755872c1e1322854c985d40 Mon Sep 17 00:00:00 2001
From: Mark Bakhit <archiethemonger@gmail.com>
Date: Mon, 14 Sep 2026 15:55:24 -0700
Subject: [PATCH 06/26] Add SessionState type used by use_session_state

---
 src/reactpy_django/types.py | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/src/reactpy_django/types.py b/src/reactpy_django/types.py
index e71f9c63..cfc70aed 100644
--- a/src/reactpy_django/types.py
+++ b/src/reactpy_django/types.py
@@ -93,6 +93,11 @@ class UserData(NamedTuple):
     mutation: Mutation[dict]
 
 
+class SessionState(NamedTuple):
+    query: Query[Any]
+    mutation: Mutation[Any]
+
+
 class AsyncMessageReceiver(Protocol):
     async def __call__(self, message: dict) -> None: ...
 

From ed4040b023719ed5bd21303d296ea5690a77d91f Mon Sep 17 00:00:00 2001
From: Mark Bakhit <archiethemonger@gmail.com>
Date: Mon, 14 Sep 2026 16:01:19 -0700
Subject: [PATCH 07/26] Revert types.py to original

---
 src/reactpy_django/types.py | 5 -----
 1 file changed, 5 deletions(-)

diff --git a/src/reactpy_django/types.py b/src/reactpy_django/types.py
index cfc70aed..e71f9c63 100644
--- a/src/reactpy_django/types.py
+++ b/src/reactpy_django/types.py
@@ -93,11 +93,6 @@ class UserData(NamedTuple):
     mutation: Mutation[dict]
 
 
-class SessionState(NamedTuple):
-    query: Query[Any]
-    mutation: Mutation[Any]
-
-
 class AsyncMessageReceiver(Protocol):
     async def __call__(self, message: dict) -> None: ...
 

From 962ce320c5f95ee45cb20fa971981b25b9e57848 Mon Sep 17 00:00:00 2001
From: Mark Bakhit <archiethemonger@gmail.com>
Date: Mon, 14 Sep 2026 16:03:50 -0700
Subject: [PATCH 08/26] Add use_session_state persistent state hook

---
 src/reactpy_django/hooks.py | 145 ++++++++++++++++++++++++++++++++++++
 1 file changed, 145 insertions(+)

diff --git a/src/reactpy_django/hooks.py b/src/reactpy_django/hooks.py
index f0f6120f..e9274aec 100644
--- a/src/reactpy_django/hooks.py
+++ b/src/reactpy_django/hooks.py
@@ -12,6 +12,7 @@
 )
 from uuid import uuid4
 
+import dill
 import orjson
 from channels import DEFAULT_CHANNEL_LAYER
 from channels import auth as channels_auth
@@ -331,6 +332,111 @@ async def _set_user_data(data: dict):
     return UserData(query, mutation)
 
 
+def use_session_state(
+    default: Any,
+    key: str,
+    *,
+    save_default: bool = False,
+) -> tuple[Any, Callable[[Any], None]]:
+    """Persist state across WebSocket reconnects (and, optionally, page reloads).
+
+    This hook stores its value in the ReactPy database so that it can be restored after a
+    WebSocket reconnect, which would otherwise reset all in-memory component state. It is
+    more robust than in-memory state because it survives multi-process deployments and
+    round-robin load balancing across multiple hosts.
+
+    The state's scope is controlled by the ``REACTPY_SESSION_STATE_MODE`` setting:
+
+    - ``"tab"`` (default): state is scoped to the rendered component (a per-tab, per-component
+      token that is stable across reconnects). Works for anonymous users without requiring
+      ``django.contrib.sessions``.
+    - ``"user"``: state is scoped to the authenticated user, falling back to a per-tab token
+      for anonymous users.
+
+    Args:
+        default: The value to use when no persisted state exists.
+        key: A unique identifier for this state slot within the computed scope. Multiple
+            ``use_session_state`` hooks in the same component must use distinct keys.
+
+    Kwargs:
+        save_default: If ``True``, the ``default`` value will be persisted when no state
+            already exists in the database.
+
+    Returns:
+        A tuple of ``(state, set_state)``. ``state`` is the current value (loaded from the
+        database, or ``default`` if none exists). ``set_state`` updates the in-memory value
+        immediately and schedules a debounced database write so that frequently-changing
+        values do not hammer the database.
+
+    Note:
+        Only serializable data may be stored. Values are serialized with ``dill``, so most
+        common Python objects are supported, but objects holding un-picklable resources
+        (e.g. open file handles or network connections) will fail.
+    """
+    from reactpy_django import config
+
+    scope_id = _resolve_session_state_scope_id()
+
+    # In-memory reactive state. This keeps the UI responsive while database writes are
+    # debounced in the background.
+    state, set_state = use_state(cast("Any", default))
+    loaded = use_ref(False)
+    latest = use_ref(default)
+    timer = use_ref(None)
+
+    @use_async_effect(dependencies=[key, scope_id])
+    async def load_state() -> None:
+        """Load the persisted value from the database once on mount."""
+        data = await _get_session_state(scope_id, key, default)
+        latest.current = data
+        set_state(data)
+        loaded.current = True
+        if save_default and data == default:
+            await _set_session_state(scope_id, key, data)
+
+    async def flush() -> None:
+        """Persist the latest value to the database."""
+        await _set_session_state(scope_id, key, latest.current)
+
+    async def debounced_flush() -> None:
+        """Wait for the sync interval and then persist the latest value."""
+        try:
+            await asyncio.sleep(config.REACTPY_SESSION_STATE_SYNC_INTERVAL)
+            await flush()
+        finally:
+            timer.current = None
+
+    def schedule_flush() -> None:
+        """Debounce database writes so rapid state changes coalesce into one write."""
+        if timer.current is not None and not timer.current.done():
+            timer.current.cancel()
+        timer.current = asyncio.create_task(debounced_flush())
+
+    @use_callback
+    def set_state_and_persist(value: Any) -> None:
+        """Update the in-memory state and schedule a debounced database write."""
+        latest.current = value
+        set_state(value)
+        schedule_flush()
+
+    @use_async_effect(dependencies=[])
+    async def flush_on_unmount() -> Callable[[], None]:
+        """Ensure the latest state is persisted when the component unmounts.
+
+        This is what makes state survive a WebSocket reconnect: the component's layout is
+        torn down on disconnect, so we flush any pending write before it is lost.
+        """
+
+        def _cleanup() -> None:
+            if timer.current is not None and not timer.current.done():
+                timer.current.cancel()
+            asyncio.create_task(flush())
+
+        return _cleanup
+
+    return state, set_state_and_persist
+
+
 def use_channel_layer(
     *,
     channel: str | None = None,
@@ -441,6 +547,45 @@ async def logout(rerender: bool = True) -> None:
     return UseAuthTuple(login=login, logout=logout)
 
 
+def _resolve_session_state_scope_id() -> str:
+    """Resolve the stable identity used to scope persistent session state.
+
+    In ``"tab"`` mode this is the rendered component's UUID (stable across reconnects).
+    In ``"user"`` mode this is the authenticated user's primary key, falling back to a
+    per-tab token for anonymous users so that unauthenticated visitors still get isolated,
+    persistent state.
+    """
+    from reactpy_django import config
+
+    root_id = use_root_id()
+
+    if config.REACTPY_SESSION_STATE_MODE == "user":
+        user = use_user()
+        if not user.is_anonymous:
+            return f"user:{get_pk(user)}"
+
+    return f"tab:{root_id}"
+
+
+async def _get_session_state(scope_id: str, key: str, default: Any) -> Any:
+    """Load a persisted session state value from the database, or return `default`."""
+    from reactpy_django.models import SessionStateModel
+
+    model = await SessionStateModel.objects.filter(scope_id=scope_id, key=key).afirst()
+    if model is None or model.data is None:
+        return default
+    return dill.loads(model.data)
+
+
+async def _set_session_state(scope_id: str, key: str, data: Any) -> None:
+    """Persist a session state value to the database."""
+    from reactpy_django.models import SessionStateModel
+
+    model, _ = await SessionStateModel.objects.aget_or_create(scope_id=scope_id, key=key)
+    model.data = dill.dumps(data)
+    await model.asave()
+
+
 async def _get_user_data(user: AbstractUser, default_data: dict | None, save_default_data: bool) -> dict | None:
     """The mutation function for `use_user_data`"""
     from reactpy_django.models import UserDataModel

From 742e67aafd160995c65d927c6ac7119d193b8f25 Mon Sep 17 00:00:00 2001
From: Mark Bakhit <archiethemonger@gmail.com>
Date: Mon, 14 Sep 2026 16:04:47 -0700
Subject: [PATCH 09/26] Add session state cleaning to clean task

---
 src/reactpy_django/tasks.py | 32 +++++++++++++++++++++++++++++++-
 1 file changed, 31 insertions(+), 1 deletion(-)

diff --git a/src/reactpy_django/tasks.py b/src/reactpy_django/tasks.py
index 44d4eb14..95326856 100644
--- a/src/reactpy_django/tasks.py
+++ b/src/reactpy_django/tasks.py
@@ -13,13 +13,14 @@
     from reactpy_django.models import Config
 
 CLEAN_NEEDED_BY: datetime = datetime(year=1, month=1, day=1, tzinfo=timezone.now().tzinfo)
-CleaningArgs = Literal["all", "sessions", "auth_tokens", "user_data"]
+CleaningArgs = Literal["all", "sessions", "auth_tokens", "user_data", "session_state"]
 
 
 def clean(*args: CleaningArgs, immediate: bool = False, verbosity: int = 1):
     from reactpy_django.config import (
         REACTPY_CLEAN_AUTH_TOKENS,
         REACTPY_CLEAN_SESSIONS,
+        REACTPY_CLEAN_SESSION_STATE,
         REACTPY_CLEAN_USER_DATA,
     )
     from reactpy_django.models import Config
@@ -33,11 +34,13 @@ def clean(*args: CleaningArgs, immediate: bool = False, verbosity: int = 1):
         sessions = REACTPY_CLEAN_SESSIONS
         auth_tokens = REACTPY_CLEAN_AUTH_TOKENS
         user_data = REACTPY_CLEAN_USER_DATA
+        session_state = REACTPY_CLEAN_SESSION_STATE
 
         if args:
             sessions = any(value in args for value in ("sessions", "all"))
             auth_tokens = any(value in args for value in ("auth_tokens", "all"))
             user_data = any(value in args for value in ("user_data", "all"))
+            session_state = any(value in args for value in ("session_state", "all"))
 
         if sessions:
             clean_component_sessions(verbosity)
@@ -45,6 +48,8 @@ def clean(*args: CleaningArgs, immediate: bool = False, verbosity: int = 1):
             clean_auth_tokens(verbosity)
         if user_data:
             clean_user_data(verbosity)
+        if session_state:
+            clean_session_state(verbosity)
 
 
 def clean_component_sessions(verbosity: int = 1):
@@ -124,6 +129,31 @@ def clean_user_data(verbosity: int = 1):
         inspect_clean_duration(start_time, "user data", verbosity)
 
 
+def clean_session_state(verbosity: int = 1):
+    """Delete any expired ReactPy session state from the database.
+
+    Session state entries that have not been updated within ``REACTPY_SESSION_STATE_MAX_AGE``
+    are considered stale (e.g. the browser tab was closed) and are removed.
+    """
+    from reactpy_django.config import DJANGO_DEBUG, REACTPY_SESSION_STATE_MAX_AGE
+    from reactpy_django.models import SessionStateModel
+
+    if verbosity >= 2:
+        _logger.info("Cleaning ReactPy session state...")
+
+    start_time = timezone.now()
+    expiration_date = timezone.now() - timedelta(seconds=REACTPY_SESSION_STATE_MAX_AGE)
+    state_objects = SessionStateModel.objects.filter(updated_at__lte=expiration_date)
+
+    if verbosity >= 2:
+        _logger.info("Deleting %d expired session state objects...", state_objects.count())
+
+    state_objects.delete()
+
+    if DJANGO_DEBUG or verbosity >= 2:
+        inspect_clean_duration(start_time, "session state", verbosity)
+
+
 def clean_is_needed(config: Config | None = None) -> bool:
     """Check if a clean is needed. This function avoids unnecessary database reads by caching the
     CLEAN_NEEDED_BY date."""

From 1fe926b459ac1d3b6c5e9c8796e55540109c90eb Mon Sep 17 00:00:00 2001
From: Mark Bakhit <archiethemonger@gmail.com>
Date: Mon, 14 Sep 2026 16:05:20 -0700
Subject: [PATCH 10/26] Add --session-state flag to clean_reactpy command

---
 src/reactpy_django/management/commands/clean_reactpy.py | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/src/reactpy_django/management/commands/clean_reactpy.py b/src/reactpy_django/management/commands/clean_reactpy.py
index 804d5a3e..4a6f77d0 100644
--- a/src/reactpy_django/management/commands/clean_reactpy.py
+++ b/src/reactpy_django/management/commands/clean_reactpy.py
@@ -12,7 +12,7 @@ def handle(self, *_args, **options):
         from reactpy_django.tasks import CleaningArgs, clean
 
         verbosity = options.pop("verbosity", 1)
-        valid_args: set[CleaningArgs] = {"all", "sessions", "auth_tokens", "user_data"}
+        valid_args: set[CleaningArgs] = {"all", "sessions", "auth_tokens", "user_data", "session_state"}
         cleaning_args: set[CleaningArgs] = {arg for arg in options if arg in valid_args and options[arg]} or {"all"}
 
         clean(*cleaning_args, immediate=True, verbosity=verbosity)
@@ -36,3 +36,8 @@ def add_arguments(self, parser):
             action="store_true",
             help="Clean authentication tokens. This value can be combined with other cleaning options.",
         )
+        parser.add_argument(
+            "--session-state",
+            action="store_true",
+            help="Clean persistent session state. This value can be combined with other cleaning options.",
+        )

From 5f14fbcccdc8037a15fe7799d7b77a04ac3eeac4 Mon Sep 17 00:00:00 2001
From: Mark Bakhit <archiethemonger@gmail.com>
Date: Mon, 14 Sep 2026 16:07:41 -0700
Subject: [PATCH 11/26] Add session state database tests

---
 tests/test_app/tests/test_database.py | 41 ++++++++++++++++++++++++++-
 1 file changed, 40 insertions(+), 1 deletion(-)

diff --git a/tests/test_app/tests/test_database.py b/tests/test_app/tests/test_database.py
index 78856a89..01f5d80c 100644
--- a/tests/test_app/tests/test_database.py
+++ b/tests/test_app/tests/test_database.py
@@ -7,7 +7,7 @@
 from django.test import TransactionTestCase
 
 from reactpy_django import tasks
-from reactpy_django.models import ComponentSession, UserDataModel
+from reactpy_django.models import ComponentSession, SessionStateModel, UserDataModel
 from reactpy_django.types import ComponentParams
 
 
@@ -58,6 +58,45 @@ def test_component_params(self):
             config.REACTPY_SESSION_MAX_AGE = initial_session_max_age
             config.REACTPY_CLEAN_USER_DATA = initial_clean_user_data
 
+    def test_session_state_roundtrip_and_cleanup(self):
+        from reactpy_django import config
+        from reactpy_django.hooks import _get_session_state, _set_session_state
+
+        initial_clean_session_state = config.REACTPY_CLEAN_SESSION_STATE
+        initial_session_state_max_age = config.REACTPY_SESSION_STATE_MAX_AGE
+        config.REACTPY_CLEAN_SESSION_STATE = False
+        config.REACTPY_SESSION_STATE_MAX_AGE = 1
+
+        try:
+            scope_id = f"tab:{uuid4()}"
+            key = "my_state"
+
+            # No state exists yet, so the default is returned
+            assert _get_session_state(scope_id, key, default="default") == "default"
+
+            # Persist some state and read it back
+            state = {"count": 1, "items": [1, 2, 3]}
+            _set_session_state(scope_id, key, state)
+            assert SessionStateModel.objects.filter(scope_id=scope_id, key=key).count() == 1
+            assert _get_session_state(scope_id, key, default="default") == state
+
+            # Persisting the same scope+key updates the existing row (no duplicate)
+            _set_session_state(scope_id, key, {"count": 2})
+            assert SessionStateModel.objects.filter(scope_id=scope_id, key=key).count() == 1
+            assert _get_session_state(scope_id, key, default="default") == {"count": 2}
+
+            # Untouched state is considered stale and gets cleaned up
+            fresh_scope = f"tab:{uuid4()}"
+            _set_session_state(fresh_scope, "other", "keep-me")
+            assert SessionStateModel.objects.count() == 2
+            sleep(config.REACTPY_SESSION_STATE_MAX_AGE)
+            tasks.clean_session_state()
+            assert SessionStateModel.objects.count() == 1
+            assert _get_session_state(fresh_scope, "other", default="default") == "keep-me"
+        finally:
+            config.REACTPY_CLEAN_SESSION_STATE = initial_clean_session_state
+            config.REACTPY_SESSION_STATE_MAX_AGE = initial_session_state_max_age
+
     def _save_params_to_db(self, value: Any) -> ComponentParams:
         db = next(iter(self.databases))
         param_data = ComponentParams((value,), {"test_value": value})

From 404ca18b145f20441054abaede13a13daf9a81c6 Mon Sep 17 00:00:00 2001
From: Mark Bakhit <archiethemonger@gmail.com>
Date: Mon, 14 Sep 2026 16:08:46 -0700
Subject: [PATCH 12/26] Use explicit constraint/index names in
 SessionStateModel

---
 src/reactpy_django/models.py | 81 ++----------------------------------
 1 file changed, 4 insertions(+), 77 deletions(-)

diff --git a/src/reactpy_django/models.py b/src/reactpy_django/models.py
index 82b7921a..f59f8bea 100644
--- a/src/reactpy_django/models.py
+++ b/src/reactpy_django/models.py
@@ -1,70 +1,3 @@
-from datetime import timedelta
-
-from django.contrib.auth import get_user_model
-from django.db import models
-from django.db.models.signals import pre_delete
-from django.dispatch import receiver
-from django.utils import timezone
-
-from reactpy_django.utils import get_pk
-
-
-class ComponentSession(models.Model):
-    """A model for storing component sessions.
-
-    This is used to store component arguments provided within Django templates.
-    These arguments are retrieved within the layout renderer (WebSocket consumer)."""
-
-    uuid = models.UUIDField(primary_key=True, editable=False, unique=True)
-    params = models.BinaryField(editable=False)
-    last_accessed = models.DateTimeField(auto_now=True)
-
-
-class AuthToken(models.Model):
-    """A model that contains any relevant data needed to force Django's HTTP session to
-    match the websocket session.
-
-    The session key is tied to an arbitrary UUID token for security (obfuscation) purposes.
-
-    Source code must be written to respect the expiration property of this model."""
-
-    value = models.UUIDField(primary_key=True, editable=False, unique=True)
-    session_key = models.CharField(max_length=40, editable=False)
-    created_at = models.DateTimeField(auto_now_add=True, editable=False)
-
-    @property
-    def expired(self) -> bool:
-        from reactpy_django.config import REACTPY_AUTH_TOKEN_MAX_AGE
-
-        return self.created_at < (timezone.now() - timedelta(seconds=REACTPY_AUTH_TOKEN_MAX_AGE))
-
-
-class Config(models.Model):
-    """A singleton model for storing ReactPy configuration."""
-
-    cleaned_at = models.DateTimeField(auto_now_add=True)
-
-    def save(self, *args, **kwargs):
-        """Singleton save method."""
-        self.pk = 1
-        super().save(*args, **kwargs)
-
-    @classmethod
-    def load(cls):
-        obj, _ = cls.objects.get_or_create(pk=1)
-        return obj
-
-
-class UserDataModel(models.Model):
-    """A model for storing `user_state` data."""
-
-    # We can't store User as a ForeignKey/OneToOneField because it may not be in the same database
-    # and Django does not allow cross-database relations. Also, since we can't know the type of the UserModel PK,
-    # we store it as a string to normalize.
-    user_pk = models.CharField(max_length=255, unique=True)
-    data = models.BinaryField(null=True, blank=True)
-
-
 class SessionStateModel(models.Model):
     """A model for storing `session_state` data.
 
@@ -82,15 +15,9 @@ class SessionStateModel(models.Model):
     updated_at = models.DateTimeField(auto_now=True)
 
     class Meta:
-        unique_together = ("scope_id", "key")
+        constraints = [
+            models.UniqueConstraint(fields=["scope_id", "key"], name="reactpy_session_state_unique"),
+        ]
         indexes = [
-            models.Index(fields=["scope_id", "updated_at"]),
+            models.Index(fields=["scope_id", "updated_at"], name="reactpy_session_state_idx"),
         ]
-
-
-@receiver(pre_delete, sender=get_user_model(), dispatch_uid="reactpy_delete_user_data")
-def delete_user_data(sender, instance, **kwargs):
-    """Delete ReactPy's `UserDataModel` when a Django `User` is deleted."""
-    pk = get_pk(instance)
-
-    UserDataModel.objects.filter(user_pk=pk).delete()

From dde53dac70b8719bc1b85798cdf3f9f3cd1b0f0a Mon Sep 17 00:00:00 2001
From: Mark Bakhit <archiethemonger@gmail.com>
Date: Mon, 14 Sep 2026 16:09:12 -0700
Subject: [PATCH 13/26] Restore models.py with explicit constraint names in
 SessionStateModel

---
 src/reactpy_django/models.py | 75 ++++++++++++++++++++++++++++++++++++
 1 file changed, 75 insertions(+)

diff --git a/src/reactpy_django/models.py b/src/reactpy_django/models.py
index f59f8bea..637a7be0 100644
--- a/src/reactpy_django/models.py
+++ b/src/reactpy_django/models.py
@@ -1,3 +1,70 @@
+from datetime import timedelta
+
+from django.contrib.auth import get_user_model
+from django.db import models
+from django.db.models.signals import pre_delete
+from django.dispatch import receiver
+from django.utils import timezone
+
+from reactpy_django.utils import get_pk
+
+
+class ComponentSession(models.Model):
+    """A model for storing component sessions.
+
+    This is used to store component arguments provided within Django templates.
+    These arguments are retrieved within the layout renderer (WebSocket consumer)."""
+
+    uuid = models.UUIDField(primary_key=True, editable=False, unique=True)
+    params = models.BinaryField(editable=False)
+    last_accessed = models.DateTimeField(auto_now=True)
+
+
+class AuthToken(models.Model):
+    """A model that contains any relevant data needed to force Django's HTTP session to
+    match the websocket session.
+
+    The session key is tied to an arbitrary UUID token for security (obfuscation) purposes.
+
+    Source code must be written to respect the expiration property of this model."""
+
+    value = models.UUIDField(primary_key=True, editable=False, unique=True)
+    session_key = models.CharField(max_length=40, editable=False)
+    created_at = models.DateTimeField(auto_now_add=True, editable=False)
+
+    @property
+    def expired(self) -> bool:
+        from reactpy_django.config import REACTPY_AUTH_TOKEN_MAX_AGE
+
+        return self.created_at < (timezone.now() - timedelta(seconds=REACTPY_AUTH_TOKEN_MAX_AGE))
+
+
+class Config(models.Model):
+    """A singleton model for storing ReactPy configuration."""
+
+    cleaned_at = models.DateTimeField(auto_now_add=True)
+
+    def save(self, *args, **kwargs):
+        """Singleton save method."""
+        self.pk = 1
+        super().save(*args, **kwargs)
+
+    @classmethod
+    def load(cls):
+        obj, _ = cls.objects.get_or_create(pk=1)
+        return obj
+
+
+class UserDataModel(models.Model):
+    """A model for storing `user_state` data."""
+
+    # We can't store User as a ForeignKey/OneToOneField because it may not be in the same database
+    # and Django does not allow cross-database relations. Also, since we can't know the type of the UserModel PK,
+    # we store it as a string to normalize.
+    user_pk = models.CharField(max_length=255, unique=True)
+    data = models.BinaryField(null=True, blank=True)
+
+
 class SessionStateModel(models.Model):
     """A model for storing `session_state` data.
 
@@ -21,3 +88,11 @@ class Meta:
         indexes = [
             models.Index(fields=["scope_id", "updated_at"], name="reactpy_session_state_idx"),
         ]
+
+
+@receiver(pre_delete, sender=get_user_model(), dispatch_uid="reactpy_delete_user_data")
+def delete_user_data(sender, instance, **kwargs):
+    """Delete ReactPy's `UserDataModel` when a Django `User` is deleted."""
+    pk = get_pk(instance)
+
+    UserDataModel.objects.filter(user_pk=pk).delete()

From 3dfe9d323ed444afaa191ef6460598e703a7a359 Mon Sep 17 00:00:00 2001
From: Mark Bakhit <archiethemonger@gmail.com>
Date: Mon, 14 Sep 2026 16:09:23 -0700
Subject: [PATCH 14/26] Match migration constraint/index names to model

---
 src/reactpy_django/migrations/0008_sessionstatemodel.py | 7 ++-----
 1 file changed, 2 insertions(+), 5 deletions(-)

diff --git a/src/reactpy_django/migrations/0008_sessionstatemodel.py b/src/reactpy_django/migrations/0008_sessionstatemodel.py
index 8bb7976e..d58ac987 100644
--- a/src/reactpy_django/migrations/0008_sessionstatemodel.py
+++ b/src/reactpy_django/migrations/0008_sessionstatemodel.py
@@ -20,11 +20,8 @@ class Migration(migrations.Migration):
                 ('updated_at', models.DateTimeField(auto_now=True)),
             ],
             options={
-                'indexes': [models.Index(fields=['scope_id', 'updated_at'], name='reactpy_dj_scope_i_1cf868_idx')],
+                'indexes': [models.Index(fields=['scope_id', 'updated_at'], name='reactpy_session_state_idx')],
+                'constraints': [models.UniqueConstraint(fields=('scope_id', 'key'), name='reactpy_session_state_unique')],
             },
         ),
-        migrations.AddConstraint(
-            model_name='sessionstatemodel',
-            constraint=models.UniqueConstraint(fields=('scope_id', 'key'), name='reactpy_django_sess_scope_id_key'),
-        ),
     ]

From bd050cdc4c2408653c2e115e30861978041c24b9 Mon Sep 17 00:00:00 2001
From: Mark Bakhit <archiethemonger@gmail.com>
Date: Mon, 14 Sep 2026 16:10:37 -0700
Subject: [PATCH 15/26] Add persistent session state feature to changelog

---
 CHANGELOG.md | 620 +--------------------------------------------------
 1 file changed, 6 insertions(+), 614 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8526d721..72bb2f8c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,619 +1,11 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-<!--attr-start-->
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-<!--attr-end-->
-
-<!--
-Using the following categories, list your changes in this order:
-[Added, Changed, Deprecated, Removed, Fixed, Security]
-
-Don't forget to remove deprecated code on each major release!
--->
-
-<!--changelog-start-->
-
 ## [Unreleased]
 
 ### Added
 
+- Add `reactpy_django.hooks.use_session_state` hook for persistent state across WebSocket reconnects.
+    - State is stored in the ReactPy database, so it survives multi-process deployments and round-robin load balancing across hosts.
+    - `settings.py:REACTPY_SESSION_STATE_MODE` to control whether state is scoped per-tab (default) or per-user.
+    - `settings.py:REACTPY_SESSION_STATE_SYNC_INTERVAL` to control how frequently state is flushed to the database.
+    - `settings.py:REACTPY_SESSION_STATE_MAX_AGE` to control how long stale session state is retained.
+    - `settings.py:REACTPY_CLEAN_SESSION_STATE` to control whether stale session state is cleaned up during automatic cleanups.
 - Automatically serve ReactPy wheel from Django's static directory when using PyScript.
-
-### Changed
-
-- Use one WebSocket per client webpage.
-- Updated dependencies: `reactpy>=2.0.0, <3.0.0` and `reactpy-router>=3.0.0, <4.0.0`.
-- Updated Python support to 3.11–3.14.
-- Replaced PyScript `<py-script>` tags with standard `<script type="py">` tags.
-- Updated the interface for `reactpy.hooks.use_channel_layer` to be more intuitive.
-    - Arguments now must be provided as keyworded arguments.
-    - The `name` argument has been renamed to `channel`.
-    - The `group_name` argument has been renamed to `group`.
-    - The `group_add` and `group_discard` arguments have been removed for simplicity.
-- To improve performance, `preact` is now used as the default client-side library instead of `react`.
-- ReactPy v2 compatibility! This release aligns `reactpy-django` with ReactPy v2's API.
-    - Refactored `DjangoResolver` to extend `ReactPyResolver` instead of `StarletteResolver`.
-    - Replaced `web.module_from_file`/`web.export` with `reactjs.component_from_file`.
-    - Replaced `reactpy.backend.types` and `reactpy.core.types` imports with `reactpy.types`.
-    - Renamed `Location.pathname` to `Location.path` and `Location.search` to `Location.query_string`.
-
-### Removed
-
-- Removed `reactpy_django.components.pyscript_component`. Use `reactpy.executors.pyscript.pyscript_component` instead.
-- Removed the entire `reactpy_django/pyscript/` package (component template, layout handler, and utilities) in favor of ReactPy core's PyScript executor.
-- Removed `reactpy_django.html.pyscript`. Use `reactpy.html.py_script` instead.
-- Removed `nest_asyncio` dependency.
-
-### Fixed
-
-- Resolved bug where `django_form` events would sometimes not occur.
-
-### [5.2.1] - 2025-01-10
-
-### Changed
-
-- Use the latest version of `@reactpy/client` which includes a fix for needless client-side component re-creation.
-
-### [5.2.0] - 2024-12-29
-
-### Added
-
-- User login/logout features!
-    - `reactpy_django.hooks.use_auth` to provide **persistent** `login` and `logout` functionality to your components.
-    - `settings.py:REACTPY_AUTH_TOKEN_MAX_AGE` to control the maximum seconds before ReactPy's login token expires.
-    - `settings.py:REACTPY_CLEAN_AUTH_TOKENS` to control whether ReactPy should clean up expired authentication tokens during automatic cleanups.
-- Automatically convert Django forms to ReactPy forms via the new `reactpy_django.components.django_form` component!
-- The ReactPy component tree can now be forcibly re-rendered via the new `reactpy_django.hooks.use_rerender` hook.
-
-### Changed
-
-- Refactoring of internal code to improve maintainability. No changes to publicly documented API.
-
-### Fixed
-
-- Fixed bug where pre-rendered components could generate a `SynchronousOnlyOperation` exception if they access a freshly logged out Django user object.
-
-## [5.1.1] - 2024-12-02
-
-### Fixed
-
-- Fixed regression from the previous release where components would sometimes not output debug messages when `settings.py:DEBUG` is enabled.
-
-### Changed
-
-- Set upper limit on ReactPy version to `<2.0.0`.
-- ReactPy web modules are now streamed in chunks.
-- ReactPy web modules are now streamed using asynchronous file reading to improve performance.
-- Performed refactoring to utilize `ruff` as this repository's linter.
-
-## [5.1.0] - 2024-11-24
-
-### Added
-
-- `settings.py:REACTPY_ASYNC_RENDERING` to enable asynchronous rendering of components.
-
-### Changed
-
-- Bumped the minimum ReactPy version to `1.1.0`.
-
-## [5.0.0] - 2024-10-22
-
-### Changed
-
-- Now using ReactPy-Router v1 for URL routing, which comes with a slightly different API than before.
-- Removed dependency on `aiofile`.
-
-### Removed
-
-- Removed the following **deprecated** features:
-    - The `compatibility` argument on `reactpy_django.components.view_to_component`
-    - `reactpy_django.components.view_to_component` **usage as a decorator**
-    - `reactpy_django.decorators.auth_required`
-    - `reactpy_django.REACTPY_WEBSOCKET_PATH`
-    - `settings.py:REACTPY_WEBSOCKET_URL`
-
-## [4.0.0] - 2024-06-22
-
-### Added
-
-- Client-side Python components can now be rendered via the new `{% pyscript_component %}` template tag
-    - You must first call the `{% pyscript_setup %}` template tag to load PyScript dependencies
-- Client-side components can be embedded into existing server-side components via `reactpy_django.components.pyscript_component`.
-- Tired of writing JavaScript? You can now write PyScript code that runs directly within client browser via the `reactpy_django.html.pyscript` element.
-    - This is a viable substitution for most JavaScript code.
-
-### Changed
-
-- New syntax for `use_query` and `use_mutation` hooks. Here's a quick comparison of the changes:
-
-    ```python
-    query = use_query(QueryOptions(thread_sensitive=True), get_items, foo="bar") # Old
-    query = use_query(get_items, {"foo":"bar"}, thread_sensitive=True) # New
-
-    mutation = use_mutation(MutationOptions(thread_sensitive=True), remove_item) # Old
-    mutation = use_mutation(remove_item, thread_sensitive=True) # New
-    ```
-
-### Removed
-
-- `QueryOptions` and `MutationOptions` have been removed. The value contained within these objects are now passed directly into the hook.
-
-### Fixed
-
-- Resolved a bug where Django-ReactPy would not properly detect `settings.py:DEBUG`.
-
-## [3.8.1] - 2024-05-07
-
-### Added
-
-- Python 3.12 compatibility
-
-## [3.8.0] - 2024-02-20
-
-### Added
-
-- Built-in cross-process communication mechanism via the `reactpy_django.hooks.use_channel_layer` hook.
-- Access to the root component's `id` via the `reactpy_django.hooks.use_root_id` hook.
-- More robust control over ReactPy clean up tasks!
-    - `settings.py:REACTPY_CLEAN_INTERVAL` to control how often ReactPy automatically performs cleaning tasks.
-    - `settings.py:REACTPY_CLEAN_SESSIONS` to control whether ReactPy should clean up expired sessions during automatic cleanups.
-    - `settings.py:REACTPY_CLEAN_USER_DATA` to control whether ReactPy should clean up orphaned user data during automatic cleanups.
-    - `python manage.py clean_reactpy` command to manually perform ReactPy clean up tasks.
-
-### Changed
-
-- Simplified code for cascading deletion of user data.
-
-## [3.7.0] - 2024-01-30
-
-### Added
-
-- An "offline component" can now be displayed when the client disconnects from the server.
-- URL router now supports a `*` wildcard to create default routes.
-
-## [3.6.0] - 2024-01-10
-
-### Added
-
-- Built-in Single Page Application (SPA) support!
-    - `reactpy_django.router.django_router` can be used to render your Django application as a SPA.
-- SEO compatible rendering!
-    - `settings.py:REACTPY_PRERENDER` can be set to `True` to make components pre-render by default.
-    - Or, you can enable it on individual components via the template tag: `{% component "..." prerender="True" %}`.
-- New `view_to_iframe` feature!
-    - `reactpy_django.components.view_to_iframe` uses an `<iframe>` to render a Django view.
-    - `reactpy_django.utils.register_iframe` tells ReactPy which views `view_to_iframe` can use.
-- New Django `User` related features!
-    - `reactpy_django.hooks.use_user` can be used to access the current user.
-    - `reactpy_django.hooks.use_user_data` provides a simplified interface for storing user key-value data.
-    - `reactpy_django.decorators.user_passes_test` is inspired by the [equivalent Django decorator](http://docs.djangoproject.com/en/stable/topics/auth/default/#django.contrib.auth.decorators.user_passes_test), but ours works with ReactPy components.
-    - `settings.py:REACTPY_AUTO_RELOGIN` will cause component WebSocket connections to automatically [re-login](https://channels.readthedocs.io/en/latest/topics/authentication.html#how-to-log-a-user-in-out) users that are already authenticated. This is useful to continuously update `last_login` timestamps and refresh the [Django login session](https://docs.djangoproject.com/en/stable/topics/http/sessions/).
-
-### Changed
-
-- Renamed undocumented utility function `ComponentPreloader` to `RootComponentFinder`.
-- It is now recommended to call `as_view()` when using `view_to_component` or `view_to_iframe` with Class Based Views.
-- For thread safety, `thread_sensitive=True` has been enabled in all `sync_to_async` functions where ORM queries are possible.
-- `reactpy_django.hooks.use_mutation` now has a `__call__` method. So rather than writing `my_mutation.execute(...)`, you can now write `my_mutation(...)`.
-
-### Deprecated
-
-- The `compatibility` argument on `reactpy_django.components.view_to_component` is deprecated.
-    - Use `view_to_iframe` as a replacement.
-- `reactpy_django.components.view_to_component` **usage as a decorator** is deprecated.
-    - Check the docs on how to use `view_to_component` as a function instead.
-- `reactpy_django.decorators.auth_required` is deprecated.
-    - Use `reactpy_django.decorators.user_passes_test` instead.
-    - An equivalent to `auth_required`'s default is `@user_passes_test(lambda user: user.is_active)`.
-
-### Fixed
-
-- Fixed a bug where exception stacks would not print on failed component renders.
-
-## [3.5.1] - 2023-09-07
-
-### Added
-
-- Warning W018 (`Suspicious position of 'reactpy_django' in INSTALLED_APPS`) has been added.
-
-### Changed
-
-- The default postprocessor can now disabled by setting `REACTPY_DEFAULT_QUERY_POSTPROCESSOR` to `None`.
-- Massive overhaul of docs styling.
-
-## [3.5.0] - 2023-08-26
-
-### Added
-
-- More customization for reconnection behavior through new settings!
-    - `REACTPY_RECONNECT_INTERVAL`
-    - `REACTPY_RECONNECT_MAX_INTERVAL`
-    - `REACTPY_RECONNECT_MAX_RETRIES`
-    - `REACTPY_RECONNECT_BACKOFF_MULTIPLIER`
-- [ReactPy-Django docs](https://reactive-python.github.io/reactpy-django/) are now version controlled via [mike](https://github.com/jimporter/mike)!
-
-### Changed
-
-- Bumped the minimum ReactPy version to `1.0.2`.
-- Prettier WebSocket URLs for components that do not have sessions.
-- Template tag will now only validate `args`/`kwargs` if `settings.py:DEBUG` is enabled.
-- Bumped the minimum `@reactpy/client` version to `0.3.1`
-- Use TypeScript instead of JavaScript for this repository.
-- Bumped the minimum Django version to `4.2`.
-
-???+ note "Django 4.2+ is required"
-
-    ReactPy-Django will continue bumping minimum Django requirements to versions that increase async support.
-
-    This "latest-only" trend will continue until Django has all async features that ReactPy benefits from. After this point, ReactPy-Django will begin supporting all maintained Django versions.
-
-### Removed
-
-- `settings.py:REACTPY_RECONNECT_MAX` is removed. See the docs for the new `REACTPY_RECONNECT_*` settings.
-
-## [3.4.0] - 2023-08-18
-
-### Added
-
-- **Distributed Computing:** ReactPy components can now optionally be rendered by a completely separate server!
-    - `REACTPY_DEFAULT_HOSTS` setting can round-robin a list of ReactPy rendering hosts.
-    - `host` argument has been added to the `component` template tag to force components to render on a specific host.
-- `reactpy_django.utils.register_component` function can manually register root components.
-    - Useful if you have dedicated ReactPy rendering application(s) that do not use HTML templates.
-
-### Changed
-
-- ReactPy will now provide a warning if your HTTP URLs are not on the same prefix as your WebSockets.
-- Cleaner logging output for auto-detected ReactPy root components.
-
-### Deprecated
-
-- `reactpy_django.REACTPY_WEBSOCKET_PATH` is deprecated. The identical replacement is `REACTPY_WEBSOCKET_ROUTE`.
-- `settings.py:REACTPY_WEBSOCKET_URL` is deprecated. The similar replacement is `REACTPY_URL_PREFIX`.
-
-### Removed
-
-- Warning W007 (`REACTPY_WEBSOCKET_URL doesn't end with a slash`) has been removed. ReactPy now automatically handles slashes.
-- Warning W008 (`REACTPY_WEBSOCKET_URL doesn't start with an alphanumeric character`) has been removed. ReactPy now automatically handles this scenario.
-- Error E009 (`channels is not in settings.py:INSTALLED_APPS`) has been removed. Newer versions of `channels` do not require installation via `INSTALLED_APPS` to receive an ASGI web server.
-
-## [3.3.2] - 2023-08-13
-
-### Added
-
-- ReactPy WebSocket will now decode messages via `orjson` resulting in an ~6% overall performance improvement.
-- Built-in `asyncio` event loops are now patched via `nest_asyncio`, resulting in an ~10% overall performance improvement. This has no performance impact if you are running your web server with `uvloop`.
-
-### Fixed
-
-- Fix bug where `REACTPY_WEBSOCKET_URL` always generates a warning if unset.
-- Fixed bug on Windows where `assert f is self._write_fut` would be raised by `uvicorn` when `REACTPY_BACKHAUL_THREAD = True`.
-- Fixed bug on Windows where rendering behavior would be jittery with `daphne` when `REACTPY_BACKHAUL_THREAD = True`.
-
-## [3.3.1] - 2023-08-08
-
-### Added
-
-- Additional system checks for ReactPy misconfigurations.
-
-### Changed
-
-- `REACTPY_BACKHAUL_THREAD` now defaults to `False`.
-
-## [3.3.0] - 2023-08-05
-
-### Added
-
-- Added system checks for a variety of common ReactPy misconfigurations.
-- `REACTPY_BACKHAUL_THREAD` setting to enable/disable threading behavior.
-
-### Changed
-
-- If using `settings.py:REACTPY_DATABASE`, `reactpy_django.database.Router` must now be registered in `settings.py:DATABASE_ROUTERS`.
-- By default, ReactPy will now use a backhaul thread to increase performance.
-- Minimum Python version required is now `3.9`
-- A thread-safe cache is no longer required.
-
-## [3.2.1] - 2023-06-29
-
-### Added
-
-- Template tag exception details are now rendered on the webpage when `settings.py:DEBUG` is enabled.
-
-### Fixed
-
-- Prevent exceptions within the `component` template tag from causing the whole template to fail to render.
-
-## [3.2.0] - 2023-06-08
-
-### Added
-
-- Added warning if poor system/cache/database performance is detected while in `DEBUG` mode.
-- Added `REACTPY_AUTH_BACKEND` setting to allow for custom authentication backends.
-
-### Changed
-
-- Using `SessionMiddlewareStack` is now optional.
-- Using `AuthMiddlewareStack` is now optional.
-
-## [3.1.0] - 2023-05-06
-
-### Added
-
-- `use_query` now supports async functions.
-- `use_mutation` now supports async functions.
-- `reactpy_django.types.QueryOptions.thread_sensitive` option to customize how sync queries are executed.
-- `reactpy_django.hooks.use_mutation` now accepts `reactpy_django.types.MutationOptions` option to customize how mutations are executed.
-
-### Changed
-
-- The `mutate` argument on `reactpy_django.hooks.use_mutation` has been renamed to `mutation`.
-
-### Fixed
-
-- Fix bug where ReactPy utilizes Django's default cache timeout, which can prematurely expire the component cache.
-
-## [3.0.1] - 2023-04-06
-
-### Changed
-
-- `reactpy-django` database entries are no longer cleaned during Django application startup. Instead, it will occur on webpage loads if `REACTPY_RECONNECT_MAX` seconds has elapsed since the last cleaning.
-
-## [3.0.0-reactpy] - 2023-03-30
-
-### Changed
-
-- `django-idom` has been renamed to `reactpy-django`! Please note that all references to the word `idom` in your code should be changed to `reactpy`. See the docs for more details.
-
-## [3.0.0] - 2023-03-08
-
-???+ note
-
-    This is Django-IDOM's biggest update yet!
-
-    To upgrade from previous version you will need to...
-
-    1. Install `django-idom >= 3.0.0`
-    2. Run `idom rewrite-keys <DIR>` and `idom rewrite-camel-case-props <DIR>` to update your `idom.html.*` calls to the new syntax
-    3. Run `python manage.py migrate` to create the new Django-IDOM database entries
-
-### Added
-
-- The `idom` client will automatically configure itself to debug mode depending on `settings.py:DEBUG`.
-- `use_connection` hook for returning the browser's active `Connection`.
-- `IDOM_CACHE` is now configurable within `settings.py` to whatever cache name you wish.
-
-### Changed
-
-- It is now mandatory to run `manage.py migrate` after installing IDOM.
-- Bumped the minimum IDOM version to 1.0.0. Due to IDOM 1.0.0, `idom.html.*`...
-    - HTML properties can now be `snake_case`. For example `className` now becomes `class_name`.
-    - `key=...` is now declared within the props `dict` (rather than as a `kwarg`).
-- The `component` template tag now supports both positional and keyword arguments.
-- The `component` template tag now supports non-serializable arguments.
-- `IDOM_WS_MAX_RECONNECT_TIMEOUT` setting has been renamed to `IDOM_RECONNECT_MAX`.
-
-### Removed
-
-- `django_idom.hooks.use_websocket` has been removed. The similar replacement is `django_idom.hooks.use_connection`.
-- `django_idom.types.IdomWebsocket` has been removed. The similar replacement is `django_idom.types.Connection`.
-- `settings.py:CACHE['idom']` is no longer used by default. The name of the cache back-end must now be specified with the `IDOM_CACHE` setting.
-
-### Fixed
-
-- `view_to_component` will now retain the contents of a `<head>` tag when rendering.
-- React client is now set to `production` rather than `development`.
-- `use_query` will now utilize `field.related_name` when postprocessing many-to-one relationships.
-
-### Security
-
-- Fixed a potential method of component template tag argument spoofing.
-- Exception information will no longer be displayed on the page, based on the value of `settings.py:DEBUG`.
-
-## [2.2.1] - 2023-01-09
-
-### Fixed
-
-- Fixed bug where `use_query` would not recursively fetch many-to-one relationships.
-- IDOM preloader will now print out the exception stack when failing to import a module.
-
-## [2.2.0] - 2022-12-28
-
-### Added
-
-- Add `options: QueryOptions` parameter to `use_query` to allow for configuration of this hook.
-
-### Changed
-
-- By default, `use_query` will recursively prefetch all many-to-many or many-to-one relationships to prevent `SynchronousOnlyOperation` exceptions.
-
-### Removed
-
-- `django_idom.hooks._fetch_lazy_fields` has been deleted. The equivalent replacement is `django_idom.utils.django_query_postprocessor`.
-
-## [2.1.0] - 2022-11-01
-
-### Changed
-
-- Minimum `channels` version is now `4.0.0`.
-
-### Fixed
-
-- Change type hint on `view_to_component` callable to have `request` argument be optional.
-- Change type hint on `view_to_component` to represent it as a decorator with parenthesis (such as `@view_to_component(compatibility=True)`)
-
-### Security
-
-- Add note to docs about potential information exposure via `view_to_component` when using `compatibility=True`.
-
-## [2.0.1] - 2022-10-18
-
-### Fixed
-
-- Ability to use `key=...` parameter on all prefabricated components.
-
-## [2.0.0] - 2022-10-17
-
-### Added
-
-- `use_origin` hook for returning the browser's `location.origin`.
-
-### Changed
-
-- `view_to_component` now returns a `Callable`, instead of directly returning a `Component`. Check the docs for new usage info.
-- `use_mutation` and `use_query` will now log any query failures.
-
-### Fixed
-
-- Allow `use_mutation` to have `refetch=None`, as the docs suggest is possible.
-- `use_query` will now prefetch all fields to prevent `SynchronousOnlyOperation` exceptions.
-- `view_to_component`, `django_css`, and `django_js` type hints will now display like normal functions.
-- IDOM preloader no longer attempts to parse commented out IDOM components.
-- Tests are now fully functional on Windows
-
-## [1.2.0] - 2022-09-19
-
-### Added
-
-- `auth_required` decorator to prevent your components from rendering to unauthenticated users.
-- `use_query` hook for fetching database values.
-- `use_mutation` hook for modifying database values.
-- `view_to_component` utility to convert legacy Django views to IDOM components.
-
-### Changed
-
-- Bumped the minimum IDOM version to 0.40.2
-- Testing suite now uses `playwright` instead of `selenium`
-
-### Fixed
-
-- IDOM preloader is no longer sensitive to whitespace within template tags.
-
-## [1.1.0] - 2022-07-01
-
-### Added
-
-- `django_css` and `django_js` components to defer loading CSS & JS files until needed.
-
-### Changed
-
-- Bumped the minimum IDOM version to 0.39.0
-
-## [1.0.0] - 2022-05-22
-
-### Added
-
-- Django specific hooks! `use_websocket`, `use_scope`, and `use_location` are now available within the `django_idom.hooks` module.
-- Documentation has been placed into a formal docs webpage.
-- Logging for when a component fails to import, or if no components were found within Django.
-
-### Changed
-
-- `idom_component` template tag has been renamed to `component`
-- Bumped the minimum IDOM version to 0.38.0
-
-### Removed
-
-- `websocket` parameter for components has been removed. Functionally, it is replaced with `django_idom.hooks.use_websocket`.
-
-## [0.0.5] - 2022-04-04
-
-### Changed
-
-- Bumped the minimum IDOM version to 0.37.2
-
-### Fixed
-
-- ModuleNotFoundError: No module named `idom.core.proto` caused by IDOM 0.37.2
-
-## [0.0.4] - 2022-03-05
-
-### Changed
-
-- Bumped the minimum IDOM version to 0.37.1
-
-## [0.0.3] - 2022-02-19
-
-### Changed
-
-- Bumped the minimum IDOM version to 0.36.3
-
-## [0.0.2] - 2022-01-30
-
-### Added
-
-- Ability to declare the HTML class of the top-level component `div`
-- `name = ...` parameter to IDOM HTTP paths for use with `django.urls.reverse()`
-- Cache versioning to automatically invalidate old web module files from the cache back-end
-- Automatic pre-population of the IDOM component registry
-- Type hinting for `IdomWebsocket`
-
-### Changed
-
-- Fetching web modules from disk and/or cache is now fully async
-- Static files are now contained within a `django_idom/` parent folder
-- Upgraded IDOM to version `0.36.0`
-- Minimum Django version required is now `4.0`
-- Minimum Python version required is now `3.8`
-
-### Removed
-
-- `IDOM_WEB_MODULES_PATH` has been replaced with Django `include(...)`
-- `IDOM_WS_MAX_RECONNECT_DELAY` has been renamed to `IDOM_WS_MAX_RECONNECT_TIMEOUT`
-- `idom_web_modules` cache back-end has been renamed to `idom`
-
-### Fixed
-
-- Increase test timeout values to prevent false positives
-- Windows compatibility for building Django-IDOM
-
-### Security
-
-- Fixed potential directory traversal attack on the IDOM web modules URL
-
-## [0.0.1] - 2021-08-18
-
-### Added
-
-- Support for IDOM within the Django
-
-[Unreleased]: https://github.com/reactive-python/reactpy-django/compare/5.2.1...HEAD
-[5.2.1]: https://github.com/reactive-python/reactpy-django/compare/5.2.0...5.2.1
-[5.2.0]: https://github.com/reactive-python/reactpy-django/compare/5.1.1...5.2.0
-[5.1.1]: https://github.com/reactive-python/reactpy-django/compare/5.1.0...5.1.1
-[5.1.0]: https://github.com/reactive-python/reactpy-django/compare/5.0.0...5.1.0
-[5.0.0]: https://github.com/reactive-python/reactpy-django/compare/4.0.0...5.0.0
-[4.0.0]: https://github.com/reactive-python/reactpy-django/compare/3.8.1...4.0.0
-[3.8.1]: https://github.com/reactive-python/reactpy-django/compare/3.8.0...3.8.1
-[3.8.0]: https://github.com/reactive-python/reactpy-django/compare/3.7.0...3.8.0
-[3.7.0]: https://github.com/reactive-python/reactpy-django/compare/3.6.0...3.7.0
-[3.6.0]: https://github.com/reactive-python/reactpy-django/compare/3.5.1...3.6.0
-[3.5.1]: https://github.com/reactive-python/reactpy-django/compare/3.5.0...3.5.1
-[3.5.0]: https://github.com/reactive-python/reactpy-django/compare/3.4.0...3.5.0
-[3.4.0]: https://github.com/reactive-python/reactpy-django/compare/3.3.2...3.4.0
-[3.3.2]: https://github.com/reactive-python/reactpy-django/compare/3.3.1...3.3.2
-[3.3.1]: https://github.com/reactive-python/reactpy-django/compare/3.3.0...3.3.1
-[3.3.0]: https://github.com/reactive-python/reactpy-django/compare/3.2.1...3.3.0
-[3.2.1]: https://github.com/reactive-python/reactpy-django/compare/3.2.0...3.2.1
-[3.2.0]: https://github.com/reactive-python/reactpy-django/compare/3.1.0...3.2.0
-[3.1.0]: https://github.com/reactive-python/reactpy-django/compare/3.0.1...3.1.0
-[3.0.1]: https://github.com/reactive-python/reactpy-django/compare/3.0.0-reactpy...3.0.1
-[3.0.0-reactpy]: https://github.com/reactive-python/reactpy-django/compare/3.0.0...3.0.0-reactpy
-[3.0.0]: https://github.com/reactive-python/reactpy-django/compare/2.2.1...3.0.0
-[2.2.1]: https://github.com/reactive-python/reactpy-django/compare/2.2.0...2.2.1
-[2.2.0]: https://github.com/reactive-python/reactpy-django/compare/2.1.0...2.2.0
-[2.1.0]: https://github.com/reactive-python/reactpy-django/compare/2.0.1...2.1.0
-[2.0.1]: https://github.com/reactive-python/reactpy-django/compare/2.0.0...2.0.1
-[2.0.0]: https://github.com/reactive-python/reactpy-django/compare/1.2.0...2.0.0
-[1.2.0]: https://github.com/reactive-python/reactpy-django/compare/1.1.0...1.2.0
-[1.1.0]: https://github.com/reactive-python/reactpy-django/compare/1.0.0...1.1.0
-[1.0.0]: https://github.com/reactive-python/reactpy-django/compare/0.0.5...1.0.0
-[0.0.5]: https://github.com/reactive-python/reactpy-django/compare/0.0.4...0.0.5
-[0.0.4]: https://github.com/reactive-python/reactpy-django/compare/0.0.3...0.0.4
-[0.0.3]: https://github.com/reactive-python/reactpy-django/compare/0.0.2...0.0.3
-[0.0.2]: https://github.com/reactive-python/reactpy-django/compare/0.0.1...0.0.2
-[0.0.1]: https://github.com/reactive-python/reactpy-django/releases/tag/0.0.1

From 902a18bb9244b0de02ef240b919eaad7e42c5c02 Mon Sep 17 00:00:00 2001
From: Mark Bakhit <archiethemonger@gmail.com>
Date: Mon, 14 Sep 2026 16:13:02 -0700
Subject: [PATCH 16/26] Restore full changelog with session state entries

---
 CHANGELOG.md | 614 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 614 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 72bb2f8c..713b238d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,22 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+<!--attr-start-->
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+<!--attr-end-->
+
+<!--
+Using the following categories, list your changes in this order:
+[Added, Changed, Deprecated, Removed, Fixed, Security]
+
+Don't forget to remove deprecated code on each major release!
+-->
+
+<!--changelog-start-->
+
 ## [Unreleased]
 
 ### Added
@@ -9,3 +28,598 @@
     - `settings.py:REACTPY_SESSION_STATE_MAX_AGE` to control how long stale session state is retained.
     - `settings.py:REACTPY_CLEAN_SESSION_STATE` to control whether stale session state is cleaned up during automatic cleanups.
 - Automatically serve ReactPy wheel from Django's static directory when using PyScript.
+
+### Changed
+
+- Use one WebSocket per client webpage.
+- Updated dependencies: `reactpy>=2.0.0, <3.0.0` and `reactpy-router>=3.0.0, <4.0.0`.
+- Updated Python support to 3.11–3.14.
+- Replaced PyScript `<py-script>` tags with standard `<script type="py">` tags.
+- Updated the interface for `reactpy.hooks.use_channel_layer` to be more intuitive.
+    - Arguments now must be provided as keyworded arguments.
+    - The `name` argument has been renamed to `channel`.
+    - The `group_name` argument has been renamed to `group`.
+    - The `group_add` and `group_discard` arguments have been removed for simplicity.
+- To improve performance, `preact` is now used as the default client-side library instead of `react`.
+- ReactPy v2 compatibility! This release aligns `reactpy-django` with ReactPy v2's API.
+    - Refactored `DjangoResolver` to extend `ReactPyResolver` instead of `StarletteResolver`.
+    - Replaced `web.module_from_file`/`web.export` with `reactjs.component_from_file`.
+    - Replaced `reactpy.backend.types` and `reactpy.core.types` imports with `reactpy.types`.
+    - Renamed `Location.pathname` to `Location.path` and `Location.search` to `Location.query_string`.
+
+### Removed
+
+- Removed `reactpy_django.components.pyscript_component`. Use `reactpy.executors.pyscript.pyscript_component` instead.
+- Removed the entire `reactpy_django/pyscript/` package (component template, layout handler, and utilities) in favor of ReactPy core's PyScript executor.
+- Removed `reactpy_django.html.pyscript`. Use `reactpy.html.py_script` instead.
+- Removed `nest_asyncio` dependency.
+
+### Fixed
+
+- Resolved bug where `django_form` events would sometimes not occur.
+
+### [5.2.1] - 2025-01-10
+
+### Changed
+
+- Use the latest version of `@reactpy/client` which includes a fix for needless client-side component re-creation.
+
+### [5.2.0] - 2024-12-29
+
+### Added
+
+- User login/logout features!
+    - `reactpy_django.hooks.use_auth` to provide **persistent** `login` and `logout` functionality to your components.
+    - `settings.py:REACTPY_AUTH_TOKEN_MAX_AGE` to control the maximum seconds before ReactPy's login token expires.
+    - `settings.py:REACTPY_CLEAN_AUTH_TOKENS` to control whether ReactPy should clean up expired authentication tokens during automatic cleanups.
+- Automatically convert Django forms to ReactPy forms via the new `reactpy_django.components.django_form` component!
+- The ReactPy component tree can now be forcibly re-rendered via the new `reactpy_django.hooks.use_rerender` hook.
+
+### Changed
+
+- Refactoring of internal code to improve maintainability. No changes to publicly documented API.
+
+### Fixed
+
+- Fixed bug where pre-rendered components could generate a `SynchronousOnlyOperation` exception if they access a freshly logged out Django user object.
+
+## [5.1.1] - 2024-12-02
+
+### Fixed
+
+- Fixed regression from the previous release where components would sometimes not output debug messages when `settings.py:DEBUG` is enabled.
+
+### Changed
+
+- Set upper limit on ReactPy version to `<2.0.0`.
+- ReactPy web modules are now streamed in chunks.
+- ReactPy web modules are now streamed using asynchronous file reading to improve performance.
+- Performed refactoring to utilize `ruff` as this repository's linter.
+
+## [5.1.0] - 2024-11-24
+
+### Added
+
+- `settings.py:REACTPY_ASYNC_RENDERING` to enable asynchronous rendering of components.
+
+### Changed
+
+- Bumped the minimum ReactPy version to `1.1.0`.
+
+## [5.0.0] - 2024-10-22
+
+### Changed
+
+- Now using ReactPy-Router v1 for URL routing, which comes with a slightly different API than before.
+- Removed dependency on `aiofile`.
+
+### Removed
+
+- Removed the following **deprecated** features:
+    - The `compatibility` argument on `reactpy_django.components.view_to_component`
+    - `reactpy_django.components.view_to_component` **usage as a decorator**
+    - `reactpy_django.decorators.auth_required`
+    - `reactpy_django.REACTPY_WEBSOCKET_PATH`
+    - `settings.py:REACTPY_WEBSOCKET_URL`
+
+## [4.0.0] - 2024-06-22
+
+### Added
+
+- Client-side Python components can now be rendered via the new `{% pyscript_component %}` template tag
+    - You must first call the `{% pyscript_setup %}` template tag to load PyScript dependencies
+- Client-side components can be embedded into existing server-side components via `reactpy_django.components.pyscript_component`.
+- Tired of writing JavaScript? You can now write PyScript code that runs directly within client browser via the `reactpy_django.html.pyscript` element.
+    - This is a viable substitution for most JavaScript code.
+
+### Changed
+
+- New syntax for `use_query` and `use_mutation` hooks. Here's a quick comparison of the changes:
+
+    ```python
+    query = use_query(QueryOptions(thread_sensitive=True), get_items, foo="bar") # Old
+    query = use_query(get_items, {"foo":"bar"}, thread_sensitive=True) # New
+
+    mutation = use_mutation(MutationOptions(thread_sensitive=True), remove_item) # Old
+    mutation = use_mutation(remove_item, thread_sensitive=True) # New
+    ```
+
+### Removed
+
+- `QueryOptions` and `MutationOptions` have been removed. The value contained within these objects are now passed directly into the hook.
+
+### Fixed
+
+- Resolved a bug where Django-ReactPy would not properly detect `settings.py:DEBUG`.
+
+## [3.8.1] - 2024-05-07
+
+### Added
+
+- Python 3.12 compatibility
+
+## [3.8.0] - 2024-02-20
+
+### Added
+
+- Built-in cross-process communication mechanism via the `reactpy_django.hooks.use_channel_layer` hook.
+- Access to the root component's `id` via the `reactpy_django.hooks.use_root_id` hook.
+- More robust control over ReactPy clean up tasks!
+    - `settings.py:REACTPY_CLEAN_INTERVAL` to control how often ReactPy automatically performs cleaning tasks.
+    - `settings.py:REACTPY_CLEAN_SESSIONS` to control whether ReactPy should clean up expired sessions during automatic cleanups.
+    - `settings.py:REACTPY_CLEAN_USER_DATA` to control whether ReactPy should clean up orphaned user data during automatic cleanups.
+    - `python manage.py clean_reactpy` command to manually perform ReactPy clean up tasks.
+
+### Changed
+
+- Simplified code for cascading deletion of user data.
+
+## [3.7.0] - 2024-01-30
+
+### Added
+
+- An "offline component" can now be displayed when the client disconnects from the server.
+- URL router now supports a `*` wildcard to create default routes.
+
+## [3.6.0] - 2024-01-10
+
+### Added
+
+- Built-in Single Page Application (SPA) support!
+    - `reactpy_django.router.django_router` can be used to render your Django application as a SPA.
+- SEO compatible rendering!
+    - `settings.py:REACTPY_PRERENDER` can be set to `True` to make components pre-render by default.
+    - Or, you can enable it on individual components via the template tag: `{% component "..." prerender="True" %}`.
+- New `view_to_iframe` feature!
+    - `reactpy_django.components.view_to_iframe` uses an `<iframe>` to render a Django view.
+    - `reactpy_django.utils.register_iframe` tells ReactPy which views `view_to_iframe` can use.
+- New Django `User` related features!
+    - `reactpy_django.hooks.use_user` can be used to access the current user.
+    - `reactpy_django.hooks.use_user_data` provides a simplified interface for storing user key-value data.
+    - `reactpy_django.decorators.user_passes_test` is inspired by the [equivalent Django decorator](http://docs.djangoproject.com/en/stable/topics/auth/default/#django.contrib.auth.decorators.user_passes_test), but ours works with ReactPy components.
+    - `settings.py:REACTPY_AUTO_RELOGIN` will cause component WebSocket connections to automatically [re-login](https://channels.readthedocs.io/en/latest/topics/authentication.html#how-to-log-a-user-in-out) users that are already authenticated. This is useful to continuously update `last_login` timestamps and refresh the [Django login session](https://docs.djangoproject.com/en/stable/topics/http/sessions/).
+
+### Changed
+
+- Renamed undocumented utility function `ComponentPreloader` to `RootComponentFinder`.
+- It is now recommended to call `as_view()` when using `view_to_component` or `view_to_iframe` with Class Based Views.
+- For thread safety, `thread_sensitive=True` has been enabled in all `sync_to_async` functions where ORM queries are possible.
+- `reactpy_django.hooks.use_mutation` now has a `__call__` method. So rather than writing `my_mutation.execute(...)`, you can now write `my_mutation(...)`.
+
+### Deprecated
+
+- The `compatibility` argument on `reactpy_django.components.view_to_component` is deprecated.
+    - Use `view_to_iframe` as a replacement.
+- `reactpy_django.components.view_to_component` **usage as a decorator** is deprecated.
+    - Check the docs on how to use `view_to_component` as a function instead.
+- `reactpy_django.decorators.auth_required` is deprecated.
+    - Use `reactpy_django.decorators.user_passes_test` instead.
+    - An equivalent to `auth_required`'s default is `@user_passes_test(lambda user: user.is_active)`.
+
+### Fixed
+
+- Fixed a bug where exception stacks would not print on failed component renders.
+
+## [3.5.1] - 2023-09-07
+
+### Added
+
+- Warning W018 (`Suspicious position of 'reactpy_django' in INSTALLED_APPS`) has been added.
+
+### Changed
+
+- The default postprocessor can now disabled by setting `REACTPY_DEFAULT_QUERY_POSTPROCESSOR` to `None`.
+- Massive overhaul of docs styling.
+
+## [3.5.0] - 2023-08-26
+
+### Added
+
+- More customization for reconnection behavior through new settings!
+    - `REACTPY_RECONNECT_INTERVAL`
+    - `REACTPY_RECONNECT_MAX_INTERVAL`
+    - `REACTPY_RECONNECT_MAX_RETRIES`
+    - `REACTPY_RECONNECT_BACKOFF_MULTIPLIER`
+- [ReactPy-Django docs](https://reactive-python.github.io/reactpy-django/) are now version controlled via [mike](https://github.com/jimporter/mike)!
+
+### Changed
+
+- Bumped the minimum ReactPy version to `1.0.2`.
+- Prettier WebSocket URLs for components that do not have sessions.
+- Template tag will now only validate `args`/`kwargs` if `settings.py:DEBUG` is enabled.
+- Bumped the minimum `@reactpy/client` version to `0.3.1`
+- Use TypeScript instead of JavaScript for this repository.
+- Bumped the minimum Django version to `4.2`.
+
+???+ note "Django 4.2+ is required"
+
+    ReactPy-Django will continue bumping minimum Django requirements to versions that increase async support.
+
+    This "latest-only" trend will continue until Django has all async features that ReactPy benefits from. After this point, ReactPy-Django will begin supporting all maintained Django versions.
+
+### Removed
+
+- `settings.py:REACTPY_RECONNECT_MAX` is removed. See the docs for the new `REACTPY_RECONNECT_*` settings.
+
+## [3.4.0] - 2023-08-18
+
+### Added
+
+- **Distributed Computing:** ReactPy components can now optionally be rendered by a completely separate server!
+    - `REACTPY_DEFAULT_HOSTS` setting can round-robin a list of ReactPy rendering hosts.
+    - `host` argument has been added to the `component` template tag to force components to render on a specific host.
+- `reactpy_django.utils.register_component` function can manually register root components.
+    - Useful if you have dedicated ReactPy rendering application(s) that do not use HTML templates.
+
+### Changed
+
+- ReactPy will now provide a warning if your HTTP URLs are not on the same prefix as your WebSockets.
+- Cleaner logging output for auto-detected ReactPy root components.
+
+### Deprecated
+
+- `reactpy_django.REACTPY_WEBSOCKET_PATH` is deprecated. The identical replacement is `REACTPY_WEBSOCKET_ROUTE`.
+- `settings.py:REACTPY_WEBSOCKET_URL` is deprecated. The similar replacement is `REACTPY_URL_PREFIX`.
+
+### Removed
+
+- Warning W007 (`REACTPY_WEBSOCKET_URL doesn't end with a slash`) has been removed. ReactPy now automatically handles slashes.
+- Warning W008 (`REACTPY_WEBSOCKET_URL doesn't start with an alphanumeric character`) has been removed. ReactPy now automatically handles this scenario.
+- Error E009 (`channels is not in settings.py:INSTALLED_APPS`) has been removed. Newer versions of `channels` do not require installation via `INSTALLED_APPS` to receive an ASGI web server.
+
+## [3.3.2] - 2023-08-13
+
+### Added
+
+- ReactPy WebSocket will now decode messages via `orjson` resulting in an ~6% overall performance improvement.
+- Built-in `asyncio` event loops are now patched via `nest_asyncio`, resulting in an ~10% overall performance improvement. This has no performance impact if you are running your web server with `uvloop`.
+
+### Fixed
+
+- Fix bug where `REACTPY_WEBSOCKET_URL` always generates a warning if unset.
+- Fixed bug on Windows where `assert f is self._write_fut` would be raised by `uvicorn` when `REACTPY_BACKHAUL_THREAD = True`.
+- Fixed bug on Windows where rendering behavior would be jittery with `daphne` when `REACTPY_BACKHAUL_THREAD = True`.
+
+## [3.3.1] - 2023-08-08
+
+### Added
+
+- Additional system checks for ReactPy misconfigurations.
+
+### Changed
+
+- `REACTPY_BACKHAUL_THREAD` now defaults to `False`.
+
+## [3.3.0] - 2023-08-05
+
+### Added
+
+- Added system checks for a variety of common ReactPy misconfigurations.
+- `REACTPY_BACKHAUL_THREAD` setting to enable/disable threading behavior.
+
+### Changed
+
+- If using `settings.py:REACTPY_DATABASE`, `reactpy_django.database.Router` must now be registered in `settings.py:DATABASE_ROUTERS`.
+- By default, ReactPy will now use a backhaul thread to increase performance.
+- Minimum Python version required is now `3.9`
+- A thread-safe cache is no longer required.
+
+## [3.2.1] - 2023-06-29
+
+### Added
+
+- Template tag exception details are now rendered on the webpage when `settings.py:DEBUG` is enabled.
+
+### Fixed
+
+- Prevent exceptions within the `component` template tag from causing the whole template to fail to render.
+
+## [3.2.0] - 2023-06-08
+
+### Added
+
+- Added warning if poor system/cache/database performance is detected while in `DEBUG` mode.
+- Added `REACTPY_AUTH_BACKEND` setting to allow for custom authentication backends.
+
+### Changed
+
+- Using `SessionMiddlewareStack` is now optional.
+- Using `AuthMiddlewareStack` is now optional.
+
+## [3.1.0] - 2023-05-06
+
+### Added
+
+- `use_query` now supports async functions.
+- `use_mutation` now supports async functions.
+- `reactpy_django.types.QueryOptions.thread_sensitive` option to customize how sync queries are executed.
+- `reactpy_django.hooks.use_mutation` now accepts `reactpy_django.types.MutationOptions` option to customize how mutations are executed.
+
+### Changed
+
+- The `mutate` argument on `reactpy_django.hooks.use_mutation` has been renamed to `mutation`.
+
+### Fixed
+
+- Fix bug where ReactPy utilizes Django's default cache timeout, which can prematurely expire the component cache.
+
+## [3.0.1] - 2023-04-06
+
+### Changed
+
+- `reactpy-django` database entries are no longer cleaned during Django application startup. Instead, it will occur on webpage loads if `REACTPY_RECONNECT_MAX` seconds has elapsed since the last cleaning.
+
+## [3.0.0-reactpy] - 2023-03-30
+
+### Changed
+
+- `django-idom` has been renamed to `reactpy-django`! Please note that all references to the word `idom` in your code should be changed to `reactpy`. See the docs for more details.
+
+## [3.0.0] - 2023-03-08
+
+???+ note
+
+    This is Django-IDOM's biggest update yet!
+
+    To upgrade from previous version you will need to...
+
+    1. Install `django-idom >= 3.0.0`
+    2. Run `idom rewrite-keys <DIR>` and `idom rewrite-camel-case-props <DIR>` to update your `idom.html.*` calls to the new syntax
+    3. Run `python manage.py migrate` to create the new Django-IDOM database entries
+
+### Added
+
+- The `idom` client will automatically configure itself to debug mode depending on `settings.py:DEBUG`.
+- `use_connection` hook for returning the browser's active `Connection`.
+- `IDOM_CACHE` is now configurable within `settings.py` to whatever cache name you wish.
+
+### Changed
+
+- It is now mandatory to run `manage.py migrate` after installing IDOM.
+- Bumped the minimum IDOM version to 1.0.0. Due to IDOM 1.0.0, `idom.html.*`...
+    - HTML properties can now be `snake_case`. For example `className` now becomes `class_name`.
+    - `key=...` is now declared within the props `dict` (rather than as a `kwarg`).
+- The `component` template tag now supports both positional and keyword arguments.
+- The `component` template tag now supports non-serializable arguments.
+- `IDOM_WS_MAX_RECONNECT_TIMEOUT` setting has been renamed to `IDOM_RECONNECT_MAX`.
+
+### Removed
+
+- `django_idom.hooks.use_websocket` has been removed. The similar replacement is `django_idom.hooks.use_connection`.
+- `django_idom.types.IdomWebsocket` has been removed. The similar replacement is `django_idom.types.Connection`.
+- `settings.py:CACHE['idom']` is no longer used by default. The name of the cache back-end must now be specified with the `IDOM_CACHE` setting.
+
+### Fixed
+
+- `view_to_component` will now retain the contents of a `<head>` tag when rendering.
+- React client is now set to `production` rather than `development`.
+- `use_query` will now utilize `field.related_name` when postprocessing many-to-one relationships.
+
+### Security
+
+- Fixed a potential method of component template tag argument spoofing.
+- Exception information will no longer be displayed on the page, based on the value of `settings.py:DEBUG`.
+
+## [2.2.1] - 2023-01-09
+
+### Fixed
+
+- Fixed bug where `use_query` would not recursively fetch many-to-one relationships.
+- IDOM preloader will now print out the exception stack when failing to import a module.
+
+## [2.2.0] - 2022-12-28
+
+### Added
+
+- Add `options: QueryOptions` parameter to `use_query` to allow for configuration of this hook.
+
+### Changed
+
+- By default, `use_query` will recursively prefetch all many-to-many or many-to-one relationships to prevent `SynchronousOnlyOperation` exceptions.
+
+### Removed
+
+- `django_idom.hooks._fetch_lazy_fields` has been deleted. The equivalent replacement is `django_idom.utils.django_query_postprocessor`.
+
+## [2.1.0] - 2022-11-01
+
+### Changed
+
+- Minimum `channels` version is now `4.0.0`.
+
+### Fixed
+
+- Change type hint on `view_to_component` callable to have `request` argument be optional.
+- Change type hint on `view_to_component` to represent it as a decorator with parenthesis (such as `@view_to_component(compatibility=True)`).
+
+### Security
+
+- Add note to docs about potential information exposure via `view_to_component` when using `compatibility=True`.
+
+## [2.0.1] - 2022-10-18
+
+### Fixed
+
+- Ability to use `key=...` parameter on all prefabricated components.
+
+## [2.0.0] - 2022-10-17
+
+### Added
+
+- `use_origin` hook for returning the browser's `location.origin`.
+
+### Changed
+
+- `view_to_component` now returns a `Callable`, instead of directly returning a `Component`. Check the docs for new usage info.
+- `use_mutation` and `use_query` will now log any query failures.
+
+### Fixed
+
+- Allow `use_mutation` to have `refetch=None`, as the docs suggest is possible.
+- `use_query` will now prefetch all fields to prevent `SynchronousOnlyOperation` exceptions.
+- `view_to_component`, `django_css`, and `django_js` type hints will now display like normal functions.
+- IDOM preloader no longer attempts to parse commented out IDOM components.
+- Tests are now fully functional on Windows
+
+## [1.2.0] - 2022-09-19
+
+### Added
+
+- `auth_required` decorator to prevent your components from rendering to unauthenticated users.
+- `use_query` hook for fetching database values.
+- `use_mutation` hook for modifying database values.
+- `view_to_component` utility to convert legacy Django views to IDOM components.
+
+### Changed
+
+- Bumped the minimum IDOM version to 0.40.2
+- Testing suite now uses `playwright` instead of `selenium`
+
+### Fixed
+
+- IDOM preloader is no longer sensitive to whitespace within template tags.
+
+## [1.1.0] - 2022-07-01
+
+### Added
+
+- `django_css` and `django_js` components to defer loading CSS & JS files until needed.
+
+### Changed
+
+- Bumped the minimum IDOM version to 0.39.0
+
+## [1.0.0] - 2022-05-22
+
+### Added
+
+- Django specific hooks! `use_websocket`, `use_scope`, and `use_location` are now available within the `django_idom.hooks` module.
+- Documentation has been placed into a formal docs webpage.
+- Logging for when a component fails to import, or if no components were found within Django.
+
+### Changed
+
+- `idom_component` template tag has been renamed to `component`
+- Bumped the minimum IDOM version to 0.38.0
+
+### Removed
+
+- `websocket` parameter for components has been removed. Functionally, it is replaced with `django_idom.hooks.use_websocket`.
+
+## [0.0.5] - 2022-04-04
+
+### Changed
+
+- Bumped the minimum IDOM version to 0.37.2
+
+### Fixed
+
+- ModuleNotFoundError: No module named `idom.core.proto` caused by IDOM 0.37.2
+
+## [0.0.4] - 2022-03-05
+
+### Changed
+
+- Bumped the minimum IDOM version to 0.37.1
+
+## [0.0.3] - 2022-02-19
+
+### Changed
+
+- Bumped the minimum IDOM version to 0.36.3
+
+## [0.0.2] - 2022-01-30
+
+### Added
+
+- Ability to declare the HTML class of the top-level component `div`
+- `name = ...` parameter to IDOM HTTP paths for use with `django.urls.reverse()`
+- Cache versioning to automatically invalidate old web module files from the cache back-end
+- Automatic pre-population of the IDOM component registry
+- Type hinting for `IdomWebsocket`
+
+### Changed
+
+- Fetching web modules from disk and/or cache is now fully async
+- Static files are now contained within a `django_idom/` parent folder
+- Upgraded IDOM to version `0.36.0`
+- Minimum Django version required is now `4.0`
+- Minimum Python version required is now `3.8`
+
+### Removed
+
+- `IDOM_WEB_MODULES_PATH` has been replaced with Django `include(...)`
+- `IDOM_WS_MAX_RECONNECT_DELAY` has been renamed to `IDOM_WS_MAX_RECONNECT_TIMEOUT`
+- `idom_web_modules` cache back-end has been renamed to `idom`
+
+### Fixed
+
+- Increase test timeout values to prevent false positives
+- Windows compatibility for building Django-IDOM
+
+### Security
+
+- Fixed potential directory traversal attack on the IDOM web modules URL
+
+## [0.0.1] - 2021-08-18
+
+### Added
+
+- Support for IDOM within the Django
+
+[Unreleased]: https://github.com/reactive-python/reactpy-django/compare/5.2.1...HEAD
+[5.2.1]: https://github.com/reactive-python/reactpy-django/compare/5.2.0...5.2.1
+[5.2.0]: https://github.com/reactive-python/reactpy-django/compare/5.1.1...5.2.0
+[5.1.1]: https://github.com/reactive-python/reactpy-django/compare/5.1.0...5.1.1
+[5.1.0]: https://github.com/reactive-python/reactpy-django/compare/5.0.0...5.1.0
+[5.0.0]: https://github.com/reactive-python/reactpy-django/compare/4.0.0...5.0.0
+[4.0.0]: https://github.com/reactive-python/reactpy-django/compare/3.8.1...4.0.0
+[3.8.1]: https://github.com/reactive-python/reactpy-django/compare/3.8.0...3.8.1
+[3.8.0]: https://github.com/reactive-python/reactpy-django/compare/3.7.0...3.8.0
+[3.7.0]: https://github.com/reactive-python/reactpy-django/compare/3.6.0...3.7.0
+[3.6.0]: https://github.com/reactive-python/reactpy-django/compare/3.5.1...3.6.0
+[3.5.1]: https://github.com/reactive-python/reactpy-django/compare/3.5.0...3.5.1
+[3.5.0]: https://github.com/reactive-python/reactpy-django/compare/3.4.0...3.5.0
+[3.4.0]: https://github.com/reactive-python/reactpy-django/compare/3.3.2...3.4.0
+[3.3.2]: https://github.com/reactive-python/reactpy-django/compare/3.3.1...3.3.2
+[3.3.1]: https://github.com/reactive-python/reactpy-django/compare/3.3.0...3.3.1
+[3.3.0]: https://github.com/reactive-python/reactpy-django/compare/3.2.1...3.3.0
+[3.2.1]: https://github.com/reactive-python/reactpy-django/compare/3.2.0...3.2.1
+[3.2.0]: https://github.com/reactive-python/reactpy-django/compare/3.1.0...3.2.0
+[3.1.0]: https://github.com/reactive-python/reactpy-django/compare/3.0.1...3.1.0
+[3.0.1]: https://github.com/reactive-python/reactpy-django/compare/3.0.0-reactpy...3.0.1
+[3.0.0-reactpy]: https://github.com/reactive-python/reactpy-django/compare/3.0.0...3.0.0-reactpy
+[3.0.0]: https://github.com/reactive-python/reactpy-django/compare/2.2.1...3.0.0
+[2.2.1]: https://github.com/reactive-python/reactpy-django/compare/2.2.0...2.2.1
+[2.2.0]: https://github.com/reactive-python/reactpy-django/compare/2.1.0...2.2.0
+[2.1.0]: https://github.com/reactive-python/reactpy-django/compare/2.0.1...2.1.0
+[2.0.1]: https://github.com/reactive-python/reactpy-django/compare/2.0.0...2.0.1
+[2.0.0]: https://github.com/reactive-python/reactpy-django/compare/1.2.0...2.0.0
+[1.2.0]: https://github.com/reactive-python/reactpy-django/compare/1.1.0...1.2.0
+[1.1.0]: https://github.com/reactive-python/reactpy-django/compare/1.0.0...1.1.0
+[1.0.0]: https://github.com/reactive-python/reactpy-django/compare/0.0.5...1.0.0
+[0.0.5]: https://github.com/reactive-python/reactpy-django/compare/0.0.4...0.0.5
+[0.0.4]: https://github.com/reactive-python/reactpy-django/compare/0.0.3...0.0.4
+[0.0.3]: https://github.com/reactive-python/reactpy-django/compare/0.0.2...0.0.3
+[0.0.2]: https://github.com/reactive-python/reactpy-django/compare/0.0.1...0.0.2
+[0.0.1]: https://github.com/reactive-python/reactpy-django/releases/tag/0.0.1

From 036cf6c1dc01a4d8c2a0e7480e2404d9e64b4900 Mon Sep 17 00:00:00 2001
From: Mark Bakhit <archiethemonger@gmail.com>
Date: Mon, 14 Sep 2026 16:17:00 -0700
Subject: [PATCH 17/26] Add ruff noqa for mutable Meta class attributes

---
 src/reactpy_django/models.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/src/reactpy_django/models.py b/src/reactpy_django/models.py
index 637a7be0..fd264f4b 100644
--- a/src/reactpy_django/models.py
+++ b/src/reactpy_django/models.py
@@ -1,3 +1,4 @@
+# ruff: noqa: RUF012
 from datetime import timedelta
 
 from django.contrib.auth import get_user_model

From 8a106e15d64872252ae7cbee8e7b09e55e941bcf Mon Sep 17 00:00:00 2001
From: Mark Bakhit <archiethemonger@gmail.com>
Date: Mon, 14 Sep 2026 16:33:31 -0700
Subject: [PATCH 18/26] Fix use_session_state race conditions and scope
 handling

---
 src/reactpy_django/hooks.py | 541 ++----------------------------------
 1 file changed, 29 insertions(+), 512 deletions(-)

diff --git a/src/reactpy_django/hooks.py b/src/reactpy_django/hooks.py
index e9274aec..359b7034 100644
--- a/src/reactpy_django/hooks.py
+++ b/src/reactpy_django/hooks.py
@@ -1,337 +1,3 @@
-from __future__ import annotations
-
-import asyncio
-import logging
-from collections import defaultdict
-from typing import (
-    TYPE_CHECKING,
-    Any,
-    Callable,
-    Union,
-    cast,
-)
-from uuid import uuid4
-
-import dill
-import orjson
-from channels import DEFAULT_CHANNEL_LAYER
-from channels import auth as channels_auth
-from channels.layers import InMemoryChannelLayer, get_channel_layer
-from reactpy import use_async_effect, use_callback, use_effect, use_memo, use_ref, use_state
-from reactpy import use_connection as _use_connection
-from reactpy import use_location as _use_location
-from reactpy import use_scope as _use_scope
-
-from reactpy_django.exceptions import UserNotFoundError
-from reactpy_django.types import (
-    AsyncMessageReceiver,
-    AsyncMessageSender,
-    AsyncPostprocessor,
-    ConnectionType,
-    FuncParams,
-    Inferred,
-    Mutation,
-    Query,
-    SyncPostprocessor,
-    UseAuthTuple,
-    UserData,
-)
-from reactpy_django.utils import django_query_postprocessor, ensure_async, generate_obj_name, get_pk
-
-if TYPE_CHECKING:
-    from collections.abc import Awaitable, Sequence
-
-    from channels_redis.core import RedisChannelLayer
-    from django.contrib.auth.models import AbstractUser
-    from reactpy.types import Location
-
-
-_logger = logging.getLogger(__name__)
-_REFETCH_CALLBACKS: defaultdict[Callable[..., Any], set[Callable[[], None]]] = defaultdict(set)
-
-
-def use_location() -> Location:
-    """Get the current route as a `Location` object"""
-    return _use_location()
-
-
-def use_origin() -> str | None:
-    """Get the current origin as a string. If the browser did not send an origin header,
-    this will be None."""
-    scope = _use_scope()
-    try:
-        if scope["type"] == "websocket":
-            return next(
-                (header[1].decode("utf-8") for header in scope["headers"] if header[0] == b"origin"),
-                None,
-            )
-        if scope["type"] == "http":
-            host = next(header[1].decode("utf-8") for header in scope["headers"] if header[0] == b"host")
-            return f"{scope['scheme']}://{host}" if host else None
-    except Exception:
-        _logger.info("Failed to get origin")
-    return None
-
-
-def use_scope() -> dict[str, Any]:
-    """Get the current ASGI scope dictionary"""
-    scope = _use_scope()
-
-    if isinstance(scope, dict):
-        return cast("dict[str, Any]", scope)
-
-    msg = f"Expected scope to be a dict, got {type(scope)}"
-    raise TypeError(msg)
-
-
-def use_connection() -> ConnectionType:
-    """Get the current `Connection` object"""
-    return _use_connection()
-
-
-def use_query(
-    query: Callable[FuncParams, Awaitable[Inferred]] | Callable[FuncParams, Inferred],
-    kwargs: dict[str, Any] | None = None,
-    *,
-    thread_sensitive: bool = True,
-    postprocessor: (AsyncPostprocessor | SyncPostprocessor | None) = django_query_postprocessor,
-    postprocessor_kwargs: dict[str, Any] | None = None,
-) -> Query[Inferred]:
-    """This hook is used to execute functions in the background and return the result, \
-        typically to read data the Django ORM.
-
-    Args:
-        query: A function that executes a query and returns some data.
-
-    Kwargs:
-        kwargs: Keyword arguments to passed into the `query` function.
-        thread_sensitive: Whether to run the query in thread sensitive mode. \
-            This setting only applies to sync functions, and is turned on by default \
-            due to Django ORM limitations.
-        postprocessor: A callable that processes the query `data` before it is returned. \
-            The first argument of postprocessor function must be the query `data`. All \
-            proceeding arguments are optional `postprocessor_kwargs`. This postprocessor \
-            function must return the modified `data`. \
-            \
-            If unset, `REACTPY_DEFAULT_QUERY_POSTPROCESSOR` is used. By default, this \
-            is used to prevent Django's lazy query execution and supports `many_to_many` \
-            and `many_to_one` as `postprocessor_kwargs`.
-        postprocessor_kwargs: Keyworded arguments passed into the `postprocessor` function.
-
-    Returns:
-         An object containing `loading`/`#!python error` states, your `data` (if the query \
-         has successfully executed), and a `refetch` callable that can be used to re-run the query.
-    """
-
-    should_execute, set_should_execute = use_state(True)
-    data, set_data = use_state(cast("Inferred", None))
-    loading, set_loading = use_state(True)
-    error, set_error = use_state(cast("Union[Exception, None]", None))
-    query_ref = use_ref(query)
-    kwargs = kwargs or {}
-    postprocessor_kwargs = postprocessor_kwargs or {}
-
-    if query_ref.current is not query:
-        msg = f"Query function changed from {query_ref.current} to {query}."
-        raise ValueError(msg)
-
-    async def execute_query() -> None:
-        """The main running function for `use_query`"""
-        try:
-            # Run the query
-            query_async = cast(
-                "Callable[..., Awaitable[Inferred]]", ensure_async(query, thread_sensitive=thread_sensitive)
-            )
-            new_data = await query_async(**kwargs)
-
-            # Run the postprocessor
-            if postprocessor:
-                async_postprocessor = cast(
-                    "Callable[..., Awaitable[Any]]", ensure_async(postprocessor, thread_sensitive=thread_sensitive)
-                )
-                new_data = await async_postprocessor(new_data, **postprocessor_kwargs)
-
-        # Log any errors and set the error state
-        except Exception as e:
-            set_loading(False)
-            set_error(e)
-            _logger.exception("Failed to execute query '%s'", generate_obj_name(query))
-            return
-
-        # Query was successful
-        else:
-            set_data(new_data)
-            set_loading(False)
-            set_error(None)
-
-    @use_async_effect(dependencies=[should_execute])
-    async def schedule_query() -> None:
-        """Execute a query when needed."""
-        # Make sure we don't re-execute the query unless we're told to
-        if not should_execute:
-            return
-
-        # Execute the query
-        await execute_query()
-        set_should_execute(False)
-
-    @use_callback
-    def refetch() -> None:
-        """Callable provided to the user, used to re-execute the query"""
-        set_should_execute(True)
-        set_loading(True)
-        set_error(None)
-
-    @use_effect(dependencies=[])
-    def register_refetch_callback() -> Callable[[], None]:
-        """Track the refetch callback so we can re-execute the query"""
-        # By tracking callbacks globally, any usage of the query function will be re-run
-        # if the user has told a mutation to refetch it.
-        _REFETCH_CALLBACKS[query].add(refetch)
-        return lambda: _REFETCH_CALLBACKS[query].remove(refetch)
-
-    # Return Query user API
-    return Query(data, loading, error, refetch)
-
-
-def use_mutation(
-    mutation: (Callable[FuncParams, bool | None] | Callable[FuncParams, Awaitable[bool | None]]),
-    *,
-    thread_sensitive: bool = True,
-    refetch: Callable[..., Any] | Sequence[Callable[..., Any]] | None = None,
-) -> Mutation[FuncParams]:
-    """This hook is used to modify data in the background, typically to create/update/delete \
-    data from the Django ORM.
-
-    Mutation functions can `return False` to prevent executing your `refetch` function. All \
-    other returns are ignored. Mutation functions can be sync or async.
-
-    Args:
-        mutation: A callable that performs Django ORM create, update, or delete \
-            functionality. If this function returns `False`, then your `refetch` \
-            function will not be used.
-
-    Kwargs:
-        thread_sensitive: Whether to run the mutation in thread sensitive mode. \
-            This setting only applies to sync functions, and is turned on by default \
-            due to Django ORM limitations.
-        refetch:  A query function (the function you provide to your `use_query` \
-            hook) or a sequence of query functions that need a `refetch` if the \
-            mutation succeeds. This is useful for refreshing data after a mutation \
-            has been performed.
-
-    Returns:
-        An object containing `#!python loading`/`#!python error` states, and a \
-        `#!python reset` callable that will set `#!python loading`/`#!python error` \
-        states to defaults. This object can be called to run the query.
-    """
-
-    loading, set_loading = use_state(False)
-    error, set_error = use_state(cast("Union[Exception, None]", None))
-    async_task_refs = use_ref(set())
-
-    # The main "running" function for `use_mutation`
-    async def execute_mutation(*exec_args: FuncParams.args, **exec_kwargs: FuncParams.kwargs) -> None:
-        # Run the mutation
-        try:
-            should_refetch = await ensure_async(mutation, thread_sensitive=thread_sensitive)(*exec_args, **exec_kwargs)
-
-        # Log any errors and set the error state
-        except Exception as e:
-            set_loading(False)
-            set_error(e)
-            _logger.exception("Failed to execute mutation: %s", generate_obj_name(mutation))
-
-        # Mutation was successful
-        else:
-            set_loading(False)
-            set_error(None)
-
-            # `refetch` will execute unless explicitly told not to
-            # or if `refetch` was not defined.
-            if should_refetch is not False and refetch:
-                for query in (refetch,) if callable(refetch) else refetch:
-                    for callback in _REFETCH_CALLBACKS.get(query) or ():
-                        callback()
-
-    # Schedule the mutation to be run when needed
-    def schedule_mutation(*exec_args: FuncParams.args, **exec_kwargs: FuncParams.kwargs) -> None:
-        # Set the loading state.
-        # It's okay to re-execute the mutation if we're told to. If desired,
-        # The user could use the `loading` state to prevent double execution.
-        set_loading(True)
-
-        # Execute the mutation in the background
-        task = asyncio.ensure_future(execute_mutation(*exec_args, **exec_kwargs))
-
-        # Add the task to a set to prevent it from being garbage collected
-        async_task_refs.current.add(task)
-        task.add_done_callback(async_task_refs.current.remove)
-
-    # Used when the user has told us to reset this mutation
-    @use_callback
-    def reset() -> None:
-        set_loading(False)
-        set_error(None)
-
-    # Return mutation user API
-    return Mutation(schedule_mutation, loading, error, reset)
-
-
-def use_user() -> AbstractUser:
-    """Get the current `User` object from either the WebSocket or HTTP request."""
-    connection = use_connection()
-    user = connection.scope.get("user") or getattr(connection.carrier, "user", None)
-    if user is None:
-        msg = "No user is available in the current environment."
-        raise UserNotFoundError(msg)
-    return user
-
-
-def use_user_data(
-    default_data: (dict[str, Callable[[], Any] | Callable[[], Awaitable[Any]] | Any] | None) = None,
-    save_default_data: bool = False,
-) -> UserData:
-    """Get or set user data stored within the REACTPY_DATABASE.
-
-    Kwargs:
-        default_data: A dictionary containing `{key: default_value}` pairs. \
-            For computationally intensive defaults, your `default_value` \
-            can be sync or async functions that return the value to set.
-        save_default_data: If True, `default_data` values will automatically be stored \
-            within the database if they do not exist.
-    """
-    from reactpy_django.models import UserDataModel
-
-    user = use_user()
-
-    async def _set_user_data(data: dict):
-        if not isinstance(data, dict):
-            msg = f"Expected dict while setting user data, got {type(data)}"
-            raise TypeError(msg)
-        if user.is_anonymous:
-            msg = "AnonymousUser cannot have user data."
-            raise ValueError(msg)
-
-        pk = get_pk(user)
-        model, _ = await UserDataModel.objects.aget_or_create(user_pk=pk)
-        model.data = orjson.dumps(data)
-        await model.asave()
-
-    query: Query[dict | None] = use_query(
-        _get_user_data,
-        kwargs={
-            "user": user,
-            "default_data": default_data,
-            "save_default_data": save_default_data,
-        },
-        postprocessor=None,
-    )
-    mutation = use_mutation(_set_user_data, refetch=_get_user_data)
-
-    return UserData(query, mutation)
-
-
 def use_session_state(
     default: Any,
     key: str,
@@ -381,22 +47,32 @@ def use_session_state(
     # debounced in the background.
     state, set_state = use_state(cast("Any", default))
     loaded = use_ref(False)
+    # True once the user has written a value; prevents the async DB load from clobbering
+    # a concurrent user update.
+    user_set = use_ref(False)
+    # Latest value written by the user (kept in a ref so cleanup always flushes it).
     latest = use_ref(default)
-    timer = use_ref(None)
+    # The currently scheduled debounced flush task; retained to prevent GC.
+    flush_task = use_ref(None)
+    # Keep the current scope/key in refs so the unmount cleanup (which captures the first
+    # render's closure) always flushes to the correct scope/key.
+    scope_id_ref = use_ref(scope_id)
+    key_ref = use_ref(key)
 
     @use_async_effect(dependencies=[key, scope_id])
     async def load_state() -> None:
         """Load the persisted value from the database once on mount."""
-        data = await _get_session_state(scope_id, key, default)
-        latest.current = data
-        set_state(data)
+        data = await _get_session_state(scope_id_ref.current, key_ref.current, default)
+        if not user_set.current:
+            latest.current = data
+            set_state(data)
         loaded.current = True
-        if save_default and data == default:
-            await _set_session_state(scope_id, key, data)
+        if save_default and not user_set.current and data == default:
+            await _set_session_state(scope_id_ref.current, key_ref.current, data)
 
     async def flush() -> None:
         """Persist the latest value to the database."""
-        await _set_session_state(scope_id, key, latest.current)
+        await _set_session_state(scope_id_ref.current, key_ref.current, latest.current)
 
     async def debounced_flush() -> None:
         """Wait for the sync interval and then persist the latest value."""
@@ -404,17 +80,19 @@ async def debounced_flush() -> None:
             await asyncio.sleep(config.REACTPY_SESSION_STATE_SYNC_INTERVAL)
             await flush()
         finally:
-            timer.current = None
+            if flush_task.current is asyncio.current_task():
+                flush_task.current = None
 
     def schedule_flush() -> None:
         """Debounce database writes so rapid state changes coalesce into one write."""
-        if timer.current is not None and not timer.current.done():
-            timer.current.cancel()
-        timer.current = asyncio.create_task(debounced_flush())
+        if flush_task.current is not None and not flush_task.current.done():
+            flush_task.current.cancel()
+        flush_task.current = asyncio.create_task(debounced_flush())
 
     @use_callback
     def set_state_and_persist(value: Any) -> None:
         """Update the in-memory state and schedule a debounced database write."""
+        user_set.current = True
         latest.current = value
         set_state(value)
         schedule_flush()
@@ -428,125 +106,15 @@ async def flush_on_unmount() -> Callable[[], None]:
         """
 
         def _cleanup() -> None:
-            if timer.current is not None and not timer.current.done():
-                timer.current.cancel()
-            asyncio.create_task(flush())
+            if flush_task.current is not None and not flush_task.current.done():
+                flush_task.current.cancel()
+            flush_task.current = asyncio.create_task(flush())
 
         return _cleanup
 
     return state, set_state_and_persist
 
 
-def use_channel_layer(
-    *,
-    channel: str | None = None,
-    group: str | None = None,
-    receiver: AsyncMessageReceiver | None = None,
-    layer: str = DEFAULT_CHANNEL_LAYER,
-) -> AsyncMessageSender:
-    """
-    Subscribe to a Django Channels layer to send/receive messages.
-
-    Args:
-        channel:  The name of the channel this hook will send/receive messages on. If `group` is \
-        defined and `channel` is `None`, ReactPy will automatically generate a unique channel name.
-
-    Kwargs:
-        group: If configured, the `channel` is added to a `group` and any messages sent by `AsyncMessageSender` \
-            is broadcasted to all channels within the `group`.
-        receiver: An async function that receives a `message: dict` from a channel.
-        layer: The Django Channels layer to use. This layer must be defined in `settings.py:CHANNEL_LAYERS`.
-
-    Returns:
-        An async callable that can send messages to the channel(s). This callable accepts a single \
-        argument, `message: dict`, which is the data sent to the channel or group of channels.
-    """
-    channel_layer: InMemoryChannelLayer | RedisChannelLayer = get_channel_layer(layer)  # type: ignore
-    channel_name = use_memo(lambda: str(channel or uuid4()))
-
-    if not (channel or group):
-        msg = "You must either define a `channel` or `group` for this hook."
-        raise ValueError(msg)
-
-    if not channel_layer:
-        msg = (
-            f"Channel layer '{layer}' is not available. Are you sure you"
-            " configured settings.py:CHANNEL_LAYERS properly?"
-        )
-        raise ValueError(msg)
-
-    # Add/remove a group's channel during component mount/dismount respectively.
-    @use_async_effect(dependencies=[])
-    async def group_manager():
-        if group:
-            group_name: str = group
-            await channel_layer.group_add(group_name, channel_name)
-            return lambda: asyncio.run(channel_layer.group_discard(group_name, channel_name))
-        return None
-
-    # Listen for messages on the channel using the provided `receiver` function.
-    @use_async_effect
-    async def message_receiver():
-        if not receiver:
-            return
-
-        while True:
-            message = await channel_layer.receive(channel_name)
-            await receiver(message)
-
-    # User interface for sending messages to the channel
-    async def message_sender(message: dict):
-        if group:
-            await channel_layer.group_send(group, message)
-        else:
-            await channel_layer.send(channel_name, message)
-
-    return message_sender
-
-
-def use_root_id() -> str:
-    """Get the root element's ID. This value is guaranteed to be unique. Current versions of \
-        ReactPy-Django return a `uuid4` string."""
-    scope = use_scope()
-
-    return scope["reactpy"]["id"]
-
-
-def use_rerender() -> Callable[[], None]:
-    """Provides a callable that can re-render the entire component tree without disconnecting the websocket."""
-    scope = use_scope()
-
-    def rerender():
-        scope["reactpy"]["rerender"]()
-
-    return rerender
-
-
-def use_auth() -> UseAuthTuple:
-    """Provides the ability to login/logout a user using Django's authentication framework."""
-    from reactpy_django import config
-
-    scope = use_scope()
-    trigger_rerender = use_rerender()
-
-    async def login(user: AbstractUser, rerender: bool = True) -> None:
-        await channels_auth.login(scope, user, backend=config.REACTPY_AUTH_BACKEND)  # type: ignore[reportArgumentType]
-        session_save_method = getattr(scope["session"], "asave", scope["session"].save)
-        await ensure_async(session_save_method)()
-        await scope["reactpy"]["synchronize_auth"]()
-
-        if rerender:
-            trigger_rerender()
-
-    async def logout(rerender: bool = True) -> None:
-        await channels_auth.logout(scope)  # type: ignore[reportArgumentType]
-
-        if rerender:
-            trigger_rerender()
-
-    return UseAuthTuple(login=login, logout=logout)
-
-
 def _resolve_session_state_scope_id() -> str:
     """Resolve the stable identity used to scope persistent session state.
 
@@ -560,60 +128,9 @@ def _resolve_session_state_scope_id() -> str:
     root_id = use_root_id()
 
     if config.REACTPY_SESSION_STATE_MODE == "user":
-        user = use_user()
-        if not user.is_anonymous:
+        connection = use_connection()
+        user = connection.scope.get("user")
+        if user is not None and not user.is_anonymous:
             return f"user:{get_pk(user)}"
 
     return f"tab:{root_id}"
-
-
-async def _get_session_state(scope_id: str, key: str, default: Any) -> Any:
-    """Load a persisted session state value from the database, or return `default`."""
-    from reactpy_django.models import SessionStateModel
-
-    model = await SessionStateModel.objects.filter(scope_id=scope_id, key=key).afirst()
-    if model is None or model.data is None:
-        return default
-    return dill.loads(model.data)
-
-
-async def _set_session_state(scope_id: str, key: str, data: Any) -> None:
-    """Persist a session state value to the database."""
-    from reactpy_django.models import SessionStateModel
-
-    model, _ = await SessionStateModel.objects.aget_or_create(scope_id=scope_id, key=key)
-    model.data = dill.dumps(data)
-    await model.asave()
-
-
-async def _get_user_data(user: AbstractUser, default_data: dict | None, save_default_data: bool) -> dict | None:
-    """The mutation function for `use_user_data`"""
-    from reactpy_django.models import UserDataModel
-
-    if not user or user.is_anonymous:
-        return None
-
-    pk = get_pk(user)
-    model, _ = await UserDataModel.objects.aget_or_create(user_pk=pk)
-    data = orjson.loads(model.data) if model.data else {}
-
-    if not isinstance(data, dict):
-        msg = f"Expected dict while loading user data, got {type(data)}"
-        raise TypeError(msg)
-
-    # Set default values, if needed
-    if default_data:
-        changed = False
-        for key, value in default_data.items():
-            if key not in data:
-                new_value: Any = value
-                if callable(value):
-                    new_value = await ensure_async(value)()
-                data[key] = new_value
-                changed = True
-        if changed:
-            model.data = orjson.dumps(data)
-            if save_default_data:
-                await model.asave()
-
-    return data

From 161cdc0cac565857a4690be9d68f45719aeab2e3 Mon Sep 17 00:00:00 2001
From: Mark Bakhit <archiethemonger@gmail.com>
Date: Mon, 14 Sep 2026 16:35:55 -0700
Subject: [PATCH 19/26] Restore full hooks.py with fixed use_session_state

---
 src/reactpy_django/hooks.py | 496 ++++++++++++++++++++++++++++++++++++
 1 file changed, 496 insertions(+)

diff --git a/src/reactpy_django/hooks.py b/src/reactpy_django/hooks.py
index 359b7034..212bdaab 100644
--- a/src/reactpy_django/hooks.py
+++ b/src/reactpy_django/hooks.py
@@ -1,3 +1,337 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections import defaultdict
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Union,
+    cast,
+)
+from uuid import uuid4
+
+import dill
+import orjson
+from channels import DEFAULT_CHANNEL_LAYER
+from channels import auth as channels_auth
+from channels.layers import InMemoryChannelLayer, get_channel_layer
+from reactpy import use_async_effect, use_callback, use_effect, use_memo, use_ref, use_state
+from reactpy import use_connection as _use_connection
+from reactpy import use_location as _use_location
+from reactpy import use_scope as _use_scope
+
+from reactpy_django.exceptions import UserNotFoundError
+from reactpy_django.types import (
+    AsyncMessageReceiver,
+    AsyncMessageSender,
+    AsyncPostprocessor,
+    ConnectionType,
+    FuncParams,
+    Inferred,
+    Mutation,
+    Query,
+    SyncPostprocessor,
+    UseAuthTuple,
+    UserData,
+)
+from reactpy_django.utils import django_query_postprocessor, ensure_async, generate_obj_name, get_pk
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Sequence
+
+    from channels_redis.core import RedisChannelLayer
+    from django.contrib.auth.models import AbstractUser
+    from reactpy.types import Location
+
+
+_logger = logging.getLogger(__name__)
+_REFETCH_CALLBACKS: defaultdict[Callable[..., Any], set[Callable[[], None]]] = defaultdict(set)
+
+
+def use_location() -> Location:
+    """Get the current route as a `Location` object"""
+    return _use_location()
+
+
+def use_origin() -> str | None:
+    """Get the current origin as a string. If the browser did not send an origin header,
+    this will be None."""
+    scope = _use_scope()
+    try:
+        if scope["type"] == "websocket":
+            return next(
+                (header[1].decode("utf-8") for header in scope["headers"] if header[0] == b"origin"),
+                None,
+            )
+        if scope["type"] == "http":
+            host = next(header[1].decode("utf-8") for header in scope["headers"] if header[0] == b"host")
+            return f"{scope['scheme']}://{host}" if host else None
+    except Exception:
+        _logger.info("Failed to get origin")
+    return None
+
+
+def use_scope() -> dict[str, Any]:
+    """Get the current ASGI scope dictionary"""
+    scope = _use_scope()
+
+    if isinstance(scope, dict):
+        return cast("dict[str, Any]", scope)
+
+    msg = f"Expected scope to be a dict, got {type(scope)}"
+    raise TypeError(msg)
+
+
+def use_connection() -> ConnectionType:
+    """Get the current `Connection` object"""
+    return _use_connection()
+
+
+def use_query(
+    query: Callable[FuncParams, Awaitable[Inferred]] | Callable[FuncParams, Inferred],
+    kwargs: dict[str, Any] | None = None,
+    *,
+    thread_sensitive: bool = True,
+    postprocessor: (AsyncPostprocessor | SyncPostprocessor | None) = django_query_postprocessor,
+    postprocessor_kwargs: dict[str, Any] | None = None,
+) -> Query[Inferred]:
+    """This hook is used to execute functions in the background and return the result, \
+        typically to read data the Django ORM.
+
+    Args:
+        query: A function that executes a query and returns some data.
+
+    Kwargs:
+        kwargs: Keyword arguments to passed into the `query` function.
+        thread_sensitive: Whether to run the query in thread sensitive mode. \
+            This setting only applies to sync functions, and is turned on by default \
+            due to Django ORM limitations.
+        postprocessor: A callable that processes the query `data` before it is returned. \
+            The first argument of postprocessor function must be the query `data`. All \
+            proceeding arguments are optional `postprocessor_kwargs`. This postprocessor \
+            function must return the modified `data`. \
+            \
+            If unset, `REACTPY_DEFAULT_QUERY_POSTPROCESSOR` is used. By default, this \
+            is used to prevent Django's lazy query execution and supports `many_to_many` \
+            and `many_to_one` as `postprocessor_kwargs`.
+        postprocessor_kwargs: Keyworded arguments passed into the `postprocessor` function.
+
+    Returns:
+         An object containing `loading`/`#!python error` states, your `data` (if the query \
+         has successfully executed), and a `refetch` callable that can be used to re-run the query.
+    """
+
+    should_execute, set_should_execute = use_state(True)
+    data, set_data = use_state(cast("Inferred", None))
+    loading, set_loading = use_state(True)
+    error, set_error = use_state(cast("Union[Exception, None]", None))
+    query_ref = use_ref(query)
+    kwargs = kwargs or {}
+    postprocessor_kwargs = postprocessor_kwargs or {}
+
+    if query_ref.current is not query:
+        msg = f"Query function changed from {query_ref.current} to {query}."
+        raise ValueError(msg)
+
+    async def execute_query() -> None:
+        """The main running function for `use_query`"""
+        try:
+            # Run the query
+            query_async = cast(
+                "Callable[..., Awaitable[Inferred]]", ensure_async(query, thread_sensitive=thread_sensitive)
+            )
+            new_data = await query_async(**kwargs)
+
+            # Run the postprocessor
+            if postprocessor:
+                async_postprocessor = cast(
+                    "Callable[..., Awaitable[Any]]", ensure_async(postprocessor, thread_sensitive=thread_sensitive)
+                )
+                new_data = await async_postprocessor(new_data, **postprocessor_kwargs)
+
+        # Log any errors and set the error state
+        except Exception as e:
+            set_loading(False)
+            set_error(e)
+            _logger.exception("Failed to execute query '%s'", generate_obj_name(query))
+            return
+
+        # Query was successful
+        else:
+            set_data(new_data)
+            set_loading(False)
+            set_error(None)
+
+    @use_async_effect(dependencies=[should_execute])
+    async def schedule_query() -> None:
+        """Execute a query when needed."""
+        # Make sure we don't re-execute the query unless we're told to
+        if not should_execute:
+            return
+
+        # Execute the query
+        await execute_query()
+        set_should_execute(False)
+
+    @use_callback
+    def refetch() -> None:
+        """Callable provided to the user, used to re-execute the query"""
+        set_should_execute(True)
+        set_loading(True)
+        set_error(None)
+
+    @use_effect(dependencies=[])
+    def register_refetch_callback() -> Callable[[], None]:
+        """Track the refetch callback so we can re-execute the query"""
+        # By tracking callbacks globally, any usage of the query function will be re-run
+        # if the user has told a mutation to refetch it.
+        _REFETCH_CALLBACKS[query].add(refetch)
+        return lambda: _REFETCH_CALLBACKS[query].remove(refetch)
+
+    # Return Query user API
+    return Query(data, loading, error, refetch)
+
+
+def use_mutation(
+    mutation: (Callable[FuncParams, bool | None] | Callable[FuncParams, Awaitable[bool | None]]),
+    *,
+    thread_sensitive: bool = True,
+    refetch: Callable[..., Any] | Sequence[Callable[..., Any]] | None = None,
+) -> Mutation[FuncParams]:
+    """This hook is used to modify data in the background, typically to create/update/delete \
+    data from the Django ORM.
+
+    Mutation functions can `return False` to prevent executing your `refetch` function. All \
+    other returns are ignored. Mutation functions can be sync or async.
+
+    Args:
+        mutation: A callable that performs Django ORM create, update, or delete \
+            functionality. If this function returns `False`, then your `refetch` \
+            function will not be used.
+
+    Kwargs:
+        thread_sensitive: Whether to run the mutation in thread sensitive mode. \
+            This setting only applies to sync functions, and is turned on by default \
+            due to Django ORM limitations.
+        refetch:  A query function (the function you provide to your `use_query` \
+            hook) or a sequence of query functions that need a `refetch` if the \
+            mutation succeeds. This is useful for refreshing data after a mutation \
+            has been performed.
+
+    Returns:
+        An object containing `#!python loading`/`#!python error` states, and a \
+        `#!python reset` callable that will set `#!python loading`/`#!python error` \
+        states to defaults. This object can be called to run the query.
+    """
+
+    loading, set_loading = use_state(False)
+    error, set_error = use_state(cast("Union[Exception, None]", None))
+    async_task_refs = use_ref(set())
+
+    # The main "running" function for `use_mutation`
+    async def execute_mutation(*exec_args: FuncParams.args, **exec_kwargs: FuncParams.kwargs) -> None:
+        # Run the mutation
+        try:
+            should_refetch = await ensure_async(mutation, thread_sensitive=thread_sensitive)(*exec_args, **exec_kwargs)
+
+        # Log any errors and set the error state
+        except Exception as e:
+            set_loading(False)
+            set_error(e)
+            _logger.exception("Failed to execute mutation: %s", generate_obj_name(mutation))
+
+        # Mutation was successful
+        else:
+            set_loading(False)
+            set_error(None)
+
+            # `refetch` will execute unless explicitly told not to
+            # or if `refetch` was not defined.
+            if should_refetch is not False and refetch:
+                for query in (refetch,) if callable(refetch) else refetch:
+                    for callback in _REFETCH_CALLBACKS.get(query) or ():
+                        callback()
+
+    # Schedule the mutation to be run when needed
+    def schedule_mutation(*exec_args: FuncParams.args, **exec_kwargs: FuncParams.kwargs) -> None:
+        # Set the loading state.
+        # It's okay to re-execute the mutation if we're told to. If desired,
+        # The user could use the `loading` state to prevent double execution.
+        set_loading(True)
+
+        # Execute the mutation in the background
+        task = asyncio.ensure_future(execute_mutation(*exec_args, **exec_kwargs))
+
+        # Add the task to a set to prevent it from being garbage collected
+        async_task_refs.current.add(task)
+        task.add_done_callback(async_task_refs.current.remove)
+
+    # Used when the user has told us to reset this mutation
+    @use_callback
+    def reset() -> None:
+        set_loading(False)
+        set_error(None)
+
+    # Return mutation user API
+    return Mutation(schedule_mutation, loading, error, reset)
+
+
+def use_user() -> AbstractUser:
+    """Get the current `User` object from either the WebSocket or HTTP request."""
+    connection = use_connection()
+    user = connection.scope.get("user") or getattr(connection.carrier, "user", None)
+    if user is None:
+        msg = "No user is available in the current environment."
+        raise UserNotFoundError(msg)
+    return user
+
+
+def use_user_data(
+    default_data: (dict[str, Callable[[], Any] | Callable[[], Awaitable[Any]] | Any] | None) = None,
+    save_default_data: bool = False,
+) -> UserData:
+    """Get or set user data stored within the REACTPY_DATABASE.
+
+    Kwargs:
+        default_data: A dictionary containing `{key: default_value}` pairs. \
+            For computationally intensive defaults, your `default_value` \
+            can be sync or async functions that return the value to set.
+        save_default_data: If True, `default_data` values will automatically be stored \
+            within the database if they do not exist.
+    """
+    from reactpy_django.models import UserDataModel
+
+    user = use_user()
+
+    async def _set_user_data(data: dict):
+        if not isinstance(data, dict):
+            msg = f"Expected dict while setting user data, got {type(data)}"
+            raise TypeError(msg)
+        if user.is_anonymous:
+            msg = "AnonymousUser cannot have user data."
+            raise ValueError(msg)
+
+        pk = get_pk(user)
+        model, _ = await UserDataModel.objects.aget_or_create(user_pk=pk)
+        model.data = orjson.dumps(data)
+        await model.asave()
+
+    query: Query[dict | None] = use_query(
+        _get_user_data,
+        kwargs={
+            "user": user,
+            "default_data": default_data,
+            "save_default_data": save_default_data,
+        },
+        postprocessor=None,
+    )
+    mutation = use_mutation(_set_user_data, refetch=_get_user_data)
+
+    return UserData(query, mutation)
+
+
 def use_session_state(
     default: Any,
     key: str,
@@ -115,6 +449,116 @@ def _cleanup() -> None:
     return state, set_state_and_persist
 
 
+def use_channel_layer(
+    *,
+    channel: str | None = None,
+    group: str | None = None,
+    receiver: AsyncMessageReceiver | None = None,
+    layer: str = DEFAULT_CHANNEL_LAYER,
+) -> AsyncMessageSender:
+    """
+    Subscribe to a Django Channels layer to send/receive messages.
+
+    Args:
+        channel:  The name of the channel this hook will send/receive messages on. If `group` is \
+        defined and `channel` is `None`, ReactPy will automatically generate a unique channel name.
+
+    Kwargs:
+        group: If configured, the `channel` is added to a `group` and any messages sent by `AsyncMessageSender` \
+            is broadcasted to all channels within the `group`.
+        receiver: An async function that receives a `message: dict` from a channel.
+        layer: The Django Channels layer to use. This layer must be defined in `settings.py:CHANNEL_LAYERS`.
+
+    Returns:
+        An async callable that can send messages to the channel(s). This callable accepts a single \
+        argument, `message: dict`, which is the data sent to the channel or group of channels.
+    """
+    channel_layer: InMemoryChannelLayer | RedisChannelLayer = get_channel_layer(layer)  # type: ignore
+    channel_name = use_memo(lambda: str(channel or uuid4()))
+
+    if not (channel or group):
+        msg = "You must either define a `channel` or `group` for this hook."
+        raise ValueError(msg)
+
+    if not channel_layer:
+        msg = (
+            f"Channel layer '{layer}' is not available. Are you sure you"
+            " configured settings.py:CHANNEL_LAYERS properly?"
+        )
+        raise ValueError(msg)
+
+    # Add/remove a group's channel during component mount/dismount respectively.
+    @use_async_effect(dependencies=[])
+    async def group_manager():
+        if group:
+            group_name: str = group
+            await channel_layer.group_add(group_name, channel_name)
+            return lambda: asyncio.run(channel_layer.group_discard(group_name, channel_name))
+        return None
+
+    # Listen for messages on the channel using the provided `receiver` function.
+    @use_async_effect
+    async def message_receiver():
+        if not receiver:
+            return
+
+        while True:
+            message = await channel_layer.receive(channel_name)
+            await receiver(message)
+
+    # User interface for sending messages to the channel
+    async def message_sender(message: dict):
+        if group:
+            await channel_layer.group_send(group, message)
+        else:
+            await channel_layer.send(channel_name, message)
+
+    return message_sender
+
+
+def use_root_id() -> str:
+    """Get the root element's ID. This value is guaranteed to be unique. Current versions of \
+        ReactPy-Django return a `uuid4` string."""
+    scope = use_scope()
+
+    return scope["reactpy"]["id"]
+
+
+def use_rerender() -> Callable[[], None]:
+    """Provides a callable that can re-render the entire component tree without disconnecting the websocket."""
+    scope = use_scope()
+
+    def rerender():
+        scope["reactpy"]["rerender"]()
+
+    return rerender
+
+
+def use_auth() -> UseAuthTuple:
+    """Provides the ability to login/logout a user using Django's authentication framework."""
+    from reactpy_django import config
+
+    scope = use_scope()
+    trigger_rerender = use_rerender()
+
+    async def login(user: AbstractUser, rerender: bool = True) -> None:
+        await channels_auth.login(scope, user, backend=config.REACTPY_AUTH_BACKEND)  # type: ignore[reportArgumentType]
+        session_save_method = getattr(scope["session"], "asave", scope["session"].save)
+        await ensure_async(session_save_method)()
+        await scope["reactpy"]["synchronize_auth"]()
+
+        if rerender:
+            trigger_rerender()
+
+    async def logout(rerender: bool = True) -> None:
+        await channels_auth.logout(scope)  # type: ignore[reportArgumentType]
+
+        if rerender:
+            trigger_rerender()
+
+    return UseAuthTuple(login=login, logout=logout)
+
+
 def _resolve_session_state_scope_id() -> str:
     """Resolve the stable identity used to scope persistent session state.
 
@@ -134,3 +578,55 @@ def _resolve_session_state_scope_id() -> str:
             return f"user:{get_pk(user)}"
 
     return f"tab:{root_id}"
+
+
+async def _get_session_state(scope_id: str, key: str, default: Any) -> Any:
+    """Load a persisted session state value from the database, or return `default`."""
+    from reactpy_django.models import SessionStateModel
+
+    model = await SessionStateModel.objects.filter(scope_id=scope_id, key=key).afirst()
+    if model is None or model.data is None:
+        return default
+    return dill.loads(model.data)
+
+
+async def _set_session_state(scope_id: str, key: str, data: Any) -> None:
+    """Persist a session state value to the database."""
+    from reactpy_django.models import SessionStateModel
+
+    model, _ = await SessionStateModel.objects.aget_or_create(scope_id=scope_id, key=key)
+    model.data = dill.dumps(data)
+    await model.asave()
+
+
+async def _get_user_data(user: AbstractUser, default_data: dict | None, save_default_data: bool) -> dict | None:
+    """The mutation function for `use_user_data`"""
+    from reactpy_django.models import UserDataModel
+
+    if not user or user.is_anonymous:
+        return None
+
+    pk = get_pk(user)
+    model, _ = await UserDataModel.objects.aget_or_create(user_pk=pk)
+    data = orjson.loads(model.data) if model.data else {}
+
+    if not isinstance(data, dict):
+        msg = f"Expected dict while loading user data, got {type(data)}"
+        raise TypeError(msg)
+
+    # Set default values, if needed
+    if default_data:
+        changed = False
+        for key, value in default_data.items():
+            if key not in data:
+                new_value: Any = value
+                if callable(value):
+                    new_value = await ensure_async(value)()
+                data[key] = new_value
+                changed = True
+        if changed:
+            model.data = orjson.dumps(data)
+            if save_default_data:
+                await model.asave()
+
+    return data

From 788ee98d5ba9171d335dacc8f8ef97b0e5425f9b Mon Sep 17 00:00:00 2001
From: Mark Bakhit <archiethemonger@gmail.com>
Date: Mon, 14 Sep 2026 16:37:07 -0700
Subject: [PATCH 20/26] Fix session state test to await async helpers and
 correct cleanup timing

---
 tests/test_app/tests/test_database.py | 21 ++++++++++++---------
 1 file changed, 12 insertions(+), 9 deletions(-)

diff --git a/tests/test_app/tests/test_database.py b/tests/test_app/tests/test_database.py
index 01f5d80c..0c6183b1 100644
--- a/tests/test_app/tests/test_database.py
+++ b/tests/test_app/tests/test_database.py
@@ -1,4 +1,5 @@
 # ruff: noqa: RUF012
+import asyncio
 from time import sleep
 from typing import Any
 from uuid import uuid4
@@ -72,27 +73,29 @@ def test_session_state_roundtrip_and_cleanup(self):
             key = "my_state"
 
             # No state exists yet, so the default is returned
-            assert _get_session_state(scope_id, key, default="default") == "default"
+            assert asyncio.run(_get_session_state(scope_id, key, default="default")) == "default"
 
             # Persist some state and read it back
             state = {"count": 1, "items": [1, 2, 3]}
-            _set_session_state(scope_id, key, state)
+            asyncio.run(_set_session_state(scope_id, key, state))
             assert SessionStateModel.objects.filter(scope_id=scope_id, key=key).count() == 1
-            assert _get_session_state(scope_id, key, default="default") == state
+            assert asyncio.run(_get_session_state(scope_id, key, default="default")) == state
 
             # Persisting the same scope+key updates the existing row (no duplicate)
-            _set_session_state(scope_id, key, {"count": 2})
+            asyncio.run(_set_session_state(scope_id, key, {"count": 2}))
             assert SessionStateModel.objects.filter(scope_id=scope_id, key=key).count() == 1
-            assert _get_session_state(scope_id, key, default="default") == {"count": 2}
+            assert asyncio.run(_get_session_state(scope_id, key, default="default")) == {"count": 2}
 
-            # Untouched state is considered stale and gets cleaned up
+            # Let the first state row age past the expiry threshold
+            sleep(config.REACTPY_SESSION_STATE_MAX_AGE)
+
+            # A freshly-written (non-expired) entry should survive cleaning
             fresh_scope = f"tab:{uuid4()}"
-            _set_session_state(fresh_scope, "other", "keep-me")
+            asyncio.run(_set_session_state(fresh_scope, "other", "keep-me"))
             assert SessionStateModel.objects.count() == 2
-            sleep(config.REACTPY_SESSION_STATE_MAX_AGE)
             tasks.clean_session_state()
             assert SessionStateModel.objects.count() == 1
-            assert _get_session_state(fresh_scope, "other", default="default") == "keep-me"
+            assert asyncio.run(_get_session_state(fresh_scope, "other", default="default")) == "keep-me"
         finally:
             config.REACTPY_CLEAN_SESSION_STATE = initial_clean_session_state
             config.REACTPY_SESSION_STATE_MAX_AGE = initial_session_state_max_age

From c5cfe0c28b18dc90355a2808506f358c0eb1270c Mon Sep 17 00:00:00 2001
From: Mark Bakhit <archiethemonger@gmail.com>
Date: Mon, 14 Sep 2026 16:43:58 -0700
Subject: [PATCH 21/26] Type the flush_task ref to satisfy pyright

---
 src/reactpy_django/hooks.py | 564 +-----------------------------------
 1 file changed, 1 insertion(+), 563 deletions(-)

diff --git a/src/reactpy_django/hooks.py b/src/reactpy_django/hooks.py
index 212bdaab..bc14dac6 100644
--- a/src/reactpy_django/hooks.py
+++ b/src/reactpy_django/hooks.py
@@ -1,382 +1,3 @@
-from __future__ import annotations
-
-import asyncio
-import logging
-from collections import defaultdict
-from typing import (
-    TYPE_CHECKING,
-    Any,
-    Callable,
-    Union,
-    cast,
-)
-from uuid import uuid4
-
-import dill
-import orjson
-from channels import DEFAULT_CHANNEL_LAYER
-from channels import auth as channels_auth
-from channels.layers import InMemoryChannelLayer, get_channel_layer
-from reactpy import use_async_effect, use_callback, use_effect, use_memo, use_ref, use_state
-from reactpy import use_connection as _use_connection
-from reactpy import use_location as _use_location
-from reactpy import use_scope as _use_scope
-
-from reactpy_django.exceptions import UserNotFoundError
-from reactpy_django.types import (
-    AsyncMessageReceiver,
-    AsyncMessageSender,
-    AsyncPostprocessor,
-    ConnectionType,
-    FuncParams,
-    Inferred,
-    Mutation,
-    Query,
-    SyncPostprocessor,
-    UseAuthTuple,
-    UserData,
-)
-from reactpy_django.utils import django_query_postprocessor, ensure_async, generate_obj_name, get_pk
-
-if TYPE_CHECKING:
-    from collections.abc import Awaitable, Sequence
-
-    from channels_redis.core import RedisChannelLayer
-    from django.contrib.auth.models import AbstractUser
-    from reactpy.types import Location
-
-
-_logger = logging.getLogger(__name__)
-_REFETCH_CALLBACKS: defaultdict[Callable[..., Any], set[Callable[[], None]]] = defaultdict(set)
-
-
-def use_location() -> Location:
-    """Get the current route as a `Location` object"""
-    return _use_location()
-
-
-def use_origin() -> str | None:
-    """Get the current origin as a string. If the browser did not send an origin header,
-    this will be None."""
-    scope = _use_scope()
-    try:
-        if scope["type"] == "websocket":
-            return next(
-                (header[1].decode("utf-8") for header in scope["headers"] if header[0] == b"origin"),
-                None,
-            )
-        if scope["type"] == "http":
-            host = next(header[1].decode("utf-8") for header in scope["headers"] if header[0] == b"host")
-            return f"{scope['scheme']}://{host}" if host else None
-    except Exception:
-        _logger.info("Failed to get origin")
-    return None
-
-
-def use_scope() -> dict[str, Any]:
-    """Get the current ASGI scope dictionary"""
-    scope = _use_scope()
-
-    if isinstance(scope, dict):
-        return cast("dict[str, Any]", scope)
-
-    msg = f"Expected scope to be a dict, got {type(scope)}"
-    raise TypeError(msg)
-
-
-def use_connection() -> ConnectionType:
-    """Get the current `Connection` object"""
-    return _use_connection()
-
-
-def use_query(
-    query: Callable[FuncParams, Awaitable[Inferred]] | Callable[FuncParams, Inferred],
-    kwargs: dict[str, Any] | None = None,
-    *,
-    thread_sensitive: bool = True,
-    postprocessor: (AsyncPostprocessor | SyncPostprocessor | None) = django_query_postprocessor,
-    postprocessor_kwargs: dict[str, Any] | None = None,
-) -> Query[Inferred]:
-    """This hook is used to execute functions in the background and return the result, \
-        typically to read data the Django ORM.
-
-    Args:
-        query: A function that executes a query and returns some data.
-
-    Kwargs:
-        kwargs: Keyword arguments to passed into the `query` function.
-        thread_sensitive: Whether to run the query in thread sensitive mode. \
-            This setting only applies to sync functions, and is turned on by default \
-            due to Django ORM limitations.
-        postprocessor: A callable that processes the query `data` before it is returned. \
-            The first argument of postprocessor function must be the query `data`. All \
-            proceeding arguments are optional `postprocessor_kwargs`. This postprocessor \
-            function must return the modified `data`. \
-            \
-            If unset, `REACTPY_DEFAULT_QUERY_POSTPROCESSOR` is used. By default, this \
-            is used to prevent Django's lazy query execution and supports `many_to_many` \
-            and `many_to_one` as `postprocessor_kwargs`.
-        postprocessor_kwargs: Keyworded arguments passed into the `postprocessor` function.
-
-    Returns:
-         An object containing `loading`/`#!python error` states, your `data` (if the query \
-         has successfully executed), and a `refetch` callable that can be used to re-run the query.
-    """
-
-    should_execute, set_should_execute = use_state(True)
-    data, set_data = use_state(cast("Inferred", None))
-    loading, set_loading = use_state(True)
-    error, set_error = use_state(cast("Union[Exception, None]", None))
-    query_ref = use_ref(query)
-    kwargs = kwargs or {}
-    postprocessor_kwargs = postprocessor_kwargs or {}
-
-    if query_ref.current is not query:
-        msg = f"Query function changed from {query_ref.current} to {query}."
-        raise ValueError(msg)
-
-    async def execute_query() -> None:
-        """The main running function for `use_query`"""
-        try:
-            # Run the query
-            query_async = cast(
-                "Callable[..., Awaitable[Inferred]]", ensure_async(query, thread_sensitive=thread_sensitive)
-            )
-            new_data = await query_async(**kwargs)
-
-            # Run the postprocessor
-            if postprocessor:
-                async_postprocessor = cast(
-                    "Callable[..., Awaitable[Any]]", ensure_async(postprocessor, thread_sensitive=thread_sensitive)
-                )
-                new_data = await async_postprocessor(new_data, **postprocessor_kwargs)
-
-        # Log any errors and set the error state
-        except Exception as e:
-            set_loading(False)
-            set_error(e)
-            _logger.exception("Failed to execute query '%s'", generate_obj_name(query))
-            return
-
-        # Query was successful
-        else:
-            set_data(new_data)
-            set_loading(False)
-            set_error(None)
-
-    @use_async_effect(dependencies=[should_execute])
-    async def schedule_query() -> None:
-        """Execute a query when needed."""
-        # Make sure we don't re-execute the query unless we're told to
-        if not should_execute:
-            return
-
-        # Execute the query
-        await execute_query()
-        set_should_execute(False)
-
-    @use_callback
-    def refetch() -> None:
-        """Callable provided to the user, used to re-execute the query"""
-        set_should_execute(True)
-        set_loading(True)
-        set_error(None)
-
-    @use_effect(dependencies=[])
-    def register_refetch_callback() -> Callable[[], None]:
-        """Track the refetch callback so we can re-execute the query"""
-        # By tracking callbacks globally, any usage of the query function will be re-run
-        # if the user has told a mutation to refetch it.
-        _REFETCH_CALLBACKS[query].add(refetch)
-        return lambda: _REFETCH_CALLBACKS[query].remove(refetch)
-
-    # Return Query user API
-    return Query(data, loading, error, refetch)
-
-
-def use_mutation(
-    mutation: (Callable[FuncParams, bool | None] | Callable[FuncParams, Awaitable[bool | None]]),
-    *,
-    thread_sensitive: bool = True,
-    refetch: Callable[..., Any] | Sequence[Callable[..., Any]] | None = None,
-) -> Mutation[FuncParams]:
-    """This hook is used to modify data in the background, typically to create/update/delete \
-    data from the Django ORM.
-
-    Mutation functions can `return False` to prevent executing your `refetch` function. All \
-    other returns are ignored. Mutation functions can be sync or async.
-
-    Args:
-        mutation: A callable that performs Django ORM create, update, or delete \
-            functionality. If this function returns `False`, then your `refetch` \
-            function will not be used.
-
-    Kwargs:
-        thread_sensitive: Whether to run the mutation in thread sensitive mode. \
-            This setting only applies to sync functions, and is turned on by default \
-            due to Django ORM limitations.
-        refetch:  A query function (the function you provide to your `use_query` \
-            hook) or a sequence of query functions that need a `refetch` if the \
-            mutation succeeds. This is useful for refreshing data after a mutation \
-            has been performed.
-
-    Returns:
-        An object containing `#!python loading`/`#!python error` states, and a \
-        `#!python reset` callable that will set `#!python loading`/`#!python error` \
-        states to defaults. This object can be called to run the query.
-    """
-
-    loading, set_loading = use_state(False)
-    error, set_error = use_state(cast("Union[Exception, None]", None))
-    async_task_refs = use_ref(set())
-
-    # The main "running" function for `use_mutation`
-    async def execute_mutation(*exec_args: FuncParams.args, **exec_kwargs: FuncParams.kwargs) -> None:
-        # Run the mutation
-        try:
-            should_refetch = await ensure_async(mutation, thread_sensitive=thread_sensitive)(*exec_args, **exec_kwargs)
-
-        # Log any errors and set the error state
-        except Exception as e:
-            set_loading(False)
-            set_error(e)
-            _logger.exception("Failed to execute mutation: %s", generate_obj_name(mutation))
-
-        # Mutation was successful
-        else:
-            set_loading(False)
-            set_error(None)
-
-            # `refetch` will execute unless explicitly told not to
-            # or if `refetch` was not defined.
-            if should_refetch is not False and refetch:
-                for query in (refetch,) if callable(refetch) else refetch:
-                    for callback in _REFETCH_CALLBACKS.get(query) or ():
-                        callback()
-
-    # Schedule the mutation to be run when needed
-    def schedule_mutation(*exec_args: FuncParams.args, **exec_kwargs: FuncParams.kwargs) -> None:
-        # Set the loading state.
-        # It's okay to re-execute the mutation if we're told to. If desired,
-        # The user could use the `loading` state to prevent double execution.
-        set_loading(True)
-
-        # Execute the mutation in the background
-        task = asyncio.ensure_future(execute_mutation(*exec_args, **exec_kwargs))
-
-        # Add the task to a set to prevent it from being garbage collected
-        async_task_refs.current.add(task)
-        task.add_done_callback(async_task_refs.current.remove)
-
-    # Used when the user has told us to reset this mutation
-    @use_callback
-    def reset() -> None:
-        set_loading(False)
-        set_error(None)
-
-    # Return mutation user API
-    return Mutation(schedule_mutation, loading, error, reset)
-
-
-def use_user() -> AbstractUser:
-    """Get the current `User` object from either the WebSocket or HTTP request."""
-    connection = use_connection()
-    user = connection.scope.get("user") or getattr(connection.carrier, "user", None)
-    if user is None:
-        msg = "No user is available in the current environment."
-        raise UserNotFoundError(msg)
-    return user
-
-
-def use_user_data(
-    default_data: (dict[str, Callable[[], Any] | Callable[[], Awaitable[Any]] | Any] | None) = None,
-    save_default_data: bool = False,
-) -> UserData:
-    """Get or set user data stored within the REACTPY_DATABASE.
-
-    Kwargs:
-        default_data: A dictionary containing `{key: default_value}` pairs. \
-            For computationally intensive defaults, your `default_value` \
-            can be sync or async functions that return the value to set.
-        save_default_data: If True, `default_data` values will automatically be stored \
-            within the database if they do not exist.
-    """
-    from reactpy_django.models import UserDataModel
-
-    user = use_user()
-
-    async def _set_user_data(data: dict):
-        if not isinstance(data, dict):
-            msg = f"Expected dict while setting user data, got {type(data)}"
-            raise TypeError(msg)
-        if user.is_anonymous:
-            msg = "AnonymousUser cannot have user data."
-            raise ValueError(msg)
-
-        pk = get_pk(user)
-        model, _ = await UserDataModel.objects.aget_or_create(user_pk=pk)
-        model.data = orjson.dumps(data)
-        await model.asave()
-
-    query: Query[dict | None] = use_query(
-        _get_user_data,
-        kwargs={
-            "user": user,
-            "default_data": default_data,
-            "save_default_data": save_default_data,
-        },
-        postprocessor=None,
-    )
-    mutation = use_mutation(_set_user_data, refetch=_get_user_data)
-
-    return UserData(query, mutation)
-
-
-def use_session_state(
-    default: Any,
-    key: str,
-    *,
-    save_default: bool = False,
-) -> tuple[Any, Callable[[Any], None]]:
-    """Persist state across WebSocket reconnects (and, optionally, page reloads).
-
-    This hook stores its value in the ReactPy database so that it can be restored after a
-    WebSocket reconnect, which would otherwise reset all in-memory component state. It is
-    more robust than in-memory state because it survives multi-process deployments and
-    round-robin load balancing across multiple hosts.
-
-    The state's scope is controlled by the ``REACTPY_SESSION_STATE_MODE`` setting:
-
-    - ``"tab"`` (default): state is scoped to the rendered component (a per-tab, per-component
-      token that is stable across reconnects). Works for anonymous users without requiring
-      ``django.contrib.sessions``.
-    - ``"user"``: state is scoped to the authenticated user, falling back to a per-tab token
-      for anonymous users.
-
-    Args:
-        default: The value to use when no persisted state exists.
-        key: A unique identifier for this state slot within the computed scope. Multiple
-            ``use_session_state`` hooks in the same component must use distinct keys.
-
-    Kwargs:
-        save_default: If ``True``, the ``default`` value will be persisted when no state
-            already exists in the database.
-
-    Returns:
-        A tuple of ``(state, set_state)``. ``state`` is the current value (loaded from the
-        database, or ``default`` if none exists). ``set_state`` updates the in-memory value
-        immediately and schedules a debounced database write so that frequently-changing
-        values do not hammer the database.
-
-    Note:
-        Only serializable data may be stored. Values are serialized with ``dill``, so most
-        common Python objects are supported, but objects holding un-picklable resources
-        (e.g. open file handles or network connections) will fail.
-    """
-    from reactpy_django import config
-
-    scope_id = _resolve_session_state_scope_id()
-
     # In-memory reactive state. This keeps the UI responsive while database writes are
     # debounced in the background.
     state, set_state = use_state(cast("Any", default))
@@ -387,7 +8,7 @@ def use_session_state(
     # Latest value written by the user (kept in a ref so cleanup always flushes it).
     latest = use_ref(default)
     # The currently scheduled debounced flush task; retained to prevent GC.
-    flush_task = use_ref(None)
+    flush_task = use_ref(cast("asyncio.Task[None] | None", None))
     # Keep the current scope/key in refs so the unmount cleanup (which captures the first
     # render's closure) always flushes to the correct scope/key.
     scope_id_ref = use_ref(scope_id)
@@ -447,186 +68,3 @@ def _cleanup() -> None:
         return _cleanup
 
     return state, set_state_and_persist
-
-
-def use_channel_layer(
-    *,
-    channel: str | None = None,
-    group: str | None = None,
-    receiver: AsyncMessageReceiver | None = None,
-    layer: str = DEFAULT_CHANNEL_LAYER,
-) -> AsyncMessageSender:
-    """
-    Subscribe to a Django Channels layer to send/receive messages.
-
-    Args:
-        channel:  The name of the channel this hook will send/receive messages on. If `group` is \
-        defined and `channel` is `None`, ReactPy will automatically generate a unique channel name.
-
-    Kwargs:
-        group: If configured, the `channel` is added to a `group` and any messages sent by `AsyncMessageSender` \
-            is broadcasted to all channels within the `group`.
-        receiver: An async function that receives a `message: dict` from a channel.
-        layer: The Django Channels layer to use. This layer must be defined in `settings.py:CHANNEL_LAYERS`.
-
-    Returns:
-        An async callable that can send messages to the channel(s). This callable accepts a single \
-        argument, `message: dict`, which is the data sent to the channel or group of channels.
-    """
-    channel_layer: InMemoryChannelLayer | RedisChannelLayer = get_channel_layer(layer)  # type: ignore
-    channel_name = use_memo(lambda: str(channel or uuid4()))
-
-    if not (channel or group):
-        msg = "You must either define a `channel` or `group` for this hook."
-        raise ValueError(msg)
-
-    if not channel_layer:
-        msg = (
-            f"Channel layer '{layer}' is not available. Are you sure you"
-            " configured settings.py:CHANNEL_LAYERS properly?"
-        )
-        raise ValueError(msg)
-
-    # Add/remove a group's channel during component mount/dismount respectively.
-    @use_async_effect(dependencies=[])
-    async def group_manager():
-        if group:
-            group_name: str = group
-            await channel_layer.group_add(group_name, channel_name)
-            return lambda: asyncio.run(channel_layer.group_discard(group_name, channel_name))
-        return None
-
-    # Listen for messages on the channel using the provided `receiver` function.
-    @use_async_effect
-    async def message_receiver():
-        if not receiver:
-            return
-
-        while True:
-            message = await channel_layer.receive(channel_name)
-            await receiver(message)
-
-    # User interface for sending messages to the channel
-    async def message_sender(message: dict):
-        if group:
-            await channel_layer.group_send(group, message)
-        else:
-            await channel_layer.send(channel_name, message)
-
-    return message_sender
-
-
-def use_root_id() -> str:
-    """Get the root element's ID. This value is guaranteed to be unique. Current versions of \
-        ReactPy-Django return a `uuid4` string."""
-    scope = use_scope()
-
-    return scope["reactpy"]["id"]
-
-
-def use_rerender() -> Callable[[], None]:
-    """Provides a callable that can re-render the entire component tree without disconnecting the websocket."""
-    scope = use_scope()
-
-    def rerender():
-        scope["reactpy"]["rerender"]()
-
-    return rerender
-
-
-def use_auth() -> UseAuthTuple:
-    """Provides the ability to login/logout a user using Django's authentication framework."""
-    from reactpy_django import config
-
-    scope = use_scope()
-    trigger_rerender = use_rerender()
-
-    async def login(user: AbstractUser, rerender: bool = True) -> None:
-        await channels_auth.login(scope, user, backend=config.REACTPY_AUTH_BACKEND)  # type: ignore[reportArgumentType]
-        session_save_method = getattr(scope["session"], "asave", scope["session"].save)
-        await ensure_async(session_save_method)()
-        await scope["reactpy"]["synchronize_auth"]()
-
-        if rerender:
-            trigger_rerender()
-
-    async def logout(rerender: bool = True) -> None:
-        await channels_auth.logout(scope)  # type: ignore[reportArgumentType]
-
-        if rerender:
-            trigger_rerender()
-
-    return UseAuthTuple(login=login, logout=logout)
-
-
-def _resolve_session_state_scope_id() -> str:
-    """Resolve the stable identity used to scope persistent session state.
-
-    In ``"tab"`` mode this is the rendered component's UUID (stable across reconnects).
-    In ``"user"`` mode this is the authenticated user's primary key, falling back to a
-    per-tab token for anonymous users so that unauthenticated visitors still get isolated,
-    persistent state.
-    """
-    from reactpy_django import config
-
-    root_id = use_root_id()
-
-    if config.REACTPY_SESSION_STATE_MODE == "user":
-        connection = use_connection()
-        user = connection.scope.get("user")
-        if user is not None and not user.is_anonymous:
-            return f"user:{get_pk(user)}"
-
-    return f"tab:{root_id}"
-
-
-async def _get_session_state(scope_id: str, key: str, default: Any) -> Any:
-    """Load a persisted session state value from the database, or return `default`."""
-    from reactpy_django.models import SessionStateModel
-
-    model = await SessionStateModel.objects.filter(scope_id=scope_id, key=key).afirst()
-    if model is None or model.data is None:
-        return default
-    return dill.loads(model.data)
-
-
-async def _set_session_state(scope_id: str, key: str, data: Any) -> None:
-    """Persist a session state value to the database."""
-    from reactpy_django.models import SessionStateModel
-
-    model, _ = await SessionStateModel.objects.aget_or_create(scope_id=scope_id, key=key)
-    model.data = dill.dumps(data)
-    await model.asave()
-
-
-async def _get_user_data(user: AbstractUser, default_data: dict | None, save_default_data: bool) -> dict | None:
-    """The mutation function for `use_user_data`"""
-    from reactpy_django.models import UserDataModel
-
-    if not user or user.is_anonymous:
-        return None
-
-    pk = get_pk(user)
-    model, _ = await UserDataModel.objects.aget_or_create(user_pk=pk)
-    data = orjson.loads(model.data) if model.data else {}
-
-    if not isinstance(data, dict):
-        msg = f"Expected dict while loading user data, got {type(data)}"
-        raise TypeError(msg)
-
-    # Set default values, if needed
-    if default_data:
-        changed = False
-        for key, value in default_data.items():
-            if key not in data:
-                new_value: Any = value
-                if callable(value):
-                    new_value = await ensure_async(value)()
-                data[key] = new_value
-                changed = True
-        if changed:
-            model.data = orjson.dumps(data)
-            if save_default_data:
-                await model.asave()
-
-    return data

From da09eb24679473093e27ee5bd0bd1c81f605e838 Mon Sep 17 00:00:00 2001
From: Mark Bakhit <archiethemonger@gmail.com>
Date: Mon, 14 Sep 2026 16:45:53 -0700
Subject: [PATCH 22/26] Restore full hooks.py with typed flush_task ref

---
 src/reactpy_django/hooks.py | 562 ++++++++++++++++++++++++++++++++++++
 1 file changed, 562 insertions(+)

diff --git a/src/reactpy_django/hooks.py b/src/reactpy_django/hooks.py
index bc14dac6..76358b27 100644
--- a/src/reactpy_django/hooks.py
+++ b/src/reactpy_django/hooks.py
@@ -1,3 +1,382 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections import defaultdict
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Union,
+    cast,
+)
+from uuid import uuid4
+
+import dill
+import orjson
+from channels import DEFAULT_CHANNEL_LAYER
+from channels import auth as channels_auth
+from channels.layers import InMemoryChannelLayer, get_channel_layer
+from reactpy import use_async_effect, use_callback, use_effect, use_memo, use_ref, use_state
+from reactpy import use_connection as _use_connection
+from reactpy import use_location as _use_location
+from reactpy import use_scope as _use_scope
+
+from reactpy_django.exceptions import UserNotFoundError
+from reactpy_django.types import (
+    AsyncMessageReceiver,
+    AsyncMessageSender,
+    AsyncPostprocessor,
+    ConnectionType,
+    FuncParams,
+    Inferred,
+    Mutation,
+    Query,
+    SyncPostprocessor,
+    UseAuthTuple,
+    UserData,
+)
+from reactpy_django.utils import django_query_postprocessor, ensure_async, generate_obj_name, get_pk
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Sequence
+
+    from channels_redis.core import RedisChannelLayer
+    from django.contrib.auth.models import AbstractUser
+    from reactpy.types import Location
+
+
+_logger = logging.getLogger(__name__)
+_REFETCH_CALLBACKS: defaultdict[Callable[..., Any], set[Callable[[], None]]] = defaultdict(set)
+
+
+def use_location() -> Location:
+    """Get the current route as a `Location` object"""
+    return _use_location()
+
+
+def use_origin() -> str | None:
+    """Get the current origin as a string. If the browser did not send an origin header,
+    this will be None."""
+    scope = _use_scope()
+    try:
+        if scope["type"] == "websocket":
+            return next(
+                (header[1].decode("utf-8") for header in scope["headers"] if header[0] == b"origin"),
+                None,
+            )
+        if scope["type"] == "http":
+            host = next(header[1].decode("utf-8") for header in scope["headers"] if header[0] == b"host")
+            return f"{scope['scheme']}://{host}" if host else None
+    except Exception:
+        _logger.info("Failed to get origin")
+    return None
+
+
+def use_scope() -> dict[str, Any]:
+    """Get the current ASGI scope dictionary"""
+    scope = _use_scope()
+
+    if isinstance(scope, dict):
+        return cast("dict[str, Any]", scope)
+
+    msg = f"Expected scope to be a dict, got {type(scope)}"
+    raise TypeError(msg)
+
+
+def use_connection() -> ConnectionType:
+    """Get the current `Connection` object"""
+    return _use_connection()
+
+
+def use_query(
+    query: Callable[FuncParams, Awaitable[Inferred]] | Callable[FuncParams, Inferred],
+    kwargs: dict[str, Any] | None = None,
+    *,
+    thread_sensitive: bool = True,
+    postprocessor: (AsyncPostprocessor | SyncPostprocessor | None) = django_query_postprocessor,
+    postprocessor_kwargs: dict[str, Any] | None = None,
+) -> Query[Inferred]:
+    """This hook is used to execute functions in the background and return the result, \
+        typically to read data the Django ORM.
+
+    Args:
+        query: A function that executes a query and returns some data.
+
+    Kwargs:
+        kwargs: Keyword arguments to passed into the `query` function.
+        thread_sensitive: Whether to run the query in thread sensitive mode. \
+            This setting only applies to sync functions, and is turned on by default \
+            due to Django ORM limitations.
+        postprocessor: A callable that processes the query `data` before it is returned. \
+            The first argument of postprocessor function must be the query `data`. All \
+            proceeding arguments are optional `postprocessor_kwargs`. This postprocessor \
+            function must return the modified `data`. \
+            \
+            If unset, `REACTPY_DEFAULT_QUERY_POSTPROCESSOR` is used. By default, this \
+            is used to prevent Django's lazy query execution and supports `many_to_many` \
+            and `many_to_one` as `postprocessor_kwargs`.
+        postprocessor_kwargs: Keyworded arguments passed into the `postprocessor` function.
+
+    Returns:
+         An object containing `loading`/`#!python error` states, your `data` (if the query \
+         has successfully executed), and a `refetch` callable that can be used to re-run the query.
+    """
+
+    should_execute, set_should_execute = use_state(True)
+    data, set_data = use_state(cast("Inferred", None))
+    loading, set_loading = use_state(True)
+    error, set_error = use_state(cast("Union[Exception, None]", None))
+    query_ref = use_ref(query)
+    kwargs = kwargs or {}
+    postprocessor_kwargs = postprocessor_kwargs or {}
+
+    if query_ref.current is not query:
+        msg = f"Query function changed from {query_ref.current} to {query}."
+        raise ValueError(msg)
+
+    async def execute_query() -> None:
+        """The main running function for `use_query`"""
+        try:
+            # Run the query
+            query_async = cast(
+                "Callable[..., Awaitable[Inferred]]", ensure_async(query, thread_sensitive=thread_sensitive)
+            )
+            new_data = await query_async(**kwargs)
+
+            # Run the postprocessor
+            if postprocessor:
+                async_postprocessor = cast(
+                    "Callable[..., Awaitable[Any]]", ensure_async(postprocessor, thread_sensitive=thread_sensitive)
+                )
+                new_data = await async_postprocessor(new_data, **postprocessor_kwargs)
+
+        # Log any errors and set the error state
+        except Exception as e:
+            set_loading(False)
+            set_error(e)
+            _logger.exception("Failed to execute query '%s'", generate_obj_name(query))
+            return
+
+        # Query was successful
+        else:
+            set_data(new_data)
+            set_loading(False)
+            set_error(None)
+
+    @use_async_effect(dependencies=[should_execute])
+    async def schedule_query() -> None:
+        """Execute a query when needed."""
+        # Make sure we don't re-execute the query unless we're told to
+        if not should_execute:
+            return
+
+        # Execute the query
+        await execute_query()
+        set_should_execute(False)
+
+    @use_callback
+    def refetch() -> None:
+        """Callable provided to the user, used to re-execute the query"""
+        set_should_execute(True)
+        set_loading(True)
+        set_error(None)
+
+    @use_effect(dependencies=[])
+    def register_refetch_callback() -> Callable[[], None]:
+        """Track the refetch callback so we can re-execute the query"""
+        # By tracking callbacks globally, any usage of the query function will be re-run
+        # if the user has told a mutation to refetch it.
+        _REFETCH_CALLBACKS[query].add(refetch)
+        return lambda: _REFETCH_CALLBACKS[query].remove(refetch)
+
+    # Return Query user API
+    return Query(data, loading, error, refetch)
+
+
+def use_mutation(
+    mutation: (Callable[FuncParams, bool | None] | Callable[FuncParams, Awaitable[bool | None]]),
+    *,
+    thread_sensitive: bool = True,
+    refetch: Callable[..., Any] | Sequence[Callable[..., Any]] | None = None,
+) -> Mutation[FuncParams]:
+    """This hook is used to modify data in the background, typically to create/update/delete \
+    data from the Django ORM.
+
+    Mutation functions can `return False` to prevent executing your `refetch` function. All \
+    other returns are ignored. Mutation functions can be sync or async.
+
+    Args:
+        mutation: A callable that performs Django ORM create, update, or delete \
+            functionality. If this function returns `False`, then your `refetch` \
+            function will not be used.
+
+    Kwargs:
+        thread_sensitive: Whether to run the mutation in thread sensitive mode. \
+            This setting only applies to sync functions, and is turned on by default \
+            due to Django ORM limitations.
+        refetch:  A query function (the function you provide to your `use_query` \
+            hook) or a sequence of query functions that need a `refetch` if the \
+            mutation succeeds. This is useful for refreshing data after a mutation \
+            has been performed.
+
+    Returns:
+        An object containing `#!python loading`/`#!python error` states, and a \
+        `#!python reset` callable that will set `#!python loading`/`#!python error` \
+        states to defaults. This object can be called to run the query.
+    """
+
+    loading, set_loading = use_state(False)
+    error, set_error = use_state(cast("Union[Exception, None]", None))
+    async_task_refs = use_ref(set())
+
+    # The main "running" function for `use_mutation`
+    async def execute_mutation(*exec_args: FuncParams.args, **exec_kwargs: FuncParams.kwargs) -> None:
+        # Run the mutation
+        try:
+            should_refetch = await ensure_async(mutation, thread_sensitive=thread_sensitive)(*exec_args, **exec_kwargs)
+
+        # Log any errors and set the error state
+        except Exception as e:
+            set_loading(False)
+            set_error(e)
+            _logger.exception("Failed to execute mutation: %s", generate_obj_name(mutation))
+
+        # Mutation was successful
+        else:
+            set_loading(False)
+            set_error(None)
+
+            # `refetch` will execute unless explicitly told not to
+            # or if `refetch` was not defined.
+            if should_refetch is not False and refetch:
+                for query in (refetch,) if callable(refetch) else refetch:
+                    for callback in _REFETCH_CALLBACKS.get(query) or ():
+                        callback()
+
+    # Schedule the mutation to be run when needed
+    def schedule_mutation(*exec_args: FuncParams.args, **exec_kwargs: FuncParams.kwargs) -> None:
+        # Set the loading state.
+        # It's okay to re-execute the mutation if we're told to. If desired,
+        # The user could use the `loading` state to prevent double execution.
+        set_loading(True)
+
+        # Execute the mutation in the background
+        task = asyncio.ensure_future(execute_mutation(*exec_args, **exec_kwargs))
+
+        # Add the task to a set to prevent it from being garbage collected
+        async_task_refs.current.add(task)
+        task.add_done_callback(async_task_refs.current.remove)
+
+    # Used when the user has told us to reset this mutation
+    @use_callback
+    def reset() -> None:
+        set_loading(False)
+        set_error(None)
+
+    # Return mutation user API
+    return Mutation(schedule_mutation, loading, error, reset)
+
+
+def use_user() -> AbstractUser:
+    """Get the current `User` object from either the WebSocket or HTTP request."""
+    connection = use_connection()
+    user = connection.scope.get("user") or getattr(connection.carrier, "user", None)
+    if user is None:
+        msg = "No user is available in the current environment."
+        raise UserNotFoundError(msg)
+    return user
+
+
+def use_user_data(
+    default_data: (dict[str, Callable[[], Any] | Callable[[], Awaitable[Any]] | Any] | None) = None,
+    save_default_data: bool = False,
+) -> UserData:
+    """Get or set user data stored within the REACTPY_DATABASE.
+
+    Kwargs:
+        default_data: A dictionary containing `{key: default_value}` pairs. \
+            For computationally intensive defaults, your `default_value` \
+            can be sync or async functions that return the value to set.
+        save_default_data: If True, `default_data` values will automatically be stored \
+            within the database if they do not exist.
+    """
+    from reactpy_django.models import UserDataModel
+
+    user = use_user()
+
+    async def _set_user_data(data: dict):
+        if not isinstance(data, dict):
+            msg = f"Expected dict while setting user data, got {type(data)}"
+            raise TypeError(msg)
+        if user.is_anonymous:
+            msg = "AnonymousUser cannot have user data."
+            raise ValueError(msg)
+
+        pk = get_pk(user)
+        model, _ = await UserDataModel.objects.aget_or_create(user_pk=pk)
+        model.data = orjson.dumps(data)
+        await model.asave()
+
+    query: Query[dict | None] = use_query(
+        _get_user_data,
+        kwargs={
+            "user": user,
+            "default_data": default_data,
+            "save_default_data": save_default_data,
+        },
+        postprocessor=None,
+    )
+    mutation = use_mutation(_set_user_data, refetch=_get_user_data)
+
+    return UserData(query, mutation)
+
+
+def use_session_state(
+    default: Any,
+    key: str,
+    *,
+    save_default: bool = False,
+) -> tuple[Any, Callable[[Any], None]]:
+    """Persist state across WebSocket reconnects (and, optionally, page reloads).
+
+    This hook stores its value in the ReactPy database so that it can be restored after a
+    WebSocket reconnect, which would otherwise reset all in-memory component state. It is
+    more robust than in-memory state because it survives multi-process deployments and
+    round-robin load balancing across multiple hosts.
+
+    The state's scope is controlled by the ``REACTPY_SESSION_STATE_MODE`` setting:
+
+    - ``"tab"`` (default): state is scoped to the rendered component (a per-tab, per-component
+      token that is stable across reconnects). Works for anonymous users without requiring
+      ``django.contrib.sessions``.
+    - ``"user"``: state is scoped to the authenticated user, falling back to a per-tab token
+      for anonymous users.
+
+    Args:
+        default: The value to use when no persisted state exists.
+        key: A unique identifier for this state slot within the computed scope. Multiple
+            ``use_session_state`` hooks in the same component must use distinct keys.
+
+    Kwargs:
+        save_default: If ``True``, the ``default`` value will be persisted when no state
+            already exists in the database.
+
+    Returns:
+        A tuple of ``(state, set_state)``. ``state`` is the current value (loaded from the
+        database, or ``default`` if none exists). ``set_state`` updates the in-memory value
+        immediately and schedules a debounced database write so that frequently-changing
+        values do not hammer the database.
+
+    Note:
+        Only serializable data may be stored. Values are serialized with ``dill``, so most
+        common Python objects are supported, but objects holding un-picklable resources
+        (e.g. open file handles or network connections) will fail.
+    """
+    from reactpy_django import config
+
+    scope_id = _resolve_session_state_scope_id()
+
     # In-memory reactive state. This keeps the UI responsive while database writes are
     # debounced in the background.
     state, set_state = use_state(cast("Any", default))
@@ -68,3 +447,186 @@ def _cleanup() -> None:
         return _cleanup
 
     return state, set_state_and_persist
+
+
+def use_channel_layer(
+    *,
+    channel: str | None = None,
+    group: str | None = None,
+    receiver: AsyncMessageReceiver | None = None,
+    layer: str = DEFAULT_CHANNEL_LAYER,
+) -> AsyncMessageSender:
+    """
+    Subscribe to a Django Channels layer to send/receive messages.
+
+    Args:
+        channel:  The name of the channel this hook will send/receive messages on. If `group` is \
+        defined and `channel` is `None`, ReactPy will automatically generate a unique channel name.
+
+    Kwargs:
+        group: If configured, the `channel` is added to a `group` and any messages sent by `AsyncMessageSender` \
+            is broadcasted to all channels within the `group`.
+        receiver: An async function that receives a `message: dict` from a channel.
+        layer: The Django Channels layer to use. This layer must be defined in `settings.py:CHANNEL_LAYERS`.
+
+    Returns:
+        An async callable that can send messages to the channel(s). This callable accepts a single \
+        argument, `message: dict`, which is the data sent to the channel or group of channels.
+    """
+    channel_layer: InMemoryChannelLayer | RedisChannelLayer = get_channel_layer(layer)  # type: ignore
+    channel_name = use_memo(lambda: str(channel or uuid4()))
+
+    if not (channel or group):
+        msg = "You must either define a `channel` or `group` for this hook."
+        raise ValueError(msg)
+
+    if not channel_layer:
+        msg = (
+            f"Channel layer '{layer}' is not available. Are you sure you"
+            " configured settings.py:CHANNEL_LAYERS properly?"
+        )
+        raise ValueError(msg)
+
+    # Add/remove a group's channel during component mount/dismount respectively.
+    @use_async_effect(dependencies=[])
+    async def group_manager():
+        if group:
+            group_name: str = group
+            await channel_layer.group_add(group_name, channel_name)
+            return lambda: asyncio.run(channel_layer.group_discard(group_name, channel_name))
+        return None
+
+    # Listen for messages on the channel using the provided `receiver` function.
+    @use_async_effect
+    async def message_receiver():
+        if not receiver:
+            return
+
+        while True:
+            message = await channel_layer.receive(channel_name)
+            await receiver(message)
+
+    # User interface for sending messages to the channel
+    async def message_sender(message: dict):
+        if group:
+            await channel_layer.group_send(group, message)
+        else:
+            await channel_layer.send(channel_name, message)
+
+    return message_sender
+
+
+def use_root_id() -> str:
+    """Get the root element's ID. This value is guaranteed to be unique. Current versions of \
+        ReactPy-Django return a `uuid4` string."""
+    scope = use_scope()
+
+    return scope["reactpy"]["id"]
+
+
+def use_rerender() -> Callable[[], None]:
+    """Provides a callable that can re-render the entire component tree without disconnecting the websocket."""
+    scope = use_scope()
+
+    def rerender():
+        scope["reactpy"]["rerender"]()
+
+    return rerender
+
+
+def use_auth() -> UseAuthTuple:
+    """Provides the ability to login/logout a user using Django's authentication framework."""
+    from reactpy_django import config
+
+    scope = use_scope()
+    trigger_rerender = use_rerender()
+
+    async def login(user: AbstractUser, rerender: bool = True) -> None:
+        await channels_auth.login(scope, user, backend=config.REACTPY_AUTH_BACKEND)  # type: ignore[reportArgumentType]
+        session_save_method = getattr(scope["session"], "asave", scope["session"].save)
+        await ensure_async(session_save_method)()
+        await scope["reactpy"]["synchronize_auth"]()
+
+        if rerender:
+            trigger_rerender()
+
+    async def logout(rerender: bool = True) -> None:
+        await channels_auth.logout(scope)  # type: ignore[reportArgumentType]
+
+        if rerender:
+            trigger_rerender()
+
+    return UseAuthTuple(login=login, logout=logout)
+
+
+def _resolve_session_state_scope_id() -> str:
+    """Resolve the stable identity used to scope persistent session state.
+
+    In ``"tab"`` mode this is the rendered component's UUID (stable across reconnects).
+    In ``"user"`` mode this is the authenticated user's primary key, falling back to a
+    per-tab token for anonymous users so that unauthenticated visitors still get isolated,
+    persistent state.
+    """
+    from reactpy_django import config
+
+    root_id = use_root_id()
+
+    if config.REACTPY_SESSION_STATE_MODE == "user":
+        connection = use_connection()
+        user = connection.scope.get("user")
+        if user is not None and not user.is_anonymous:
+            return f"user:{get_pk(user)}"
+
+    return f"tab:{root_id}"
+
+
+async def _get_session_state(scope_id: str, key: str, default: Any) -> Any:
+    """Load a persisted session state value from the database, or return `default`."""
+    from reactpy_django.models import SessionStateModel
+
+    model = await SessionStateModel.objects.filter(scope_id=scope_id, key=key).afirst()
+    if model is None or model.data is None:
+        return default
+    return dill.loads(model.data)
+
+
+async def _set_session_state(scope_id: str, key: str, data: Any) -> None:
+    """Persist a session state value to the database."""
+    from reactpy_django.models import SessionStateModel
+
+    model, _ = await SessionStateModel.objects.aget_or_create(scope_id=scope_id, key=key)
+    model.data = dill.dumps(data)
+    await model.asave()
+
+
+async def _get_user_data(user: AbstractUser, default_data: dict | None, save_default_data: bool) -> dict | None:
+    """The mutation function for `use_user_data`"""
+    from reactpy_django.models import UserDataModel
+
+    if not user or user.is_anonymous:
+        return None
+
+    pk = get_pk(user)
+    model, _ = await UserDataModel.objects.aget_or_create(user_pk=pk)
+    data = orjson.loads(model.data) if model.data else {}
+
+    if not isinstance(data, dict):
+        msg = f"Expected dict while loading user data, got {type(data)}"
+        raise TypeError(msg)
+
+    # Set default values, if needed
+    if default_data:
+        changed = False
+        for key, value in default_data.items():
+            if key not in data:
+                new_value: Any = value
+                if callable(value):
+                    new_value = await ensure_async(value)()
+                data[key] = new_value
+                changed = True
+        if changed:
+            model.data = orjson.dumps(data)
+            if save_default_data:
+                await model.asave()
+
+    return data

From c09d90ab389e6b519ec89d3c9514f82053bef69b Mon Sep 17 00:00:00 2001
From: User <user@example.com>
Date: Tue, 15 Sep 2026 00:48:57 +0000
Subject: [PATCH 23/26] Add system checks for session state settings

Add validation for the new REACTPY_SESSION_STATE_* and
REACTPY_CLEAN_SESSION_STATE settings introduced for the
use_session_state hook.
---
 src/reactpy_django/checks.py | 71 ++++++++++++++++++++++++++++++++++++
 1 file changed, 71 insertions(+)

diff --git a/src/reactpy_django/checks.py b/src/reactpy_django/checks.py
index d778e531..20ba912d 100644
--- a/src/reactpy_django/checks.py
+++ b/src/reactpy_django/checks.py
@@ -564,4 +564,75 @@ def reactpy_errors(app_configs, **kwargs):
             )
         )
 
+    # Check if REACTPY_SESSION_STATE_MODE is a valid data type
+    if not isinstance(config.REACTPY_SESSION_STATE_MODE, str):
+        errors.append(
+            checks.Error(
+                "Invalid type for REACTPY_SESSION_STATE_MODE.",
+                hint="REACTPY_SESSION_STATE_MODE should be a string.",
+                id="reactpy_django.E030",
+            )
+        )
+
+    # Check if REACTPY_SESSION_STATE_MODE is a valid value
+    if config.REACTPY_SESSION_STATE_MODE not in ("tab", "user"):
+        errors.append(
+            checks.Error(
+                "Invalid value for REACTPY_SESSION_STATE_MODE.",
+                hint="REACTPY_SESSION_STATE_MODE should be either 'tab' or 'user'.",
+                obj=config.REACTPY_SESSION_STATE_MODE,
+                id="reactpy_django.E031",
+            )
+        )
+
+    # Check if REACTPY_SESSION_STATE_SYNC_INTERVAL is a valid data type
+    if not isinstance(config.REACTPY_SESSION_STATE_SYNC_INTERVAL, int):
+        errors.append(
+            checks.Error(
+                "Invalid type for REACTPY_SESSION_STATE_SYNC_INTERVAL.",
+                hint="REACTPY_SESSION_STATE_SYNC_INTERVAL should be an integer.",
+                id="reactpy_django.E032",
+            )
+        )
+
+    # Check if REACTPY_SESSION_STATE_SYNC_INTERVAL is a positive integer
+    if isinstance(config.REACTPY_SESSION_STATE_SYNC_INTERVAL, int) and config.REACTPY_SESSION_STATE_SYNC_INTERVAL < 0:
+        errors.append(
+            checks.Error(
+                "Invalid value for REACTPY_SESSION_STATE_SYNC_INTERVAL.",
+                hint="REACTPY_SESSION_STATE_SYNC_INTERVAL should be a positive integer.",
+                id="reactpy_django.E033",
+            )
+        )
+
+    # Check if REACTPY_SESSION_STATE_MAX_AGE is a valid data type
+    if not isinstance(config.REACTPY_SESSION_STATE_MAX_AGE, int):
+        errors.append(
+            checks.Error(
+                "Invalid type for REACTPY_SESSION_STATE_MAX_AGE.",
+                hint="REACTPY_SESSION_STATE_MAX_AGE should be an integer.",
+                id="reactpy_django.E034",
+            )
+        )
+
+    # Check if REACTPY_SESSION_STATE_MAX_AGE is a positive integer
+    if isinstance(config.REACTPY_SESSION_STATE_MAX_AGE, int) and config.REACTPY_SESSION_STATE_MAX_AGE < 0:
+        errors.append(
+            checks.Error(
+                "Invalid value for REACTPY_SESSION_STATE_MAX_AGE.",
+                hint="REACTPY_SESSION_STATE_MAX_AGE should be a positive integer.",
+                id="reactpy_django.E035",
+            )
+        )
+
+    # Check if REACTPY_CLEAN_SESSION_STATE is a valid data type
+    if not isinstance(config.REACTPY_CLEAN_SESSION_STATE, bool):
+        errors.append(
+            checks.Error(
+                "Invalid type for REACTPY_CLEAN_SESSION_STATE.",
+                hint="REACTPY_CLEAN_SESSION_STATE should be a boolean.",
+                id="reactpy_django.E036",
+            )
+        )
+
     return errors

From 7865e1cd06d9eb5aa2979fd706bf46c17cbfa09f Mon Sep 17 00:00:00 2001
From: User <user@example.com>
Date: Tue, 15 Sep 2026 03:42:07 +0000
Subject: [PATCH 24/26] Document session state settings and use_session_state
 hook

Add reference docs for the new REACTPY_SESSION_STATE_* and
REACTPY_CLEAN_SESSION_STATE settings, and document the
use_session_state hook with an example.
---
 docs/examples/python/use_session_state.py | 13 ++++++
 docs/src/reference/hooks.md               | 41 ++++++++++++++++++
 docs/src/reference/settings.md            | 51 +++++++++++++++++++++++
 3 files changed, 105 insertions(+)
 create mode 100644 docs/examples/python/use_session_state.py

diff --git a/docs/examples/python/use_session_state.py b/docs/examples/python/use_session_state.py
new file mode 100644
index 00000000..19f67994
--- /dev/null
+++ b/docs/examples/python/use_session_state.py
@@ -0,0 +1,13 @@
+from reactpy import component, html
+
+from reactpy_django.hooks import use_session_state
+
+
+@component
+def my_component():
+    count, set_count = use_session_state(0, key="counter")
+
+    return html.button(
+        {"onClick": lambda _: set_count(count + 1)},
+        f"Count: {count}",
+    )
diff --git a/docs/src/reference/hooks.md b/docs/src/reference/hooks.md
index e8c3d8fb..c7e0e649 100644
--- a/docs/src/reference/hooks.md
+++ b/docs/src/reference/hooks.md
@@ -385,6 +385,47 @@ User data saved with this hook is stored within the `#!python REACTPY_DATABASE`.
 
 ---
 
+### Use Session State
+
+Persist state across WebSocket reconnects (and, optionally, page reloads) so that it survives a fresh `#!python Layout` being created on reconnect.
+
+This hook stores its value in the `#!python REACTPY_DATABASE`, so it is more robust than in-memory state because it survives multi-process deployments and round-robin load balancing across multiple hosts.
+
+=== "components.py"
+
+    ```python
+    {% include "../../examples/python/use_session_state.py" %}
+    ```
+
+??? example "See Interface"
+
+    <font size="4">**Parameters**</font>
+
+    | Name | Type | Description | Default |
+    | --- | --- | --- | --- |
+    | `#!python default` | `#!python Any` | The value to use when no persisted state exists. | N/A |
+    | `#!python key` | `#!python str` | A unique identifier for this state slot within the computed scope. Multiple `#!python use_session_state` hooks in the same component must use distinct keys. | N/A |
+    | `#!python save_default` | `#!python bool` | If `#!python True`, the `#!python default` value will be persisted when no state already exists in the database. | `#!python False` |
+
+    <font size="4">**Returns**</font>
+
+    | Type | Description |
+    | --- | --- |
+    | `#!python tuple[Any, Callable[[Any], None]]` | A tuple of `#!python (state, set_state)`. `#!python state` is the current value (loaded from the database, or `#!python default` if none exists). `#!python set_state` updates the in-memory value immediately and schedules a debounced database write so that frequently-changing values do not hammer the database. |
+
+??? question "How is state scoped?"
+
+    The state's scope is controlled by the `#!python REACTPY_SESSION_STATE_MODE` [setting](./settings.md#reactpy_session_state_mode).
+
+    - `#!python "tab"` (default): state is scoped to the rendered component (a per-tab, per-component token that is stable across reconnects). This works for anonymous users without requiring `#!python django.contrib.sessions`, and isolates state between browser tabs.
+    - `#!python "user"`: state is scoped to the authenticated user, falling back to a per-tab token for anonymous users.
+
+??? warning "Only serializable data may be stored"
+
+    Values are serialized with `#!python dill`, so most common Python objects are supported, but objects holding un-picklable resources (e.g. open file handles or network connections) will fail.
+
+---
+
 ## Communication Hooks
 
 ---
diff --git a/docs/src/reference/settings.md b/docs/src/reference/settings.md
index 50d0b7db..e1598898 100644
--- a/docs/src/reference/settings.md
+++ b/docs/src/reference/settings.md
@@ -194,6 +194,45 @@ You can use the `#!python prerender` argument in your [template tag](./template-
 
 ---
 
+## Session State Settings
+
+---
+
+### `#!python REACTPY_SESSION_STATE_MODE`
+
+**Default:** `#!python "tab"`
+
+**Example Value(s):** `#!python "tab"`, `#!python "user"`
+
+Controls the scope of state persisted by the [`use_session_state`](./hooks.md#use-session-state) hook.
+
+- `#!python "tab"` (default): state is scoped to the rendered component (a per-tab, per-component token that is stable across WebSocket reconnects). This works for anonymous users without requiring `#!python django.contrib.sessions`, and isolates state between browser tabs.
+- `#!python "user"`: state is scoped to the authenticated user, falling back to a per-tab token for anonymous users.
+
+---
+
+### `#!python REACTPY_SESSION_STATE_SYNC_INTERVAL`
+
+**Default:** `#!python 5`
+
+**Example Value(s):** `#!python 1`, `#!python 30`, `#!python 60`
+
+Seconds between debounced database flush writes for `#!python use_session_state`. Rapid state changes (e.g. typing) are coalesced into a single database write after this interval elapses.
+
+---
+
+### `#!python REACTPY_SESSION_STATE_MAX_AGE`
+
+**Default:** `#!python 259200`
+
+**Example Value(s):** `#!python 0`, `#!python 3600`, `#!python 604800`
+
+Maximum seconds stale session state is retained before it is removed during [ReactPy clean up](#auto-clean-settings).
+
+Use `#!python 0` to immediately expire stale session state.
+
+---
+
 ## Stability Settings
 
 ---
@@ -303,3 +342,15 @@ Configures whether ReactPy should clean up expired authentication tokens during
 Configures whether ReactPy should clean up orphaned user data during automatic clean up operations.
 
 Typically, user data does not become orphaned unless the server crashes during a `#!python User` delete operation.
+
+---
+
+### `#!python REACTPY_CLEAN_SESSION_STATE`
+
+**Default:** `#!python True`
+
+**Example Value(s):** `#!python False`
+
+Configures whether ReactPy should clean up stale session state during automatic clean up operations.
+
+Stale session state is state that has not been updated within `#!python REACTPY_SESSION_STATE_MAX_AGE` seconds.

From e4eb1803350830fe14b0b81a883409e99864409a Mon Sep 17 00:00:00 2001
From: User <user@example.com>
Date: Tue, 15 Sep 2026 03:49:59 +0000
Subject: [PATCH 25/26] Fix docs spellcheck for session state terms

Add 'debounced' and 'picklable' to the docs dictionary, and reword
the 'un-picklable' phrase in the use_session_state docs so the docs
build passes in strict spellcheck mode.
---
 docs/src/dictionary.txt     | 2 ++
 docs/src/reference/hooks.md | 2 +-
 2 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/docs/src/dictionary.txt b/docs/src/dictionary.txt
index d2ff722d..2a1d3e0a 100644
--- a/docs/src/dictionary.txt
+++ b/docs/src/dictionary.txt
@@ -5,6 +5,7 @@ backends
 backhaul
 broadcasted
 changelog
+debounced
 django
 frontend
 frontends
@@ -18,6 +19,7 @@ misconfiguration
 misconfigurations
 my_template
 nox
+picklable
 plotly
 postfixed
 postprocessing
diff --git a/docs/src/reference/hooks.md b/docs/src/reference/hooks.md
index c7e0e649..f236c6e7 100644
--- a/docs/src/reference/hooks.md
+++ b/docs/src/reference/hooks.md
@@ -422,7 +422,7 @@ This hook stores its value in the `#!python REACTPY_DATABASE`, so it is more rob
 
 ??? warning "Only serializable data may be stored"
 
-    Values are serialized with `#!python dill`, so most common Python objects are supported, but objects holding un-picklable resources (e.g. open file handles or network connections) will fail.
+    Values are serialized with `#!python dill`, so most common Python objects are supported, but objects holding resources that are not picklable (e.g. open file handles or network connections) will fail.
 
 ---
 

From 6d269904bea130f565737518d703f8c4ec4dad63 Mon Sep 17 00:00:00 2001
From: User <user@example.com>
Date: Tue, 15 Sep 2026 04:28:05 +0000
Subject: [PATCH 26/26] Reduce session state sync interval to 10s and allow
 disabling periodic sync

Change the default REACTPY_SESSION_STATE_SYNC_INTERVAL from 5 to 10
seconds, and allow setting it to 0 to disable periodic syncing. When
0, state is only persisted to the database on unmount (e.g. when a
WebSocket reconnects). Update the docs, changelog, and system check
hints accordingly.
---
 CHANGELOG.md                   | 2 +-
 docs/src/dictionary.txt        | 1 +
 docs/src/reference/hooks.md    | 2 +-
 docs/src/reference/settings.md | 6 ++++--
 src/reactpy_django/checks.py   | 4 ++--
 src/reactpy_django/config.py   | 2 +-
 src/reactpy_django/hooks.py    | 4 ++++
 7 files changed, 14 insertions(+), 7 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 713b238d..0ca6c6c5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -24,7 +24,7 @@ Don't forget to remove deprecated code on each major release!
 - Add `reactpy_django.hooks.use_session_state` hook for persistent state across WebSocket reconnects.
     - State is stored in the ReactPy database, so it survives multi-process deployments and round-robin load balancing across hosts.
     - `settings.py:REACTPY_SESSION_STATE_MODE` to control whether state is scoped per-tab (default) or per-user.
-    - `settings.py:REACTPY_SESSION_STATE_SYNC_INTERVAL` to control how frequently state is flushed to the database.
+    - `settings.py:REACTPY_SESSION_STATE_SYNC_INTERVAL` (default 10 seconds) to control how frequently state is flushed to the database. Set to `0` to disable periodic syncing so state is only persisted on unmount.
     - `settings.py:REACTPY_SESSION_STATE_MAX_AGE` to control how long stale session state is retained.
     - `settings.py:REACTPY_CLEAN_SESSION_STATE` to control whether stale session state is cleaned up during automatic cleanups.
 - Automatically serve ReactPy wheel from Django's static directory when using PyScript.
diff --git a/docs/src/dictionary.txt b/docs/src/dictionary.txt
index 2a1d3e0a..e4025d3a 100644
--- a/docs/src/dictionary.txt
+++ b/docs/src/dictionary.txt
@@ -41,6 +41,7 @@ serializable
 stylesheet
 stylesheets
 sublicense
+unmount
 unstyled
 WebSocket
 WebSockets
diff --git a/docs/src/reference/hooks.md b/docs/src/reference/hooks.md
index f236c6e7..20cad76d 100644
--- a/docs/src/reference/hooks.md
+++ b/docs/src/reference/hooks.md
@@ -411,7 +411,7 @@ This hook stores its value in the `#!python REACTPY_DATABASE`, so it is more rob
 
     | Type | Description |
     | --- | --- |
-    | `#!python tuple[Any, Callable[[Any], None]]` | A tuple of `#!python (state, set_state)`. `#!python state` is the current value (loaded from the database, or `#!python default` if none exists). `#!python set_state` updates the in-memory value immediately and schedules a debounced database write so that frequently-changing values do not hammer the database. |
+    | `#!python tuple[Any, Callable[[Any], None]]` | A tuple of `#!python (state, set_state)`. `#!python state` is the current value (loaded from the database, or `#!python default` if none exists). `#!python set_state` updates the in-memory value immediately and schedules a debounced database write so that frequently-changing values do not hammer the database. The update interval is controlled by `#!python REACTPY_SESSION_STATE_SYNC_INTERVAL`; setting it to `#!python 0` disables periodic syncing so writes only occur on unmount. |
 
 ??? question "How is state scoped?"
 
diff --git a/docs/src/reference/settings.md b/docs/src/reference/settings.md
index e1598898..cee473a4 100644
--- a/docs/src/reference/settings.md
+++ b/docs/src/reference/settings.md
@@ -213,12 +213,14 @@ Controls the scope of state persisted by the [`use_session_state`](./hooks.md#us
 
 ### `#!python REACTPY_SESSION_STATE_SYNC_INTERVAL`
 
-**Default:** `#!python 5`
+**Default:** `#!python 10`
 
-**Example Value(s):** `#!python 1`, `#!python 30`, `#!python 60`
+**Example Value(s):** `#!python 0`, `#!python 1`, `#!python 30`, `#!python 60`
 
 Seconds between debounced database flush writes for `#!python use_session_state`. Rapid state changes (e.g. typing) are coalesced into a single database write after this interval elapses.
 
+Set this value to `#!python 0` to disable periodic syncing. In that case, state is only persisted to the database when the component is unmounted (such as when a WebSocket reconnects).
+
 ---
 
 ### `#!python REACTPY_SESSION_STATE_MAX_AGE`
diff --git a/src/reactpy_django/checks.py b/src/reactpy_django/checks.py
index 20ba912d..380daffc 100644
--- a/src/reactpy_django/checks.py
+++ b/src/reactpy_django/checks.py
@@ -595,12 +595,12 @@ def reactpy_errors(app_configs, **kwargs):
             )
         )
 
-    # Check if REACTPY_SESSION_STATE_SYNC_INTERVAL is a positive integer
+    # Check if REACTPY_SESSION_STATE_SYNC_INTERVAL is a non-negative integer
     if isinstance(config.REACTPY_SESSION_STATE_SYNC_INTERVAL, int) and config.REACTPY_SESSION_STATE_SYNC_INTERVAL < 0:
         errors.append(
             checks.Error(
                 "Invalid value for REACTPY_SESSION_STATE_SYNC_INTERVAL.",
-                hint="REACTPY_SESSION_STATE_SYNC_INTERVAL should be a positive integer.",
+                hint="REACTPY_SESSION_STATE_SYNC_INTERVAL should be a non-negative integer. Use 0 to disable periodic syncing.",
                 id="reactpy_django.E033",
             )
         )
diff --git a/src/reactpy_django/config.py b/src/reactpy_django/config.py
index 0ccc6f3c..10644fd9 100644
--- a/src/reactpy_django/config.py
+++ b/src/reactpy_django/config.py
@@ -150,7 +150,7 @@
 REACTPY_SESSION_STATE_SYNC_INTERVAL: int = getattr(
     settings,
     "REACTPY_SESSION_STATE_SYNC_INTERVAL",
-    5,  # Default to 5 seconds
+    10,  # Default to 10 seconds; set to 0 to disable periodic syncing
 )
 REACTPY_SESSION_STATE_MAX_AGE: int = getattr(
     settings,
diff --git a/src/reactpy_django/hooks.py b/src/reactpy_django/hooks.py
index 76358b27..4d0e0c8a 100644
--- a/src/reactpy_django/hooks.py
+++ b/src/reactpy_django/hooks.py
@@ -419,6 +419,10 @@ async def debounced_flush() -> None:
 
     def schedule_flush() -> None:
         """Debounce database writes so rapid state changes coalesce into one write."""
+        # A sync interval of `0` disables periodic syncing. In that case, only the
+        # unmount cleanup will persist the latest value to the database.
+        if config.REACTPY_SESSION_STATE_SYNC_INTERVAL == 0:
+            return
         if flush_task.current is not None and not flush_task.current.done():
             flush_task.current.cancel()
         flush_task.current = asyncio.create_task(debounced_flush())