From 8d39c68bc366359cb0dc165453d9ab0af800da07 Mon Sep 17 00:00:00 2001
From: Andrew Bulat <andrii.bulat@gmail.com>
Date: Tue, 21 Jul 2026 15:07:07 +0100
Subject: [PATCH] docs(ai-transport): migrate UIMessageCodec to
 createUIMessageCodec
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

ably-ai-transport-js#267 (AIT-1039) removes the UIMessageCodec value export
from @ably/ai-transport/vercel in favour of the createUIMessageCodec() factory,
now generic over the AI SDK's UIMessage <metadata, data-part, tool> parameters.
The change ships in the SDK 0.6.0 release, so the docs move to the factory
across every AI Transport page.

Stacked on #3471 (zak/docs-steering), which introduces the steering docs and
already bumps the documented AIT SDK version to 0.6; this migrates every
UIMessageCodec usage — including the new steering examples and the
interruption-and-steering page — to createUIMessageCodec().

React provider props and multi-call snippets hold a stable codec instance;
one-off sends and per-request agent handlers call the factory inline. The
Vercel codec reference page is reframed around the factory (a fresh, stateless
value per call), and a new "Typed messages" section on the Vercel AI SDK UI
page documents threading concrete UIMessage types through the imperative path.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 src/pages/docs/ai-transport/api/index.mdx     |  6 ++--
 .../api/javascript/core/agent-session.mdx     | 12 +++----
 .../api/javascript/core/client-session.mdx    | 16 ++++-----
 .../api/javascript/core/codec.mdx             |  2 +-
 .../api/javascript/vercel/chat-transport.mdx  | 12 +++----
 .../api/javascript/vercel/codec.mdx           | 36 +++++++++++--------
 .../ai-transport/api/react/core/providers.mdx | 10 +++---
 .../react/vercel/chat-transport-provider.mdx  |  6 ++--
 .../docs/ai-transport/concepts/codecs.mdx     |  4 +--
 .../ai-transport/concepts/connections.mdx     |  4 +--
 src/pages/docs/ai-transport/concepts/runs.mdx |  6 ++--
 .../docs/ai-transport/concepts/sessions.mdx   |  2 +-
 .../ai-transport/features/agent-presence.mdx  |  4 +--
 .../features/chain-of-thought.mdx             |  2 +-
 .../features/concurrent-turns.mdx             | 16 ++++-----
 .../ai-transport/features/double-texting.mdx  | 10 +++---
 .../features/durable-execution.mdx            |  4 +--
 .../features/interruption-and-steering.mdx    | 10 +++---
 .../ai-transport/features/liveobjects.mdx     |  4 +--
 .../ai-transport/features/multi-device.mdx    |  4 +--
 .../features/push-notifications.mdx           |  2 +-
 .../frameworks/vercel-ai-sdk-core.mdx         |  8 ++---
 .../frameworks/vercel-ai-sdk-ui.mdx           | 23 +++++++++++-
 .../getting-started/authentication.mdx        |  7 ++--
 .../ai-transport/getting-started/core-sdk.mdx | 15 ++++----
 .../getting-started/vercel-ai-sdk.mdx         |  2 +-
 .../internals/codec-architecture.mdx          |  2 +-
 27 files changed, 131 insertions(+), 98 deletions(-)

diff --git a/src/pages/docs/ai-transport/api/index.mdx b/src/pages/docs/ai-transport/api/index.mdx
index 944ad38b70..3a428ce1ae 100644
--- a/src/pages/docs/ai-transport/api/index.mdx
+++ b/src/pages/docs/ai-transport/api/index.mdx
@@ -37,7 +37,7 @@ See the individual reference pages for the full API.
 | --- | --- | --- |
 | Core | `@ably/ai-transport` | `createClientSession`, `createAgentSession`, `Invocation`, `Codec` interface |
 | React | `@ably/ai-transport/react` | `ClientSessionProvider`, `useClientSession`, `useView`, `useTree`, `useCreateView`, `useMessagesWithSeed`, `useAblyMessages`, `createSessionHooks` |
-| Vercel | `@ably/ai-transport/vercel` | `UIMessageCodec`, Vercel-bound `createClientSession` and `createAgentSession`, `createChatTransport`, `vercelRunOutcome` |
+| Vercel | `@ably/ai-transport/vercel` | `createUIMessageCodec`, Vercel-bound `createClientSession` and `createAgentSession`, `createChatTransport`, `vercelRunOutcome` |
 | Vercel React | `@ably/ai-transport/vercel/react` | `ChatTransportProvider`, `useChatTransport`, `useMessageSync`, `useMessagesWithSeed`, plus the Vercel-baked re-exports of `ClientSessionProvider`, `useClientSession`, `useView`, `useCreateView`, `useTree`, and `useAblyMessages` |
 
 <Aside data-type='note'>
@@ -82,8 +82,8 @@ The Vercel entry points re-export the core factories with the codec pre-bound. I
     link: '/docs/ai-transport/api/javascript/vercel/chat-transport',
   },
   {
-    title: 'UIMessageCodec',
-    description: 'The pre-built codec for the Vercel AI SDK and its type parameters.',
+    title: 'createUIMessageCodec',
+    description: 'The factory for the pre-built Vercel AI SDK codec, and its type parameters.',
     image: 'icon-tech-vercel',
     link: '/docs/ai-transport/api/javascript/vercel/codec',
   },
diff --git a/src/pages/docs/ai-transport/api/javascript/core/agent-session.mdx b/src/pages/docs/ai-transport/api/javascript/core/agent-session.mdx
index ce997ee451..46778b25e3 100644
--- a/src/pages/docs/ai-transport/api/javascript/core/agent-session.mdx
+++ b/src/pages/docs/ai-transport/api/javascript/core/agent-session.mdx
@@ -15,7 +15,7 @@ Construct one with `createAgentSession` from the core entry point. For Vercel `U
 ```javascript
 import * as Ably from 'ably';
 import { createAgentSession, Invocation } from '@ably/ai-transport';
-import { UIMessageCodec } from '@ably/ai-transport/vercel';
+import { createUIMessageCodec } from '@ably/ai-transport/vercel';
 
 const ably = new Ably.Realtime({ key: process.env.ABLY_API_KEY });
 
@@ -24,7 +24,7 @@ const invocation = Invocation.fromJSON(await req.json());
 const session = createAgentSession({
   client: ably,
   channelName: invocation.sessionName,
-  codec: UIMessageCodec,
+  codec: createUIMessageCodec(),
 });
 
 await session.connect();
@@ -54,14 +54,14 @@ Construct an `AgentSession` bound to an Ably channel. The session does not attac
 ```javascript
 import * as Ably from 'ably';
 import { createAgentSession } from '@ably/ai-transport';
-import { UIMessageCodec } from '@ably/ai-transport/vercel';
+import { createUIMessageCodec } from '@ably/ai-transport/vercel';
 
 const ably = new Ably.Realtime({ key: process.env.ABLY_API_KEY });
 
 const session = createAgentSession({
   client: ably,
   channelName: 'conversation-42',
-  codec: UIMessageCodec,
+  codec: createUIMessageCodec(),
 });
 ```
 </Code>
@@ -609,7 +609,7 @@ An HTTP handler that sets up the session, creates a Run, rebuilds the conversati
 ```javascript
 import * as Ably from 'ably';
 import { createAgentSession, Invocation } from '@ably/ai-transport';
-import { UIMessageCodec } from '@ably/ai-transport/vercel';
+import { createUIMessageCodec } from '@ably/ai-transport/vercel';
 
 const ably = new Ably.Realtime({ key: process.env.ABLY_API_KEY });
 
@@ -619,7 +619,7 @@ export async function POST(req: Request) {
   const session = createAgentSession({
     client: ably,
     channelName: invocation.sessionName,
-    codec: UIMessageCodec,
+    codec: createUIMessageCodec(),
   });
 
   await session.connect();
diff --git a/src/pages/docs/ai-transport/api/javascript/core/client-session.mdx b/src/pages/docs/ai-transport/api/javascript/core/client-session.mdx
index 52082d149d..01112c78f1 100644
--- a/src/pages/docs/ai-transport/api/javascript/core/client-session.mdx
+++ b/src/pages/docs/ai-transport/api/javascript/core/client-session.mdx
@@ -15,14 +15,14 @@ Construct one with `createClientSession` from the core entry point. For Vercel `
 ```javascript
 import * as Ably from 'ably';
 import { createClientSession } from '@ably/ai-transport';
-import { UIMessageCodec } from '@ably/ai-transport/vercel';
+import { createUIMessageCodec } from '@ably/ai-transport/vercel';
 
 const ably = new Ably.Realtime({ authUrl: '/api/auth/token' });
 
 const session = createClientSession({
   client: ably,
   channelName: 'conversation-42',
-  codec: UIMessageCodec,
+  codec: createUIMessageCodec(),
 });
 
 await session.connect();
@@ -83,14 +83,14 @@ Construct a `ClientSession` bound to an Ably channel. The session does not attac
 ```javascript
 import * as Ably from 'ably';
 import { createClientSession } from '@ably/ai-transport';
-import { UIMessageCodec } from '@ably/ai-transport/vercel';
+import { createUIMessageCodec } from '@ably/ai-transport/vercel';
 
 const ably = new Ably.Realtime({ authUrl: '/api/auth/token' });
 
 const session = createClientSession({
   client: ably,
   channelName: 'conversation-42',
-  codec: UIMessageCodec,
+  codec: createUIMessageCodec(),
 });
 ```
 </Code>
@@ -224,7 +224,7 @@ Publish a codec input event that targets this Run. The steering message carries
 
 <Code>
 ```javascript
-const { published, outcome } = activeRun.steer(UIMessageCodec.createUserMessage({
+const { published, outcome } = activeRun.steer(createUIMessageCodec().createUserMessage({
   id: crypto.randomUUID(),
   role: 'user',
   parts: [{ type: 'text', text: 'Also include vegan options.' }],
@@ -342,14 +342,14 @@ End-to-end usage covering construction, connect, send, and teardown.
 ```javascript
 import * as Ably from 'ably';
 import { createClientSession } from '@ably/ai-transport';
-import { UIMessageCodec } from '@ably/ai-transport/vercel';
+import { createUIMessageCodec } from '@ably/ai-transport/vercel';
 
 const ably = new Ably.Realtime({ authUrl: '/api/auth/token' });
 
 const session = createClientSession({
   client: ably,
   channelName: 'conversation-42',
-  codec: UIMessageCodec,
+  codec: createUIMessageCodec(),
 });
 
 await session.connect();
@@ -358,7 +358,7 @@ session.view.on('update', () => {
   render(session.view.getMessages().map(({ message }) => message));
 });
 
-const clientRun = await session.view.send(UIMessageCodec.createUserMessage({
+const clientRun = await session.view.send(createUIMessageCodec().createUserMessage({
   id: crypto.randomUUID(),
   role: 'user',
   parts: [{ type: 'text', text: 'Plan a 3-day trip to Lisbon.' }],
diff --git a/src/pages/docs/ai-transport/api/javascript/core/codec.mdx b/src/pages/docs/ai-transport/api/javascript/core/codec.mdx
index d895c12e65..44b9f7d0a6 100644
--- a/src/pages/docs/ai-transport/api/javascript/core/codec.mdx
+++ b/src/pages/docs/ai-transport/api/javascript/core/codec.mdx
@@ -9,7 +9,7 @@ redirect_from:
 
 The `Codec` interface is the bridge between an AI framework and Ably channel messages. It describes the wire as a flat stream of input and output events and folds those events into a per-Run projection that the SDK extracts messages from for the conversation tree.
 
-Implement `Codec<TInput, TOutput, TProjection, TMessage>` to integrate any AI framework with AI Transport. The SDK ships [`UIMessageCodec`](/docs/ai-transport/api/javascript/vercel/codec) for the Vercel AI SDK. For other frameworks, implement the methods below.
+Implement `Codec<TInput, TOutput, TProjection, TMessage>` to integrate any AI framework with AI Transport. The SDK ships the Vercel codec via [`createUIMessageCodec()`](/docs/ai-transport/api/javascript/vercel/codec) for the Vercel AI SDK. For other frameworks, implement the methods below.
 
 <Code>
 ```typescript
diff --git a/src/pages/docs/ai-transport/api/javascript/vercel/chat-transport.mdx b/src/pages/docs/ai-transport/api/javascript/vercel/chat-transport.mdx
index 127ec63048..2b40e470ca 100644
--- a/src/pages/docs/ai-transport/api/javascript/vercel/chat-transport.mdx
+++ b/src/pages/docs/ai-transport/api/javascript/vercel/chat-transport.mdx
@@ -1,13 +1,13 @@
 ---
 title: "ChatTransport"
 meta_description: "API reference for the AI Transport Vercel ChatTransport adapter and the Vercel-bound createClientSession and createAgentSession factories."
-meta_keywords: "Vercel AI SDK, AI Transport, ChatTransport, createChatTransport, createClientSession, createAgentSession, UIMessageCodec, Ably"
+meta_keywords: "Vercel AI SDK, AI Transport, ChatTransport, createChatTransport, createClientSession, createAgentSession, createUIMessageCodec, Ably"
 redirect_from:
   - /docs/ai-transport/api-reference/vercel
   - /docs/ai-transport/api/javascript/vercel
 ---
 
-The Vercel entry point pre-binds the [`UIMessageCodec`](/docs/ai-transport/api/javascript/vercel/codec) and exposes a `ChatTransport` adapter that satisfies the contract Vercel AI SDK's `useChat` hook expects. Use these factories whenever you build a chat UI on top of `useChat` so you do not have to wire the codec yourself.
+The Vercel entry point pre-binds the [Vercel codec](/docs/ai-transport/api/javascript/vercel/codec) and exposes a `ChatTransport` adapter that satisfies the contract Vercel AI SDK's `useChat` hook expects. Use these factories whenever you build a chat UI on top of `useChat` so you do not have to wire the codec yourself.
 
 <Code>
 ```javascript
@@ -33,7 +33,7 @@ React-side wiring (`ChatTransportProvider`, `useChatTransport`, `useMessageSync`
 
 <MethodSignature>{`function createClientSession(options: VercelClientSessionOptions): ClientSession<VercelInput, VercelOutput, VercelProjection, UIMessage>`}</MethodSignature>
 
-A pre-bound version of the core [`createClientSession`](/docs/ai-transport/api/javascript/core/client-session#constructor) with `codec: UIMessageCodec` already supplied. The `api` default is set on [`createChatTransport`](#create-chat-transport), not here.
+A pre-bound version of the core [`createClientSession`](/docs/ai-transport/api/javascript/core/client-session#constructor) with the Vercel codec already supplied. The `api` default is set on [`createChatTransport`](#create-chat-transport), not here.
 
 <Code>
 ```javascript
@@ -65,13 +65,13 @@ const session = createClientSession({
 
 ### Returns <a id="create-client-session-returns"/>
 
-`ClientSession<VercelInput, VercelOutput, VercelProjection, UIMessage>`. A client session whose codec is pre-bound to `UIMessageCodec`.
+`ClientSession<VercelInput, VercelOutput, VercelProjection, UIMessage>`. A client session whose codec is pre-bound to the Vercel codec.
 
 ## Create a Vercel agent session <a id="create-agent-session"/>
 
 <MethodSignature>{`function createAgentSession(options: VercelAgentSessionOptions): AgentSession<VercelOutput, VercelProjection, UIMessage>`}</MethodSignature>
 
-A pre-bound version of the core [`createAgentSession`](/docs/ai-transport/api/javascript/core/agent-session#constructor) with `codec: UIMessageCodec` already supplied. Construct one inside your HTTP handler when the request arrives.
+A pre-bound version of the core [`createAgentSession`](/docs/ai-transport/api/javascript/core/agent-session#constructor) with the Vercel codec already supplied. Construct one inside your HTTP handler when the request arrives.
 
 <Code>
 ```javascript
@@ -108,7 +108,7 @@ Subscribe to non-fatal session-level errors with [`session.on('error')`](/docs/a
 
 ### Returns <a id="create-agent-session-returns"/>
 
-`AgentSession<VercelOutput, VercelProjection, UIMessage>`. An agent session whose codec is pre-bound to `UIMessageCodec`.
+`AgentSession<VercelOutput, VercelProjection, UIMessage>`. An agent session whose codec is pre-bound to the Vercel codec.
 
 ## Create a chat transport <a id="create-chat-transport"/>
 
diff --git a/src/pages/docs/ai-transport/api/javascript/vercel/codec.mdx b/src/pages/docs/ai-transport/api/javascript/vercel/codec.mdx
index 59fbca5cdb..339787ed13 100644
--- a/src/pages/docs/ai-transport/api/javascript/vercel/codec.mdx
+++ b/src/pages/docs/ai-transport/api/javascript/vercel/codec.mdx
@@ -1,25 +1,26 @@
 ---
-title: "UIMessageCodec"
-meta_description: "API reference for UIMessageCodec, the pre-built AI Transport codec for the Vercel AI SDK."
-meta_keywords: "Vercel AI SDK, AI Transport, UIMessageCodec, VercelInput, VercelOutput, VercelProjection, codec, Ably"
+title: "createUIMessageCodec"
+meta_description: "API reference for createUIMessageCodec, the factory for the pre-built AI Transport codec for the Vercel AI SDK."
+meta_keywords: "Vercel AI SDK, AI Transport, createUIMessageCodec, UIMessageCodec, VercelInput, VercelOutput, VercelProjection, codec, Ably"
 ---
 
-`UIMessageCodec` is the pre-built codec for the Vercel AI SDK. It implements [`Codec<VercelInput, VercelOutput, VercelProjection, UIMessage>`](/docs/ai-transport/api/javascript/core/codec) so a session can encode `UIMessageChunk` events out and decode them back into `UIMessage` objects without a custom implementation.
+`createUIMessageCodec()` returns the pre-built codec for the Vercel AI SDK. The returned codec implements [`Codec<VercelInput, VercelOutput, VercelProjection, UIMessage>`](/docs/ai-transport/api/javascript/core/codec) so a session can encode `UIMessageChunk` events out and decode them back into `UIMessage` objects without a custom implementation.
 
-You rarely import `UIMessageCodec` directly. The Vercel-pre-bound [`createClientSession`](/docs/ai-transport/api/javascript/vercel/chat-transport#create-client-session) and [`createAgentSession`](/docs/ai-transport/api/javascript/vercel/chat-transport#create-agent-session) already supply it. Import it explicitly when you build a codec wrapper, run the encoder or decoder outside of a session, or compose `UIMessageCodec` into a different codec.
+You rarely call `createUIMessageCodec()` yourself. The Vercel-pre-bound [`createClientSession`](/docs/ai-transport/api/javascript/vercel/chat-transport#create-client-session) and [`createAgentSession`](/docs/ai-transport/api/javascript/vercel/chat-transport#create-agent-session) already supply the codec. Call it explicitly when you build a codec wrapper, run the encoder or decoder outside of a session, or compose the codec into a different codec.
 
 <Code>
 ```javascript
-import { UIMessageCodec } from '@ably/ai-transport/vercel';
+import { createUIMessageCodec } from '@ably/ai-transport/vercel';
 
-const decoder = UIMessageCodec.createDecoder();
-const projection = UIMessageCodec.init();
+const codec = createUIMessageCodec();
+const decoder = codec.createDecoder();
+const projection = codec.init();
 ```
 </Code>
 
 ## Properties <a id="properties"/>
 
-`UIMessageCodec` is a value, not a type. It satisfies the full [`Codec`](/docs/ai-transport/api/javascript/core/codec) interface for the Vercel `TInput`, `TOutput`, `TProjection`, and `TMessage` parameters listed below.
+`createUIMessageCodec()` is a factory, not a type. Each call returns a fresh, stateless codec value that satisfies the full [`Codec`](/docs/ai-transport/api/javascript/core/codec) interface for the Vercel `TInput`, `TOutput`, `TProjection`, and `TMessage` parameters listed below. Because the codec is stateless, hold a single instance at module scope (or, in React, `useMemo(() => createUIMessageCodec(), [])`) and reuse it rather than calling the factory inline on every render.
 
 <Table id='UIMessageCodecProperties'>
 
@@ -40,6 +41,10 @@ const projection = UIMessageCodec.init();
 
 ## Type parameters <a id="types"/>
 
+`createUIMessageCodec` is generic over the AI SDK's three `UIMessage` type parameters — `createUIMessageCodec<TMetadata, TDataParts, TTools>()`. Supplying concrete types specialises the codec so `getMessages` (and a session's `view.getMessages()`) return messages whose `metadata`, data parts, and tool parts carry your types instead of the SDK defaults; omitting them preserves the default inference. The same parameters thread through [`createClientSession`](/docs/ai-transport/api/javascript/vercel/chat-transport#create-client-session), [`createAgentSession`](/docs/ai-transport/api/javascript/vercel/chat-transport#create-agent-session), and [`createChatTransport`](/docs/ai-transport/api/javascript/vercel/chat-transport#create-chat-transport). See [Typed messages](/docs/ai-transport/frameworks/vercel-ai-sdk-ui#typed-messages) for the end-to-end pattern.
+
+`VercelInput`, `VercelOutput`, and `VercelProjection` are likewise generic over the same three parameters, each defaulting to the SDK default. The tables below show the default instantiation.
+
 <Table id='VercelInput'>
 
 | Property | Description | Type |
@@ -72,21 +77,22 @@ Decode a single Ably message and fold the resulting events into a fresh projecti
 
 <Code>
 ```javascript
-import { UIMessageCodec } from '@ably/ai-transport/vercel';
+import { createUIMessageCodec } from '@ably/ai-transport/vercel';
 
-const decoder = UIMessageCodec.createDecoder();
-let projection = UIMessageCodec.init();
+const codec = createUIMessageCodec();
+const decoder = codec.createDecoder();
+let projection = codec.init();
 
 channel.subscribe((message) => {
   if (!message.serial) return; // live channel-subscribe messages always carry one
   const { inputs, outputs } = decoder.decode(message);
   for (const input of inputs) {
-    projection = UIMessageCodec.fold(projection, input, { serial: message.serial });
+    projection = codec.fold(projection, input, { serial: message.serial });
   }
   for (const output of outputs) {
-    projection = UIMessageCodec.fold(projection, output, { serial: message.serial });
+    projection = codec.fold(projection, output, { serial: message.serial });
   }
-  render(UIMessageCodec.getMessages(projection).map((entry) => entry.message));
+  render(codec.getMessages(projection).map((entry) => entry.message));
 });
 ```
 </Code>
diff --git a/src/pages/docs/ai-transport/api/react/core/providers.mdx b/src/pages/docs/ai-transport/api/react/core/providers.mdx
index 333312443f..a967093aa9 100644
--- a/src/pages/docs/ai-transport/api/react/core/providers.mdx
+++ b/src/pages/docs/ai-transport/api/react/core/providers.mdx
@@ -16,14 +16,14 @@ Nest multiple providers with distinct `channelName` values to manage more than o
 import * as Ably from 'ably';
 import { AblyProvider } from 'ably/react';
 import { ClientSessionProvider } from '@ably/ai-transport/react';
-import { UIMessageCodec } from '@ably/ai-transport/vercel';
+import { createUIMessageCodec } from '@ably/ai-transport/vercel';
 
 const ably = new Ably.Realtime({ authUrl: '/api/auth/token' });
 
 function App() {
   return (
     <AblyProvider client={ably}>
-      <ClientSessionProvider channelName="conversation-42" codec={UIMessageCodec}>
+      <ClientSessionProvider channelName="conversation-42" codec={createUIMessageCodec()}>
         <Chat />
       </ClientSessionProvider>
     </AblyProvider>
@@ -126,15 +126,15 @@ Nested providers with distinct channel names and a child component that addresse
 import * as Ably from 'ably';
 import { AblyProvider } from 'ably/react';
 import { ClientSessionProvider, useClientSession } from '@ably/ai-transport/react';
-import { UIMessageCodec } from '@ably/ai-transport/vercel';
+import { createUIMessageCodec } from '@ably/ai-transport/vercel';
 
 const ably = new Ably.Realtime({ authUrl: '/api/auth/token' });
 
 function App() {
   return (
     <AblyProvider client={ably}>
-      <ClientSessionProvider channelName="ai:main" codec={UIMessageCodec}>
-        <ClientSessionProvider channelName="ai:aux" codec={UIMessageCodec}>
+      <ClientSessionProvider channelName="ai:main" codec={createUIMessageCodec()}>
+        <ClientSessionProvider channelName="ai:aux" codec={createUIMessageCodec()}>
           <Chat />
         </ClientSessionProvider>
       </ClientSessionProvider>
diff --git a/src/pages/docs/ai-transport/api/react/vercel/chat-transport-provider.mdx b/src/pages/docs/ai-transport/api/react/vercel/chat-transport-provider.mdx
index e4465dcd8a..c1b3d8e813 100644
--- a/src/pages/docs/ai-transport/api/react/vercel/chat-transport-provider.mdx
+++ b/src/pages/docs/ai-transport/api/react/vercel/chat-transport-provider.mdx
@@ -1,13 +1,13 @@
 ---
 title: "ChatTransportProvider"
-meta_description: "API reference for ChatTransportProvider: the Vercel React entry point that wraps a ClientSession in a ChatTransport bound to UIMessageCodec."
+meta_description: "API reference for ChatTransportProvider: the Vercel React entry point that wraps a ClientSession in a ChatTransport bound to the Vercel codec."
 meta_keywords: "AI Transport, React, ChatTransportProvider, ChatTransport, ClientSession, useChat, Vercel AI SDK"
 redirect_from:
   - /docs/ai-transport/api-reference/chat-transport-provider
   - /docs/ai-transport/api/react/chat-transport-provider
 ---
 
-`ChatTransportProvider` is the entry point for the Vercel React integration. It wraps children in a `ClientSessionProvider` bound to `UIMessageCodec`, constructs a [`ChatTransport`](/docs/ai-transport/api/javascript/vercel/chat-transport) over that session, and exposes both through React context. Descendants call [`useChatTransport`](/docs/ai-transport/api/react/vercel/use-chat-transport) to get the transport (and the session) for Vercel `useChat`.
+`ChatTransportProvider` is the entry point for the Vercel React integration. It wraps children in a `ClientSessionProvider` bound to the Vercel codec, constructs a [`ChatTransport`](/docs/ai-transport/api/javascript/vercel/chat-transport) over that session, and exposes both through React context. Descendants call [`useChatTransport`](/docs/ai-transport/api/react/vercel/use-chat-transport) to get the transport (and the session) for Vercel `useChat`.
 
 The Realtime client is read from the surrounding `<AblyProvider>`. The session is created once on first render. The chat transport is recreated only when `chatOptions` changes.
 
@@ -35,7 +35,7 @@ function App() {
 
 ## Props <a id="props"/>
 
-`ChatTransportProviderProps` extends [`ClientSessionProviderProps`](/docs/ai-transport/api/react/core/providers#client-session-provider-props) with the `codec` field omitted (always `UIMessageCodec`) and adds four transport-owned options for the agent-invocation POST. As with `ClientSessionProvider`, the session's identity is taken from the `<AblyProvider>` client's `auth.clientId` (set via the Ably token or `ClientOptions.clientId`).
+`ChatTransportProviderProps` extends [`ClientSessionProviderProps`](/docs/ai-transport/api/react/core/providers#client-session-provider-props) with the `codec` field omitted (always the Vercel codec) and adds four transport-owned options for the agent-invocation POST. As with `ClientSessionProvider`, the session's identity is taken from the `<AblyProvider>` client's `auth.clientId` (set via the Ably token or `ClientOptions.clientId`).
 
 <Table id='ChatTransportProviderProps'>
 
diff --git a/src/pages/docs/ai-transport/concepts/codecs.mdx b/src/pages/docs/ai-transport/concepts/codecs.mdx
index 6041871640..84c8598add 100644
--- a/src/pages/docs/ai-transport/concepts/codecs.mdx
+++ b/src/pages/docs/ai-transport/concepts/codecs.mdx
@@ -76,11 +76,11 @@ const myCodec = {
 ```
 </Code>
 
-Most users don't write a custom codec; the bundled [Vercel `UIMessageCodec`](/docs/ai-transport/api/javascript/vercel/codec) covers the Vercel AI SDK end-to-end. See the [Codec API reference](/docs/ai-transport/api/javascript/core/codec) for the full interface.
+Most users don't write a custom codec; the bundled [Vercel codec](/docs/ai-transport/api/javascript/vercel/codec) covers the Vercel AI SDK end-to-end. See the [Codec API reference](/docs/ai-transport/api/javascript/core/codec) for the full interface.
 
 ## Read next <a id="next"/>
 
 - [Codec API reference](/docs/ai-transport/api/javascript/core/codec): the full `Codec`, `Encoder`, `Decoder` contracts and well-known variant types.
-- [Vercel codec](/docs/ai-transport/api/javascript/vercel/codec): the shipped `UIMessageCodec` for the Vercel AI SDK.
+- [Vercel codec](/docs/ai-transport/api/javascript/vercel/codec): the pre-built codec from `createUIMessageCodec()` for the Vercel AI SDK.
 - [Codec architecture](/docs/ai-transport/internals/codec-architecture): the wire-level encoder/decoder pipeline.
 - [Connections](/docs/ai-transport/concepts/connections): how the codec is bound into every connection.
diff --git a/src/pages/docs/ai-transport/concepts/connections.mdx b/src/pages/docs/ai-transport/concepts/connections.mdx
index 3bee445b1e..cea13dd7c1 100644
--- a/src/pages/docs/ai-transport/concepts/connections.mdx
+++ b/src/pages/docs/ai-transport/concepts/connections.mdx
@@ -65,14 +65,14 @@ A minimal client-side connection:
 ```javascript
 import * as Ably from 'ably';
 import { createClientSession } from '@ably/ai-transport';
-import { UIMessageCodec } from '@ably/ai-transport/vercel';
+import { createUIMessageCodec } from '@ably/ai-transport/vercel';
 
 const ably = new Ably.Realtime({ authUrl: '/api/auth/token' });
 
 const session = createClientSession({
   client: ably,
   channelName: 'conversation-42',
-  codec: UIMessageCodec,
+  codec: createUIMessageCodec(),
 });
 
 await session.connect();
diff --git a/src/pages/docs/ai-transport/concepts/runs.mdx b/src/pages/docs/ai-transport/concepts/runs.mdx
index 7948d6ed3e..b6d49036c0 100644
--- a/src/pages/docs/ai-transport/concepts/runs.mdx
+++ b/src/pages/docs/ai-transport/concepts/runs.mdx
@@ -72,7 +72,7 @@ A minimal client-side send returns a `ClientRun` that exposes the Run's identity
 
 <Code>
 ```javascript
-const clientRun = await session.view.send(UIMessageCodec.createUserMessage({
+const clientRun = await session.view.send(createUIMessageCodec().createUserMessage({
   id: crypto.randomUUID(),
   role: 'user',
   parts: [{ type: 'text', text: 'Plan a 3-day trip to Lisbon.' }],
@@ -101,13 +101,13 @@ Steering messages don't change how a Run ends. The terminal `RunEndReason` repor
 
 <Code>
 ```javascript
-const activeRun = await session.view.send(UIMessageCodec.createUserMessage({
+const activeRun = await session.view.send(createUIMessageCodec().createUserMessage({
   id: crypto.randomUUID(),
   role: 'user',
   parts: [{ type: 'text', text: 'Plan a 3-day trip to Lisbon.' }],
 }));
 
-const { published, outcome } = activeRun.steer(UIMessageCodec.createUserMessage({
+const { published, outcome } = activeRun.steer(createUIMessageCodec().createUserMessage({
   id: crypto.randomUUID(),
   role: 'user',
   parts: [{ type: 'text', text: 'Make it 5 days, and keep it under £800.' }],
diff --git a/src/pages/docs/ai-transport/concepts/sessions.mdx b/src/pages/docs/ai-transport/concepts/sessions.mdx
index 6c09053df5..938289aacb 100644
--- a/src/pages/docs/ai-transport/concepts/sessions.mdx
+++ b/src/pages/docs/ai-transport/concepts/sessions.mdx
@@ -67,7 +67,7 @@ await session.connect();
 ```
 </Code>
 
-`createClientSession` from `@ably/ai-transport/vercel` is pre-bound with the Vercel `UIMessageCodec`. The core entry point at `@ably/ai-transport` exposes the same factory with `codec` required. The core SDK never POSTs; the application wakes its agent by POSTing `run.toInvocation().toJSON()` (or by using `createChatTransport`, which does it for you). See [Set up authentication](/docs/ai-transport/getting-started/authentication) for how `authUrl` is wired up.
+`createClientSession` from `@ably/ai-transport/vercel` is pre-bound with the Vercel codec. The core entry point at `@ably/ai-transport` exposes the same factory with `codec` required. The core SDK never POSTs; the application wakes its agent by POSTing `run.toInvocation().toJSON()` (or by using `createChatTransport`, which does it for you). See [Set up authentication](/docs/ai-transport/getting-started/authentication) for how `authUrl` is wired up.
 
 ## Share a session across participants <a id="sharing"/>
 
diff --git a/src/pages/docs/ai-transport/features/agent-presence.mdx b/src/pages/docs/ai-transport/features/agent-presence.mdx
index 4566fc9c20..64c899e77c 100644
--- a/src/pages/docs/ai-transport/features/agent-presence.mdx
+++ b/src/pages/docs/ai-transport/features/agent-presence.mdx
@@ -25,7 +25,7 @@ The agent enters presence with its initial status, then updates that status as i
 ```javascript
 app.post('/api/chat', async (req, res) => {
   const invocation = Invocation.fromJSON(await req.json());
-  const session = createAgentSession({ client: ably, channelName: invocation.sessionName, codec: UIMessageCodec });
+  const session = createAgentSession({ client: ably, channelName: invocation.sessionName, codec: createUIMessageCodec() });
   await session.connect();
   const run = session.createRun(invocation, { signal: req.signal });
 
@@ -64,7 +64,7 @@ On the client, subscribe to presence events to track the agent's current state a
 
 <Code>
 ```javascript
-const session = createClientSession({ client: ably, channelName, codec: UIMessageCodec });
+const session = createClientSession({ client: ably, channelName, codec: createUIMessageCodec() });
 
 session.presence.subscribe((member) => {
   if (member.clientId === 'agent') {
diff --git a/src/pages/docs/ai-transport/features/chain-of-thought.mdx b/src/pages/docs/ai-transport/features/chain-of-thought.mdx
index 7744a7c081..f6577b3aaa 100644
--- a/src/pages/docs/ai-transport/features/chain-of-thought.mdx
+++ b/src/pages/docs/ai-transport/features/chain-of-thought.mdx
@@ -21,7 +21,7 @@ With the Vercel AI SDK integration, reasoning arrives as a separate `reasoning`
 ```javascript
 app.post('/api/chat', async (req, res) => {
   const invocation = Invocation.fromJSON(await req.json());
-  const session = createAgentSession({ client: ably, channelName: invocation.sessionName, codec: UIMessageCodec });
+  const session = createAgentSession({ client: ably, channelName: invocation.sessionName, codec: createUIMessageCodec() });
   await session.connect();
   const run = session.createRun(invocation, { signal: req.signal });
 
diff --git a/src/pages/docs/ai-transport/features/concurrent-turns.mdx b/src/pages/docs/ai-transport/features/concurrent-turns.mdx
index 0c937eb270..db111551f3 100644
--- a/src/pages/docs/ai-transport/features/concurrent-turns.mdx
+++ b/src/pages/docs/ai-transport/features/concurrent-turns.mdx
@@ -15,12 +15,12 @@ Turns are multiplexed on the Ably channel via `runId`. Every message published d
 
 <Code>
 ```javascript
-const run1 = await view.send(UIMessageCodec.createUserMessage({
+const run1 = await view.send(createUIMessageCodec().createUserMessage({
   id: crypto.randomUUID(),
   role: 'user',
   parts: [{ type: 'text', text: 'Summarize the report' }],
 }));
-const run2 = await view.send(UIMessageCodec.createUserMessage({
+const run2 = await view.send(createUIMessageCodec().createUserMessage({
   id: crypto.randomUUID(),
   role: 'user',
   parts: [{ type: 'text', text: 'What are the key risks?' }],
@@ -40,7 +40,7 @@ On the agent side, each Run is handled independently. The agent session creates
 ```javascript
 app.post('/api/chat', async (req, res) => {
   const invocation = Invocation.fromJSON(await req.json());
-  const session = createAgentSession({ client: ably, channelName: invocation.sessionName, codec: UIMessageCodec });
+  const session = createAgentSession({ client: ably, channelName: invocation.sessionName, codec: createUIMessageCodec() });
   await session.connect();
   const run = session.createRun(invocation, { signal: req.signal });
 
@@ -126,7 +126,7 @@ function whenRunEnds(session, runId) {
   });
 }
 
-const run1 = await view.send(UIMessageCodec.createUserMessage({
+const run1 = await view.send(createUIMessageCodec().createUserMessage({
   id: crypto.randomUUID(),
   role: 'user',
   parts: [{ type: 'text', text: 'Hello' }],
@@ -150,7 +150,7 @@ Cancel the current turn and immediately start a new one:
 const active = session.view.runs().filter((r) => r.status === 'active');
 await Promise.all(active.map((r) => session.cancel(r.runId)));
 
-const newRun = await view.send(UIMessageCodec.createUserMessage({
+const newRun = await view.send(createUIMessageCodec().createUserMessage({
   id: crypto.randomUUID(),
   role: 'user',
   parts: [{ type: 'text', text: 'Actually, focus on the budget instead' }],
@@ -166,13 +166,13 @@ Two users prompting the same session at the same time. Each user's Run is indepe
 
 <Code>
 ```javascript
-const runA = await viewA.send(UIMessageCodec.createUserMessage({
+const runA = await viewA.send(createUIMessageCodec().createUserMessage({
   id: crypto.randomUUID(),
   role: 'user',
   parts: [{ type: 'text', text: 'What does section 3 mean?' }],
 }));
 
-const runB = await viewB.send(UIMessageCodec.createUserMessage({
+const runB = await viewB.send(createUIMessageCodec().createUserMessage({
   id: crypto.randomUUID(),
   role: 'user',
   parts: [{ type: 'text', text: 'Summarize section 5' }],
@@ -190,7 +190,7 @@ An orchestrator dispatches work to multiple sub-agents, each streaming concurren
 ```javascript
 app.post('/api/chat', async (req, res) => {
   const invocation = Invocation.fromJSON(await req.json());
-  const session = createAgentSession({ client: ably, channelName: invocation.sessionName, codec: UIMessageCodec });
+  const session = createAgentSession({ client: ably, channelName: invocation.sessionName, codec: createUIMessageCodec() });
   await session.connect();
 
   // The orchestrator creates additional Invocations for sub-agents and POSTs
diff --git a/src/pages/docs/ai-transport/features/double-texting.mdx b/src/pages/docs/ai-transport/features/double-texting.mdx
index 5c18cde0a2..eb4a07ebb0 100644
--- a/src/pages/docs/ai-transport/features/double-texting.mdx
+++ b/src/pages/docs/ai-transport/features/double-texting.mdx
@@ -15,7 +15,7 @@ Sending a message while the agent is streaming starts a new concurrent turn. Bot
 
 <Code>
 ```javascript
-await send(UIMessageCodec.createUserMessage({
+await send(createUIMessageCodec().createUserMessage({
   id: crypto.randomUUID(),
   role: 'user',
   parts: [{ type: 'text', text: 'Explain quantum computing' }],
@@ -24,7 +24,7 @@ await send(UIMessageCodec.createUserMessage({
 // Agent starts streaming a response.
 // User sends another message before the response finishes.
 
-await send(UIMessageCodec.createUserMessage({
+await send(createUIMessageCodec().createUserMessage({
   id: crypto.randomUUID(),
   role: 'user',
   parts: [{ type: 'text', text: 'Also, what is superposition?' }],
@@ -52,7 +52,7 @@ const handleSend = async (text) => {
     return;
   }
 
-  await view.send(UIMessageCodec.createUserMessage({
+  await view.send(createUIMessageCodec().createUserMessage({
     id: crypto.randomUUID(),
     role: 'user',
     parts: [{ type: 'text', text }],
@@ -62,7 +62,7 @@ const handleSend = async (text) => {
 useEffect(() => {
   if (!isStreaming && queue.length > 0) {
     const next = queue.shift();
-    view.send(UIMessageCodec.createUserMessage({
+    view.send(createUIMessageCodec().createUserMessage({
       id: crypto.randomUUID(),
       role: 'user',
       parts: [{ type: 'text', text: next }],
@@ -87,7 +87,7 @@ const handleSend = async (text) => {
   const active = session.view.runs().filter((r) => r.status === 'active');
   await Promise.all(active.map((r) => session.cancel(r.runId)));
 
-  await view.send(UIMessageCodec.createUserMessage({
+  await view.send(createUIMessageCodec().createUserMessage({
     id: crypto.randomUUID(),
     role: 'user',
     parts: [{ type: 'text', text }],
diff --git a/src/pages/docs/ai-transport/features/durable-execution.mdx b/src/pages/docs/ai-transport/features/durable-execution.mdx
index 08425a2320..8b44fb4613 100644
--- a/src/pages/docs/ai-transport/features/durable-execution.mdx
+++ b/src/pages/docs/ai-transport/features/durable-execution.mdx
@@ -21,14 +21,14 @@ To create a Step inside a Run, the SDK needs three identifiers: `runId`, `invoca
 ```javascript
 import * as Ably from 'ably';
 import { createAgentSession } from '@ably/ai-transport';
-import { UIMessageCodec } from '@ably/ai-transport/vercel';
+import { createUIMessageCodec } from '@ably/ai-transport/vercel';
 
 async function runToolStep({ runId, invocationId, triggerEventId, activityId, toolCall }) {
   const ably = new Ably.Realtime({ key: process.env.ABLY_API_KEY });
   const session = createAgentSession({
     client: ably,
     channelName: 'conversation-42',
-    codec: UIMessageCodec,
+    codec: createUIMessageCodec(),
   });
   await session.connect();
 
diff --git a/src/pages/docs/ai-transport/features/interruption-and-steering.mdx b/src/pages/docs/ai-transport/features/interruption-and-steering.mdx
index 9fead5f137..c42f705cac 100644
--- a/src/pages/docs/ai-transport/features/interruption-and-steering.mdx
+++ b/src/pages/docs/ai-transport/features/interruption-and-steering.mdx
@@ -15,13 +15,13 @@ Start a Run with `view.send()`, then steer it by calling `activeRun.steer()` wit
 
 <Code>
 ```javascript
-const activeRun = await session.view.send(UIMessageCodec.createUserMessage({
+const activeRun = await session.view.send(createUIMessageCodec().createUserMessage({
   id: crypto.randomUUID(),
   role: 'user',
   parts: [{ type: 'text', text: 'Plan a 3-day trip to Lisbon.' }],
 }));
 
-const { published, outcome } = activeRun.steer(UIMessageCodec.createUserMessage({
+const { published, outcome } = activeRun.steer(createUIMessageCodec().createUserMessage({
   id: crypto.randomUUID(),
   role: 'user',
   parts: [{ type: 'text', text: 'Make it 5 days, and keep it under £800.' }],
@@ -49,7 +49,7 @@ Call `activeRun.steer(input)` to send a steering message to the agent. The agent
 
 <Code>
 ```javascript
-const { published, outcome } = activeRun.steer(UIMessageCodec.createUserMessage({
+const { published, outcome } = activeRun.steer(createUIMessageCodec().createUserMessage({
   id: crypto.randomUUID(),
   role: 'user',
   parts: [{ type: 'text', text: 'Also include vegan options.' }],
@@ -181,7 +181,7 @@ function Chat() {
     const active = view.runs().filter((run) => run.status === 'active');
     await Promise.all(active.map((run) => session.cancel(run.runId)));
 
-    await view.send(UIMessageCodec.createUserMessage({
+    await view.send(createUIMessageCodec().createUserMessage({
       id: crypto.randomUUID(),
       role: 'user',
       parts: [{ type: 'text', text }],
@@ -199,7 +199,7 @@ Send a new message without cancelling. Both Runs stream concurrently; each `Clie
 
 <Code>
 ```javascript
-const followUp = await session.view.send(UIMessageCodec.createUserMessage({
+const followUp = await session.view.send(createUIMessageCodec().createUserMessage({
   id: crypto.randomUUID(),
   role: 'user',
   parts: [{ type: 'text', text: 'Also include vegan options.' }],
diff --git a/src/pages/docs/ai-transport/features/liveobjects.mdx b/src/pages/docs/ai-transport/features/liveobjects.mdx
index d26ad63b7d..d8f44b71e1 100644
--- a/src/pages/docs/ai-transport/features/liveobjects.mdx
+++ b/src/pages/docs/ai-transport/features/liveobjects.mdx
@@ -42,7 +42,7 @@ Pass the plugin when you create the client, and the modes when you create the se
 import * as Ably from 'ably';
 import { LiveObjects } from 'ably/liveobjects';
 import { createClientSession, OBJECT_MODES } from '@ably/ai-transport';
-import { UIMessageCodec } from '@ably/ai-transport/vercel';
+import { createUIMessageCodec } from '@ably/ai-transport/vercel';
 
 // Without the LiveObjects plugin, session.object throws.
 const ably = new Ably.Realtime({ authUrl: '/api/auth/token', plugins: { LiveObjects } });
@@ -50,7 +50,7 @@ const ably = new Ably.Realtime({ authUrl: '/api/auth/token', plugins: { LiveObje
 const session = createClientSession({
   client: ably,
   channelName: 'conversation-42',
-  codec: UIMessageCodec,
+  codec: createUIMessageCodec(),
   // Opt the session's channel into LiveObjects. The session requests these
   // modes on top of the ones AI Transport always needs, so the transport
   // itself is unaffected.
diff --git a/src/pages/docs/ai-transport/features/multi-device.mdx b/src/pages/docs/ai-transport/features/multi-device.mdx
index 42a63e7105..3c52df77cf 100644
--- a/src/pages/docs/ai-transport/features/multi-device.mdx
+++ b/src/pages/docs/ai-transport/features/multi-device.mdx
@@ -14,12 +14,12 @@ Fan-out to multiple connected devices is automatic. There's no special configura
 <Code>
 ```javascript
 // Client A (laptop): wrap with a ClientSessionProvider for chatId.
-<ClientSessionProvider channelName={chatId} codec={UIMessageCodec}>
+<ClientSessionProvider channelName={chatId} codec={createUIMessageCodec()}>
   <Chat />
 </ClientSessionProvider>
 
 // Client B (phone): same channel name in its own ClientSessionProvider, different device.
-<ClientSessionProvider channelName={chatId} codec={UIMessageCodec}>
+<ClientSessionProvider channelName={chatId} codec={createUIMessageCodec()}>
   <Chat />
 </ClientSessionProvider>
 
diff --git a/src/pages/docs/ai-transport/features/push-notifications.mdx b/src/pages/docs/ai-transport/features/push-notifications.mdx
index fc9834d5bb..c34f7b3baa 100644
--- a/src/pages/docs/ai-transport/features/push-notifications.mdx
+++ b/src/pages/docs/ai-transport/features/push-notifications.mdx
@@ -38,7 +38,7 @@ app.post('/api/chat', async (req, res) => {
   const body = await req.json()
   const { userId } = body
   const invocation = Invocation.fromJSON(body)
-  const session = createAgentSession({ client: ably, channelName: invocation.sessionName, codec: UIMessageCodec })
+  const session = createAgentSession({ client: ably, channelName: invocation.sessionName, codec: createUIMessageCodec() })
   await session.connect()
   const run = session.createRun(invocation, { signal: req.signal })
 
diff --git a/src/pages/docs/ai-transport/frameworks/vercel-ai-sdk-core.mdx b/src/pages/docs/ai-transport/frameworks/vercel-ai-sdk-core.mdx
index 4b468c4852..3039b4d828 100644
--- a/src/pages/docs/ai-transport/frameworks/vercel-ai-sdk-core.mdx
+++ b/src/pages/docs/ai-transport/frameworks/vercel-ai-sdk-core.mdx
@@ -1,7 +1,7 @@
 ---
 title: "Vercel AI SDK Core"
 meta_description: "How Ably AI Transport integrates with Vercel AI SDK Core (the `ai` library) on the server. Codec, streamText, and the UI message stream."
-meta_keywords: "AI Transport, Vercel AI SDK Core, streamText, UIMessage, UIMessageCodec, durable sessions, server"
+meta_keywords: "AI Transport, Vercel AI SDK Core, streamText, UIMessage, createUIMessageCodec, durable sessions, server"
 intro: "Vercel AI SDK Core gives you streamText for orchestrating LLMs on the server. AI Transport encodes the resulting stream onto an Ably channel, so the same server code feeds durable sessions instead of an ephemeral HTTP response."
 ---
 
@@ -106,8 +106,8 @@ export async function POST(req) {
 
 The integration has three pieces:
 
-1. The `UIMessageCodec` encodes Vercel's `UIMessageChunk` events as Ably messages. Every chunk type maps to an Ably operation with headers that track the metadata. The codec encodes on the agent and decodes on the client.
-2. `createAgentSession({ client, channelName })` from `@ably/ai-transport/vercel` constructs the agent session bound to the channel from the invocation. The default codec is `UIMessageCodec`.
+1. The Vercel codec (from `createUIMessageCodec()`) encodes Vercel's `UIMessageChunk` events as Ably messages. Every chunk type maps to an Ably operation with headers that track the metadata. The codec encodes on the agent and decodes on the client.
+2. `createAgentSession({ client, channelName })` from `@ably/ai-transport/vercel` constructs the agent session bound to the channel from the invocation. The default codec is the Vercel codec (`createUIMessageCodec()`).
 3. `run.pipe()` reads the model's `UIMessageChunk` stream, encodes each chunk, and publishes the resulting Ably messages. `run.abortSignal` wires cancellation through from the client. [`vercelRunOutcome()`](/docs/ai-transport/api/javascript/vercel/run-outcome) then maps the pipe result and Vercel's `finishReason` to the right lifecycle action: suspend the Run when the model requested tools the SDK did not auto-execute, otherwise end it with the matching reason.
 
 ## Scope and trade-offs <a id="scope"/>
@@ -121,4 +121,4 @@ If you are building the client side, see [Vercel AI SDK UI](/docs/ai-transport/f
 - [Get started with Vercel AI SDK](/docs/ai-transport/getting-started/vercel-ai-sdk): build a working app.
 - [Vercel AI SDK UI](/docs/ai-transport/frameworks/vercel-ai-sdk-ui): the client-side integration that pairs with this page.
 - [Agent session API reference](/docs/ai-transport/api/javascript/core/agent-session): the full API surface for the agent session.
-- [Codec API reference](/docs/ai-transport/api/javascript/core/codec): the codec interface that `UIMessageCodec` implements.
+- [Codec API reference](/docs/ai-transport/api/javascript/core/codec): the codec interface that the Vercel codec implements.
diff --git a/src/pages/docs/ai-transport/frameworks/vercel-ai-sdk-ui.mdx b/src/pages/docs/ai-transport/frameworks/vercel-ai-sdk-ui.mdx
index c6b643227e..e3b0816b68 100644
--- a/src/pages/docs/ai-transport/frameworks/vercel-ai-sdk-ui.mdx
+++ b/src/pages/docs/ai-transport/frameworks/vercel-ai-sdk-ui.mdx
@@ -55,11 +55,32 @@ const { messages } = useChat({ transport: chatTransport });
 
 The integration has four parts:
 
-1. The `UIMessageCodec` encodes Vercel's `UIMessageChunk` events as Ably messages. Every chunk type (`text-delta`, `tool-input`, `finish`, and others) maps to an Ably message with headers that track its metadata. The codec encodes on the server, decodes on the client, and reassembles chunks into complete `UIMessage` objects.
+1. The Vercel codec (from `createUIMessageCodec()`) encodes Vercel's `UIMessageChunk` events as Ably messages. Every chunk type (`text-delta`, `tool-input`, `finish`, and others) maps to an Ably message with headers that track its metadata. The codec encodes on the server, decodes on the client, and reassembles chunks into complete `UIMessage` objects.
 2. `ChatTransportProvider` creates the underlying `ClientSession` and the `ChatTransport` adapter and makes both available through context. `useChatTransport` is a context reader that returns `{ session, chatTransport }`.
 3. `useMessageSync` subscribes to the transport's conversation tree and pushes updates into `useChat`'s `setMessages`. This is what brings multi-device sync and conversation branching into Vercel's local state without `useChat` natively supporting them. Pass a `messages` seed to reconcile a conversation loaded from your own database with the live channel; see [database hydration](/docs/ai-transport/features/database-hydration).
 4. On the server, `run.pipe(result.toUIMessageStream())` pipes the model's output through the codec encoder to the Ably channel. The HTTP response returns status 200 with an empty body. Tokens reach every connected client through the channel, not through the HTTP response. See [Vercel AI SDK Core](/docs/ai-transport/frameworks/vercel-ai-sdk-core) for the server-side detail.
 
+## Typed messages <a id="typed-messages"/>
+
+`createUIMessageCodec`, `createClientSession`, `createAgentSession`, and `createChatTransport` are generic over the AI SDK's three `UIMessage` type parameters: message metadata, custom data parts, and tools. Supply them once and your typed message flows through the session, so `view.getMessages()` returns messages whose `metadata`, data parts, and tool parts carry your types instead of the SDK defaults. Omit them and inference is unchanged.
+
+<Code>
+```typescript
+import { createClientSession } from '@ably/ai-transport/vercel';
+import type * as AI from 'ai';
+
+type Metadata = { userId: string };
+type DataParts = AI.UIDataTypes & { chart: { points: number[] } };
+type Tools = AI.UITools & { getWeather: { input: { city: string }; output: { tempC: number } } };
+
+const session = createClientSession<Metadata, DataParts, Tools>({ client: ably, channelName: 'ai:demo' });
+const [{ message }] = session.view.getMessages();
+message.metadata; // typed `Metadata | undefined`, not `unknown`
+```
+</Code>
+
+The React provider path (`ChatTransportProvider` and the hooks from `createSessionHooks`) stays at the SDK defaults, because those hooks are created once at module scope. To carry concrete types end-to-end, thread them through the imperative path: `createClientSession<Metadata, DataParts, Tools>()`, `createChatTransport<Metadata, DataParts, Tools>()`, and `useMessageSync<Metadata, DataParts, Tools>()`.
+
 ## Scope and trade-offs <a id="scope"/>
 
 Vercel AI SDK UI is intentionally focused on Vercel's data model. By design, it does not handle multi-device session continuity, branch navigation, or bidirectional control. AI Transport fills that gap without changing how you use `useChat`. The same `messages` array, the same `sendMessage`, the same `stop` button; the behaviours underneath move from ephemeral HTTP to durable sessions.
diff --git a/src/pages/docs/ai-transport/getting-started/authentication.mdx b/src/pages/docs/ai-transport/getting-started/authentication.mdx
index 97d80c756f..6770265aea 100644
--- a/src/pages/docs/ai-transport/getting-started/authentication.mdx
+++ b/src/pages/docs/ai-transport/getting-started/authentication.mdx
@@ -91,7 +91,10 @@ import { useEffect, useState } from 'react';
 import * as Ably from 'ably';
 import { AblyProvider } from 'ably/react';
 import { ClientSessionProvider, useClientSession } from '@ably/ai-transport/react';
-import { UIMessageCodec } from '@ably/ai-transport/vercel';
+import { createUIMessageCodec } from '@ably/ai-transport/vercel';
+
+// A stable codec instance (hold it at module scope or via useMemo).
+const uiMessageCodec = createUIMessageCodec();
 
 export function Providers({ children }) {
   const [client, setClient] = useState(null);
@@ -117,7 +120,7 @@ export function Providers({ children }) {
 
 function App({ conversationId }) {
   return (
-    <ClientSessionProvider channelName={conversationId} codec={UIMessageCodec}>
+    <ClientSessionProvider channelName={conversationId} codec={uiMessageCodec}>
       <Chat />
     </ClientSessionProvider>
   );
diff --git a/src/pages/docs/ai-transport/getting-started/core-sdk.mdx b/src/pages/docs/ai-transport/getting-started/core-sdk.mdx
index cc4c68b0dd..7c1f7139f7 100644
--- a/src/pages/docs/ai-transport/getting-started/core-sdk.mdx
+++ b/src/pages/docs/ai-transport/getting-started/core-sdk.mdx
@@ -57,7 +57,7 @@ import { streamText, convertToModelMessages } from 'ai';
 import { anthropic } from '@ai-sdk/anthropic';
 import * as Ably from 'ably';
 import { createAgentSession, Invocation } from '@ably/ai-transport';
-import { UIMessageCodec } from '@ably/ai-transport/vercel';
+import { createUIMessageCodec } from '@ably/ai-transport/vercel';
 
 const ably = new Ably.Realtime({ key: process.env.ABLY_API_KEY });
 
@@ -67,7 +67,7 @@ export async function POST(req) {
   const session = createAgentSession({
     client: ably,
     channelName: invocation.sessionName,
-    codec: UIMessageCodec,
+    codec: createUIMessageCodec(),
   });
 
   await session.connect();
@@ -117,7 +117,7 @@ Create `app/chat.tsx`. The component uses [`useView`](/docs/ai-transport/api/rea
 
 import { useState } from 'react';
 import { useClientSession, useView } from '@ably/ai-transport/react';
-import { UIMessageCodec } from '@ably/ai-transport/vercel';
+import { createUIMessageCodec } from '@ably/ai-transport/vercel';
 
 async function wakeAgent(run) {
   const res = await fetch('/api/chat', {
@@ -149,7 +149,7 @@ export function Chat() {
     if (!input.trim()) return;
     const text = input;
     setInput('');
-    const run = await view.send(UIMessageCodec.createUserMessage({
+    const run = await view.send(createUIMessageCodec().createUserMessage({
       id: crypto.randomUUID(),
       role: 'user',
       parts: [{ type: 'text', text }],
@@ -202,9 +202,12 @@ import { useEffect, useState } from 'react';
 import * as Ably from 'ably';
 import { AblyProvider } from 'ably/react';
 import { ClientSessionProvider } from '@ably/ai-transport/react';
-import { UIMessageCodec } from '@ably/ai-transport/vercel';
+import { createUIMessageCodec } from '@ably/ai-transport/vercel';
 import { Chat } from './chat';
 
+// A stable codec instance held at module scope, passed to the provider below.
+const uiMessageCodec = createUIMessageCodec();
+
 function Providers({ children }) {
   const [client, setClient] = useState(null);
 
@@ -222,7 +225,7 @@ export default function Page() {
   const channelName = 'conversations:my-chat-session';
   return (
     <Providers>
-      <ClientSessionProvider channelName={channelName} codec={UIMessageCodec}>
+      <ClientSessionProvider channelName={channelName} codec={uiMessageCodec}>
         <Chat />
       </ClientSessionProvider>
     </Providers>
diff --git a/src/pages/docs/ai-transport/getting-started/vercel-ai-sdk.mdx b/src/pages/docs/ai-transport/getting-started/vercel-ai-sdk.mdx
index 7e03121b48..66db55fd7e 100644
--- a/src/pages/docs/ai-transport/getting-started/vercel-ai-sdk.mdx
+++ b/src/pages/docs/ai-transport/getting-started/vercel-ai-sdk.mdx
@@ -54,7 +54,7 @@ This is a one-time setup per Ably app. Without the rule, the first token append
 
 ## Create the agent route <a id="create-the-agent-route"/>
 
-Create `app/api/chat/route.ts`. The agent receives an [Invocation](/docs/ai-transport/concepts/invocations), creates an [AgentSession](/docs/ai-transport/api/javascript/core/agent-session) pre-bound to `UIMessageCodec`, starts a Run, hydrates the conversation, pipes the LLM stream, and ends the Run.
+Create `app/api/chat/route.ts`. The agent receives an [Invocation](/docs/ai-transport/concepts/invocations), creates an [AgentSession](/docs/ai-transport/api/javascript/core/agent-session) pre-bound to the Vercel codec, starts a Run, hydrates the conversation, pipes the LLM stream, and ends the Run.
 
 <Code>
 ```javascript
diff --git a/src/pages/docs/ai-transport/internals/codec-architecture.mdx b/src/pages/docs/ai-transport/internals/codec-architecture.mdx
index 4cfeca8a8b..097fa5a876 100644
--- a/src/pages/docs/ai-transport/internals/codec-architecture.mdx
+++ b/src/pages/docs/ai-transport/internals/codec-architecture.mdx
@@ -60,7 +60,7 @@ AI Transport separates concerns into two layers:
 - Transport layer (generic): manages Run identity, lifecycle events, cancellation, input-event lookup, history pagination, and multi-client sync. It works with any `TInput` and `TOutput`.
 - Codec layer (domain): maps framework-specific events to Ably publish operations and back. It knows the shape of your events; it does not manage Run lifecycle.
 
-The transport layer calls into the codec but never inspects the domain payload. The codec calls into the channel writer but never manages Runs or lifecycle. This separation is what makes AI Transport framework-agnostic; the Vercel `UIMessageCodec` is one implementation, but any framework's event shape can be implemented against the same `Codec` interface.
+The transport layer calls into the codec but never inspects the domain payload. The codec calls into the channel writer but never manages Runs or lifecycle. This separation is what makes AI Transport framework-agnostic; the Vercel codec is one implementation, but any framework's event shape can be implemented against the same `Codec` interface.
 
 ## TInput and TOutput <a id="tinput-and-toutput"/>