docs(chat): clarify DM routing precedence in on_direct_message + Thread.subscribe (#121)

* docs(chat): clarify DM routing precedence in on_direct_message + Thread.subscribe

Ports vercel/chat#491 (commit 67c1794) docstring-only update. Aligns
Python docstrings with upstream's clarified contract: registered
on_direct_message handlers take precedence for every DM message before
on_subscribed_message, on_mention, and on_message pattern handlers; when
no DM handler is registered, DMs continue through normal routing.

The Python runtime already implemented this precedence (see
chat.py::_handle_incoming_message:2154), so this is documentation
alignment with zero behavior change.

Added regression tests:
- TestDMRoutingDocs pins the new docstring wording on both
  Chat.on_direct_message and ThreadImpl.subscribe (so a future doc
  rewrite cannot silently drift back from upstream).
- test_dm_handler_runs_before_pattern_handler covers DM > on_message
  pattern precedence, which existing DM tests covered for subscribed
  and mention but not for pattern handlers.

Refs vercel/chat#491, tracking #98.

https://claude.ai/code/session_01FyMxQn2BEAzmwKS1GZczKj

* docs(thread): fully qualify Sphinx Chat refs (gemini review)

Rewrites `:py:meth:`Chat.on_subscribed_message`` and
`:py:meth:`Chat.on_direct_message`` in `Thread.subscribe`'s docstring as
`:py:meth:`~chat_sdk.chat.Chat.on_subscribed_message`` and
`:py:meth:`~chat_sdk.chat.Chat.on_direct_message``.

`Chat` is intentionally not imported in `thread.py` (TYPE_CHECKING-only) to
avoid a circular import. The unqualified refs wouldn't resolve under Sphinx;
the absolute paths do, and the `~` keeps the rendered link text short.

The `test_thread_subscribe_docstring_documents_dm_carveout` pin still passes:
its `"on_direct_message" in doc` assertion matches the substring inside the
new qualified ref.

https://claude.ai/code/session_01FyMxQn2BEAzmwKS1GZczKj

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: patrick-chinchill

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.4.29a3 (unreleased)
+
+### Documentation alignment
+
+- **DM routing precedence docstrings** (vercel/chat#491, commit `67c1794`). The Python runtime already routed direct messages to `on_direct_message` handlers before subscribed-message, mention, and pattern handlers (`Chat._handle_incoming_message`, `chat.py:2154`), but `on_direct_message` and `Thread.subscribe` lacked docstrings clarifying that contract. Refreshed both to match upstream's #491 docstring rewrite, plus a new `tests/integration/test_dm_flow.py::TestDMRoutingDocs` group and a `test_dm_handler_runs_before_pattern_handler` regression test that pin the documented precedence (DM > pattern) the previous suite did not explicitly cover. No runtime behavior change.
+
+> Version bump from `0.4.29a2` to `0.4.29a3` will be cut by a coordinating PR once the parallel 4.29 ports land; this entry intentionally leaves `pyproject.toml` unchanged.
+
 ## 0.4.29a2 (2026-05-28)
 
 Python-only fix. No upstream version change.

src/chat_sdk/chat.py

@@ -570,7 +570,21 @@ async def handle(thread, message):
         return handler
 
     def on_direct_message(self, handler: DirectMessageHandler) -> DirectMessageHandler:
-        """Register a handler for direct messages."""
+        """Register a handler for direct messages.
+
+        Called for every message received in a DM thread when at least one
+        direct message handler is registered. Direct message handlers run
+        before :py:meth:`on_subscribed_message`, :py:meth:`on_mention`, and
+        pattern handlers.
+
+        If no ``on_direct_message`` handlers are registered, DMs continue
+        through normal routing. Unsubscribed DMs fall through to
+        :py:meth:`on_mention` for backward compatibility.
+
+        Args:
+            handler: Handler called for DM messages. Receives
+                ``(thread, message, channel, context)``.
+        """
         self._direct_message_handlers.append(handler)
         self._logger.debug("Registered direct message handler")
         return handler

src/chat_sdk/thread.py

@@ -504,6 +504,14 @@ async def is_subscribed(self) -> bool:
         return await self._state_adapter.is_subscribed(self._id)
 
     async def subscribe(self) -> None:
+        """Subscribe to future messages in this thread.
+
+        Once subscribed, messages in non-DM threads trigger
+        :py:meth:`~chat_sdk.chat.Chat.on_subscribed_message` handlers. DM threads route to
+        :py:meth:`~chat_sdk.chat.Chat.on_direct_message` first when a direct message handler
+        is registered. The initial message that triggered subscription will
+        NOT fire the handler.
+        """
         await self._state_adapter.subscribe(self._id)
         if hasattr(self.adapter, "on_thread_subscribe") and self.adapter.on_thread_subscribe:  # type: ignore[union-attr]
             await self.adapter.on_thread_subscribe(self._id)  # type: ignore[union-attr]

tests/integration/test_dm_flow.py

@@ -11,6 +11,7 @@
 
 import pytest
 
+from chat_sdk.chat import Chat
 from chat_sdk.testing import create_mock_adapter
 from chat_sdk.types import Message
 
@@ -184,3 +185,64 @@ async def handler(thread, message, channel=None, context=None):
         await chat.handle_incoming_message(adapter, dm_thread_id, msg)
 
         assert len(calls) == 0
+
+    @pytest.mark.asyncio
+    async def test_dm_handler_runs_before_pattern_handler(self):
+        """DM handler takes precedence over ``on_message`` pattern handlers.
+
+        Mirrors the routing-precedence clarification in vercel/chat#491 — DM
+        handlers run before subscribed/mention/pattern handlers when registered.
+        Without this precedence a DM whose text matches a registered pattern
+        would fire both handlers (or only the pattern handler), silently
+        breaking DM-only flows.
+        """
+        chat, adapters, state = await create_chat()
+        adapter = adapters["slack"]
+        dm_calls: list[Message] = []
+        pattern_calls: list[Message] = []
+
+        @chat.on_direct_message
+        async def dm_handler(thread, message, channel=None, context=None):
+            dm_calls.append(message)
+
+        @chat.on_message(r"^!help")
+        async def pattern_handler(thread, message, context=None):
+            pattern_calls.append(message)
+
+        dm_thread_id = "slack:DDMCHAN:"
+        msg = create_msg("!help me please", thread_id=dm_thread_id)
+        await chat.handle_incoming_message(adapter, dm_thread_id, msg)
+
+        assert len(dm_calls) == 1
+        assert dm_calls[0].text == "!help me please"
+        assert pattern_calls == []
+
+
+class TestDMRoutingDocs:
+    """Lock in the precedence-clarification docstrings ported from vercel/chat#491.
+
+    The runtime routing was already correct in the Python port (see
+    ``Chat._handle_incoming_message``: DM handlers run before
+    subscribed/mention/pattern). These checks fail if a future doc rewrite drops
+    the precedence wording, which would let the docs drift out of sync with
+    upstream's clarified contract again (the original issue closed by #491).
+    """
+
+    def test_on_direct_message_docstring_documents_precedence(self):
+        """``Chat.on_direct_message`` docstring states DM handlers run first."""
+        doc = Chat.on_direct_message.__doc__ or ""
+        assert "before" in doc.lower()
+        assert "on_subscribed_message" in doc
+        assert "on_mention" in doc
+        # Falls-through-when-unregistered carve-out preserved.
+        assert "backward compatibility" in doc
+
+    def test_thread_subscribe_docstring_documents_dm_carveout(self):
+        """``ThreadImpl.subscribe`` docstring covers the DM precedence carve-out."""
+        from chat_sdk.thread import ThreadImpl
+
+        doc = ThreadImpl.subscribe.__doc__ or ""
+        assert "non-DM" in doc
+        assert "on_direct_message" in doc
+        # Pre-existing invariant: initial subscribing message does NOT fire.
+        assert "NOT fire" in doc