react: add TransportProvider, make useClientTransport a context reader

Previously, useClientTransport was a factory hook: callers were
responsible for obtaining a channel via useChannel, passing it along
with codec and other options, and threading the resulting transport
instance through props to every consumer component.

This change introduces TransportProvider<TEvent, TMessage>, which
centralises channel setup and transport creation. The provider wraps
ChannelProvider internally, co-locates channel and transport lifecycle,
and registers the transport in a React context.

useClientTransport is now a thin context reader.

- src/react/contexts/transport-context.ts: new context (Record-based)
- src/react/contexts/transport-provider.tsx: new provider, two-component
  pattern so useChannel is called inside ChannelProvider's subtree
- src/react/use-client-transport.ts: rewritten as context reader
- Both demos updated to wrap at page level with TransportProvider
- All docs updated to the new API
- Tests rewritten: transport-provider.test.ts (new, 8 tests),
  use-client-transport.test.ts (context-based, no transport creation)

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

Author: ttypic

README.md

@@ -143,15 +143,13 @@ export async function POST(req: Request) {
 'use client';
 
 import { useChat } from '@ai-sdk/react';
-import { useChannel } from 'ably/react';
-import { useClientTransport, useActiveTurns, useView } from '@ably/ai-transport/react';
+import type * as AI from 'ai';
+import { TransportProvider, useClientTransport, useActiveTurns, useView } from '@ably/ai-transport/react';
 import { useChatTransport, useMessageSync } from '@ably/ai-transport/vercel/react';
 import { UIMessageCodec } from '@ably/ai-transport/vercel';
 
-function Chat({ chatId, clientId }: { chatId: string; clientId?: string }) {
-  const { channel } = useChannel({ channelName: chatId });
-
-  const transport = useClientTransport({ channel, codec: UIMessageCodec, clientId });
+function ChatInner({ chatId }: { chatId: string }) {
+  const transport = useClientTransport<AI.UIMessageChunk, AI.UIMessage>();
   const chatTransport = useChatTransport(transport);
 
   const { messages, setMessages, sendMessage, stop } = useChat({
@@ -162,7 +160,7 @@ function Chat({ chatId, clientId }: { chatId: string; clientId?: string }) {
   useMessageSync(transport, setMessages);
 
   const activeTurns = useActiveTurns(transport);
-  const view = useView(transport, { limit: 30 });
+  useView(transport, { limit: 30 });
 
   return (
     <div>
@@ -176,19 +174,22 @@ function Chat({ chatId, clientId }: { chatId: string; clientId?: string }) {
         }}
       >
         {activeTurns.size > 0 ? (
-          <button
-            type="button"
-            onClick={stop}
-          >
-            Stop
-          </button>
+          <button type="button" onClick={stop}>Stop</button>
         ) : (
           <button type="submit">Send</button>
         )}
       </form>
     </div>
   );
 }
+
+function Chat({ chatId, clientId }: { chatId: string; clientId?: string }) {
+  return (
+    <TransportProvider channelName={chatId} codec={UIMessageCodec} clientId={clientId}>
+      <ChatInner chatId={chatId} />
+    </TransportProvider>
+  );
+}
 ```
 
 ### Authentication

ably-common

@@ -1,10 +1,9 @@
 'use client';
 
 import { useChat } from '@ai-sdk/react';
-import { useChannel } from 'ably/react';
+import type * as AI from 'ai';
 import { useClientTransport, useActiveTurns, useView, useAblyMessages } from '@ably/ai-transport/react';
 import { useChatTransport, useMessageSync } from '@ably/ai-transport/vercel/react';
-import { UIMessageCodec } from '@ably/ai-transport/vercel';
 import { useState } from 'react';
 import { MessageList } from './components/message-list';
 import { DebugPane } from './components/debug-pane';
@@ -15,10 +14,8 @@ import { useClientTools } from './hooks/use-client-tools';
 // ---------------------------------------------------------------------------
 
 export function Chat({ chatId, clientId, historyLimit }: { chatId: string; clientId?: string; historyLimit?: number }) {
-  const { channel } = useChannel({ channelName: chatId });
-
-  // Create transport immediately (subscribes before attach — RTL7g)
-  const transport = useClientTransport({ channel, codec: UIMessageCodec, clientId, body: () => ({ id: chatId }) });
+  // Transport is created by TransportProvider in page.tsx
+  const transport = useClientTransport<AI.UIMessageChunk, AI.UIMessage>();
   const chatTransport = useChatTransport(transport);
 
   const {

demo/vercel/react/use-chat/src/app/chat.tsx

@@ -1,7 +1,8 @@
 'use client';
 
 import { Providers, useAblyReady } from './providers';
-import { ChannelProvider } from 'ably/react';
+import { TransportProvider } from '@ably/ai-transport/react';
+import { UIMessageCodec } from '@ably/ai-transport/vercel';
 import { Chat } from './chat';
 import { useSearchParams } from 'next/navigation';
 import { Suspense } from 'react';
@@ -16,13 +17,17 @@ function ChatWhenReady({ channelName, clientId, limit }: { channelName: string;
   }
 
   return (
-    <ChannelProvider channelName={channelName}>
+    <TransportProvider
+      channelName={channelName}
+      codec={UIMessageCodec}
+      clientId={clientId}
+    >
       <Chat
         chatId={channelName}
         clientId={clientId}
         historyLimit={limit}
       />
-    </ChannelProvider>
+    </TransportProvider>
   );
 }
 

demo/vercel/react/use-chat/src/app/page.tsx

@@ -1,9 +1,8 @@
 'use client';
 
 import { useState, useCallback } from 'react';
-import { useChannel } from 'ably/react';
+import type * as AI from 'ai';
 import { useClientTransport, useCreateView, useActiveTurns, useView, useAblyMessages } from '@ably/ai-transport/react';
-import { UIMessageCodec } from '@ably/ai-transport/vercel';
 
 import { userMessage } from '../helpers';
 import { useClientTools } from '../hooks/use-client-tools';
@@ -30,16 +29,10 @@ interface ChatProps {
 }
 
 export function Chat({ chatId, clientId, historyLimit }: ChatProps) {
-  const { channel } = useChannel({ channelName: chatId });
+  // Transport is created by TransportProvider in page.tsx
+  const transport = useClientTransport<AI.UIMessageChunk, AI.UIMessage>(chatId);
   const [split, setSplit] = useState(false);
 
-  const transport = useClientTransport({
-    channel,
-    codec: UIMessageCodec,
-    clientId,
-    body: () => ({ id: chatId }),
-  });
-
   const limit = historyLimit ?? 30;
   const view = useView(transport, { limit });
   const splitView = useCreateView(split ? transport : undefined, { limit });

demo/vercel/react/use-client-transport/src/app/components/chat.tsx

@@ -1,7 +1,8 @@
 'use client';
 
 import { Providers, useAblyReady } from './providers';
-import { ChannelProvider } from 'ably/react';
+import { TransportProvider } from '@ably/ai-transport/react';
+import { UIMessageCodec } from '@ably/ai-transport/vercel';
 import { Chat } from './components/chat';
 import { useSearchParams } from 'next/navigation';
 import { Suspense } from 'react';
@@ -16,13 +17,18 @@ function ChatWhenReady({ channelName, clientId, limit }: { channelName: string;
   }
 
   return (
-    <ChannelProvider channelName={channelName}>
+    <TransportProvider
+      channelName={channelName}
+      codec={UIMessageCodec}
+      clientId={clientId}
+      body={() => ({ id: channelName })}
+    >
       <Chat
         chatId={channelName}
         clientId={clientId}
         historyLimit={limit}
       />
-    </ChannelProvider>
+    </TransportProvider>
   );
 }
 

demo/vercel/react/use-client-transport/src/app/page.tsx

@@ -1,7 +1,11 @@
 {
   "compilerOptions": {
     "target": "ES2017",
-    "lib": ["dom", "dom.iterable", "esnext"],
+    "lib": [
+      "dom",
+      "dom.iterable",
+      "esnext"
+    ],
     "allowJs": true,
     "skipLibCheck": true,
     "strict": true,
@@ -11,17 +15,27 @@
     "moduleResolution": "bundler",
     "resolveJsonModule": true,
     "isolatedModules": true,
-    "jsx": "react-jsx",
+    "jsx": "preserve",
     "incremental": true,
     "plugins": [
       {
         "name": "next"
       }
     ],
     "paths": {
-      "@/*": ["./src/*"]
+      "@/*": [
+        "./src/*"
+      ]
     }
   },
-  "include": ["**/*.ts", "**/*.tsx", "next-env.d.ts", ".next/types/**/*.ts", ".next/dev/types/**/*.ts"],
-  "exclude": ["node_modules"]
+  "include": [
+    "**/*.ts",
+    "**/*.tsx",
+    "next-env.d.ts",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
 }

demo/vercel/react/use-client-transport/tsconfig.json

@@ -77,13 +77,20 @@ view.on('update', () => {
 // (e.g. Vercel's useChat), but most apps use the view instead
 ```
 
-In React, the hooks handle subscriptions and state management:
+In React, `TransportProvider` creates the transport and `useClientTransport` reads it from context:
 
 ```typescript
-import { useClientTransport, useView } from '@ably/ai-transport/react';
+import { TransportProvider, useClientTransport, useView } from '@ably/ai-transport/react';
 import { UIMessageCodec } from '@ably/ai-transport/vercel';
+import type * as AI from 'ai';
 
-const transport = useClientTransport({ channel, codec: UIMessageCodec, clientId });
+// In your layout or page component:
+<TransportProvider channelName="ai:demo" codec={UIMessageCodec} clientId={clientId}>
+  <Chat />
+</TransportProvider>
+
+// Inside Chat:
+const transport = useClientTransport<AI.UIMessageChunk, AI.UIMessage>();
 const { nodes, send } = useView(transport);
 ```
 

docs/concepts/transport.md

@@ -13,12 +13,16 @@ All clients subscribe to the same Ably channel. The transport distinguishes betw
 
 No special API is needed. Connect two clients to the same channel name, and messages sync automatically:
 
-```typescript
-// Client A
-const transportA = useClientTransport({ channel, codec: UIMessageCodec, clientId: 'user-a' });
-
-// Client B (different browser tab, device, or user)
-const transportB = useClientTransport({ channel, codec: UIMessageCodec, clientId: 'user-b' });
+```tsx
+// Client A — in its own browser tab
+<TransportProvider channelName="ai:demo" codec={UIMessageCodec} clientId="user-a">
+  <Chat />
+</TransportProvider>
+
+// Client B — in a different browser tab, device, or user session
+<TransportProvider channelName="ai:demo" codec={UIMessageCodec} clientId="user-b">
+  <Chat />
+</TransportProvider>
 
 // When Client A sends a message and the server streams a response,
 // Client B sees both the user message and the assistant response

docs/features/multi-client.md

@@ -19,13 +19,20 @@ The Vercel AI SDK provides model abstraction, streaming primitives, and React ho
 
 Wrap the transport in a `ChatTransport` adapter and pass it to Vercel's `useChat()`. Message state is managed by `useChat()` - the transport delivers messages over Ably instead of HTTP.
 
-```typescript
-import { useClientTransport } from '@ably/ai-transport/react';
+```tsx
+import { TransportProvider, useClientTransport } from '@ably/ai-transport/react';
 import { useChatTransport, useMessageSync } from '@ably/ai-transport/vercel/react';
 import { UIMessageCodec } from '@ably/ai-transport/vercel';
 import { useChat } from '@ai-sdk/react';
+import type * as AI from 'ai';
+
+// Wrap your component tree with TransportProvider
+<TransportProvider channelName={chatId} codec={UIMessageCodec} clientId={clientId}>
+  <ChatInner chatId={chatId} />
+</TransportProvider>
 
-const transport = useClientTransport({ channel, codec: UIMessageCodec, clientId });
+// Inside ChatInner:
+const transport = useClientTransport<AI.UIMessageChunk, AI.UIMessage>();
 const chatTransport = useChatTransport(transport);
 
 const { messages, setMessages, sendMessage, stop } = useChat({
@@ -37,17 +44,28 @@ const { messages, setMessages, sendMessage, stop } = useChat({
 useMessageSync(transport, setMessages);
 ```
 
-`useChatTransport()` wraps the core transport into the `ChatTransport` interface that `useChat()` expects. `useMessageSync()` pushes the transport's authoritative message list into `useChat()`'s state - this is how messages from other clients appear.
+`TransportProvider` creates the transport and wraps children with `ChannelProvider` internally. `useClientTransport()` reads it from context. `useChatTransport()` wraps the core transport into the `ChatTransport` interface that `useChat()` expects. `useMessageSync()` pushes the transport's authoritative message list into `useChat()`'s state - this is how messages from other clients appear.
 
 ### Generic hooks path (more control)
 
 Use the generic React hooks directly. You manage message state through the transport's conversation tree instead of `useChat()`.
 
-```typescript
-import { useClientTransport, useView, useActiveTurns } from '@ably/ai-transport/react';
+```tsx
+import {
+  TransportProvider,
+  useClientTransport,
+  useView,
+  useActiveTurns} from '@ably/ai-transport/react';
 import { UIMessageCodec } from '@ably/ai-transport/vercel';
+import type * as AI from 'ai';
+
+// Wrap your component tree with TransportProvider
+<TransportProvider channelName={chatId} codec={UIMessageCodec} clientId={clientId}>
+  <ChatInner />
+</TransportProvider>
 
-const transport = useClientTransport({ channel, codec: UIMessageCodec, clientId });
+// Inside ChatInner:
+const transport = useClientTransport<AI.UIMessageChunk, AI.UIMessage>();
 const {
   nodes,
   hasOlder,