feat(client): AsyncClient.stream() context manager

Adds AsyncClient.stream(method, url, **kwargs) as a
@contextlib.asynccontextmanager method on the client. Mirrors
httpx2.AsyncClient.stream() but auto-raises StatusError subclasses
on 4xx/5xx (consistent with client.get/post/etc.) with body
pre-read so exc.response.content is accessible.

Bypasses the middleware chain (v1 design decision — revisit if user
feedback warrants). Uses the shared _httpx2_exception_mapper and
_raise_on_status_error helpers extracted in the earlier refactor
commit, so dispatch logic stays in lockstep with _terminal.

Body consumption errors during 'async for chunk in response.aiter_bytes()'
propagate through the yield and get mapped to httpware exceptions
consistently.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: lesnik512

src/httpware/client.py

@@ -688,6 +688,66 @@ async def request(  # noqa: PLR0913 — mirrors httpx2 per-method signatures
             response_model=response_model,
         )
 
+    @contextlib.asynccontextmanager
+    async def stream(  # noqa: PLR0913, C901 — mirrors httpx2 per-method signatures; kwargs-forwarding complexity is structural
+        self,
+        method: str,
+        url: str,
+        *,
+        params: typing.Any | None = None,
+        headers: typing.Any | None = None,
+        cookies: typing.Any | None = None,
+        timeout: typing.Any = httpx2.USE_CLIENT_DEFAULT,
+        extensions: typing.Any | None = None,
+        json: typing.Any | None = None,
+        content: typing.Any | None = None,
+        data: typing.Any | None = None,
+        files: typing.Any | None = None,
+    ) -> AsyncIterator[httpx2.Response]:
+        """Stream an HTTP response. Bypasses the middleware chain.
+
+        Yields an httpx2.Response; consume the body via response.aiter_bytes(),
+        response.aiter_text(), response.aiter_lines(), or response.aiter_raw().
+        The body is NOT pre-read for 2xx/3xx (streaming preserved); the response
+        is closed when the context exits.
+
+        Bypasses the middleware chain (no Retry, no Bulkhead, no user-installed
+        middleware) for v1 — see planning/specs/2026-06-05-streaming-design.md.
+
+        Auto-raises StatusError subclasses on 4xx/5xx (NotFoundError,
+        ServiceUnavailableError, etc.) — consistent with client.get()/post()/etc.
+        On error the response body is pre-read so exc.response.content is
+        accessible. You lose the streaming property on errors; rare in practice.
+
+        Maps httpx2 exceptions raised during the request OR body consumption to
+        httpware exceptions via _httpx2_exception_mapper.
+        """
+        kwargs: dict[str, typing.Any] = {}
+        if params is not None:
+            kwargs["params"] = params
+        if headers is not None:
+            kwargs["headers"] = headers
+        if cookies is not None:
+            kwargs["cookies"] = cookies
+        if timeout is not httpx2.USE_CLIENT_DEFAULT:
+            kwargs["timeout"] = timeout
+        if extensions is not None:
+            kwargs["extensions"] = extensions
+        if json is not None:
+            kwargs["json"] = json
+        if content is not None:
+            kwargs["content"] = content
+        if data is not None:
+            kwargs["data"] = data
+        if files is not None:
+            kwargs["files"] = files
+
+        async with _httpx2_exception_mapper(), self._httpx2_client.stream(method, url, **kwargs) as response:
+            if HTTPStatus.BAD_REQUEST <= response.status_code < 600:  # noqa: PLR2004 — 600 is the synthetic upper bound for 5xx
+                await response.aread()  # pre-read body so exc.response.content works
+                _raise_on_status_error(response)
+            yield response
+
     async def __aenter__(self) -> typing.Self:
         """Enter the async context manager; return self."""
         return self