react: update hooks to support context-based transport fallback

- Updated hooks (`useView`, `useTree`, `useCreateView`, `useAblyMessages`, `useActiveTurns`, etc.) to use nearest transport for transport fallback when no explicit transport is provided.
- Modified `TransportProvider`
- Adjusted all affected hooks and types to align with the updated transport resolution mechanism via context.

Author: ttypic

README.md

@@ -144,12 +144,19 @@ export async function POST(req: Request) {
 
 import { useChat } from '@ai-sdk/react';
 import type * as AI from 'ai';
-import { TransportProvider, useClientTransport, useActiveTurns, useView } from '@ably/ai-transport/react';
+import { createTransportHooks } from '@ably/ai-transport/react';
 import { useChatTransport, useMessageSync } from '@ably/ai-transport/vercel/react';
 import { UIMessageCodec } from '@ably/ai-transport/vercel';
 
+const {
+  TransportProvider,
+  useClientTransport,
+  useActiveTurns,
+  useView
+} = createTransportHooks<AI.UIMessageChunk, AI.UIMessage>();
+
 function ChatInner({ chatId }: { chatId: string }) {
-  const transport = useClientTransport<AI.UIMessageChunk, AI.UIMessage>();
+  const transport = useClientTransport();
   const chatTransport = useChatTransport(transport);
 
   const { messages, setMessages, sendMessage, stop } = useChat({
@@ -159,8 +166,8 @@ function ChatInner({ chatId }: { chatId: string }) {
 
   useMessageSync(transport, setMessages);
 
-  const activeTurns = useActiveTurns(transport);
-  useView(transport, { limit: 30 });
+  const activeTurns = useActiveTurns();
+  useView({ limit: 30 });
 
   return (
     <div>

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

@@ -15,7 +15,7 @@ import { useClientTools } from './hooks/use-client-tools';
 
 export function Chat({ chatId, clientId, historyLimit }: { chatId: string; clientId?: string; historyLimit?: number }) {
   // Transport is created by TransportProvider in page.tsx
-  const transport = useClientTransport<AI.UIMessageChunk, AI.UIMessage>(chatId);
+  const transport = useClientTransport<AI.UIMessageChunk, AI.UIMessage>({ channelName: chatId });
   const chatTransport = useChatTransport(transport);
 
   const {
@@ -33,15 +33,15 @@ export function Chat({ chatId, clientId, historyLimit }: { chatId: string; clien
 
   useMessageSync(transport, setMessages);
 
-  const activeTurns = useActiveTurns(transport);
+  const activeTurns = useActiveTurns({ transport });
   const hasAnyTurns = activeTurns.size > 0;
 
-  // Auto-loads first page on mount (options provided = enabled)
-  const { nodes, hasOlder, loading, loadOlder } = useView(transport, { limit: historyLimit ?? 30 });
+  // Auto-loads first page on mount
+  const { nodes, hasOlder, loading, loadOlder } = useView({ transport, limit: historyLimit ?? 30 });
 
   useClientTools(chatMessages, addToolResult, nodes, clientId);
 
-  const ablyMessages = useAblyMessages(transport);
+  const ablyMessages = useAblyMessages({ transport });
 
   return (
     <div className="flex h-dvh">

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

@@ -30,17 +30,17 @@ interface ChatProps {
 
 export function Chat({ chatId, clientId, historyLimit }: ChatProps) {
   // Transport is created by TransportProvider in page.tsx
-  const transport = useClientTransport<AI.UIMessageChunk, AI.UIMessage>(chatId);
+  const transport = useClientTransport<AI.UIMessageChunk, AI.UIMessage>({ channelName: chatId });
   const [split, setSplit] = useState(false);
 
   const limit = historyLimit ?? 30;
-  const view = useView(transport, { limit });
-  const splitView = useCreateView(split ? transport : undefined, { limit });
+  const view = useView({ transport, limit });
+  const splitView = useCreateView({ transport, limit, skip: !split });
 
   useClientTools(view, clientId);
 
-  const activeTurns = useActiveTurns(transport);
-  const ablyMessages = useAblyMessages(transport);
+  const activeTurns = useActiveTurns({ transport });
+  const ablyMessages = useAblyMessages({ transport });
   const queue = useMessageQueue(transport, view.send);
 
   const handleToolApproved = useCallback(

src/react/contexts/transport-context.ts

@@ -10,3 +10,11 @@ export type TransportContextValue = Readonly<Record<string, ClientTransport<unkn
  * Populated by {@link TransportProvider}; read by {@link useClientTransport}.
  */
 export const TransportContext = createContext<TransportContextValue>({});
+
+/**
+ * Context that holds the nearest (innermost) registered {@link ClientTransport}.
+ * Each {@link TransportProvider} sets this to its own transport, so descendants
+ * can access the nearest transport without knowing its channel name.
+ * Read by hooks whose `transport` argument is omitted.
+ */
+export const NearestTransportContext = createContext<ClientTransport<unknown, unknown> | undefined>(undefined);

src/react/contexts/transport-provider.tsx

@@ -24,7 +24,7 @@ import { type PropsWithChildren, type ReactNode, useContext, useEffect, useMemo,
 
 import { createClientTransport } from '../../core/transport/client-transport.js';
 import type { ClientTransport, ClientTransportOptions } from '../../core/transport/types.js';
-import { TransportContext } from '../contexts/transport-context.js';
+import { NearestTransportContext, TransportContext } from '../contexts/transport-context.js';
 
 /**
  * Props for {@link TransportProvider}.
@@ -81,7 +81,13 @@ const TransportProviderInner = <TEvent, TMessage>({
     [],
   );
 
-  return <TransportContext.Provider value={contextValue}>{children}</TransportContext.Provider>;
+  return (
+    <TransportContext.Provider value={contextValue}>
+      <NearestTransportContext.Provider value={transportRef.current as ClientTransport<unknown, unknown>}>
+        {children}
+      </NearestTransportContext.Provider>
+    </TransportContext.Provider>
+  );
 };
 
 /**

src/react/create-transport-hooks.ts

@@ -8,7 +8,6 @@
  *   TransportProvider,
  *   useClientTransport,
  *   useView,
- *   useSend,
  *   useActiveTurns,
  * } = createTransportHooks<UIMessageChunk, UIMessage>();
  *
@@ -17,27 +16,24 @@
  *   <Chat />
  * </TransportProvider>
  *
- * // In Chat — no type params needed:
- * const transport = useClientTransport('ai:demo');
- * const { nodes } = useView(transport, { limit: 30 });
- * const send = useSend(transport);
+ * // In Chat — no type params needed, transport is implicit from nearest provider:
+ * const { nodes } = useView({ limit: 30 });
+ * const turns = useActiveTurns();
  */
 
 import type * as Ably from 'ably';
 import type { ComponentType } from 'react';
 
-import type { ActiveTurn, ClientTransport, SendOptions } from '../core/transport/types.js';
+import type { ClientTransport, View } from '../core/transport/types.js';
 import type { TransportProviderProps } from './contexts/transport-provider.js';
 import { TransportProvider as _TransportProvider } from './contexts/transport-provider.js';
 import { useAblyMessages as _useAblyMessages } from './use-ably-messages.js';
 import { useActiveTurns as _useActiveTurns } from './use-active-turns.js';
 import { useClientTransport as _useClientTransport } from './use-client-transport.js';
-import { useEdit as _useEdit } from './use-edit.js';
-import { useRegenerate as _useRegenerate } from './use-regenerate.js';
-import { useSend as _useSend } from './use-send.js';
+import { useCreateView as _useCreateView } from './use-create-view.js';
 import type { TreeHandle } from './use-tree.js';
 import { useTree as _useTree } from './use-tree.js';
-import type { ViewHandle, ViewOptions } from './use-view.js';
+import type { ViewHandle } from './use-view.js';
 import { useView as _useView } from './use-view.js';
 
 /**
@@ -53,58 +49,71 @@ export interface TransportHooks<TEvent, TMessage> {
   TransportProvider: ComponentType<TransportProviderProps<TEvent, TMessage>>;
   /**
    * Read the transport from context. No type params needed.
-   * @param channelName - The channel name passed to the enclosing `TransportProvider`.
-   * @throws {Ably.ErrorInfo} if no `TransportProvider` with the given `channelName` is in the tree.
+   * Omit `channelName` to use the nearest provider. Pass `skip: true` to return a stub
+   * that throws on any access — safe to hold before conditions are ready.
+   * @throws {Ably.ErrorInfo} if `skip` is falsy and no matching provider is found.
    */
-  useClientTransport: (channelName: string) => ClientTransport<TEvent, TMessage>;
+  useClientTransport: (props?: {
+    /** Channel name to look up; omit to use the nearest {@link TransportProvider}. */
+    channelName?: string;
+    /** When `true`, return a stub transport that throws on any access. */
+    skip?: boolean;
+  }) => ClientTransport<TEvent, TMessage>;
   /**
-   * Subscribe to the transport's view and return the visible node list with pagination.
-   * @param transport - The transport to read from.
-   * @param options - When provided, auto-loads the first page on mount.
+   * Subscribe to the nearest transport's view and return the visible node list with pagination.
+   * Pass `transport` to use a transport's default view, `view` to subscribe to a specific view
+   * directly. Pass `limit` to auto-load on mount. Pass `skip: true` for an empty handle.
    */
-  useView: (
-    transport: ClientTransport<TEvent, TMessage> | null | undefined,
-    options?: ViewOptions | null,
-  ) => ViewHandle<TMessage>;
-  /**
-   * Return a stable `send` callback.
-   * The returned function sends messages and returns an {@link ActiveTurn} handle.
-   * @param transport - The transport to send through.
-   */
-  useSend: (
-    transport: ClientTransport<TEvent, TMessage>,
-  ) => (messages: TMessage[], options?: SendOptions) => Promise<ActiveTurn<TEvent>>;
+  useView: (props?: {
+    /** Client transport whose default view to subscribe to; defaults to the nearest {@link TransportProvider}. */
+    transport?: ClientTransport<TEvent, TMessage> | null;
+    /** A specific {@link View} to subscribe to directly. Takes priority over `transport`. */
+    view?: View<TEvent, TMessage> | null;
+    /** When provided, auto-loads the first page on mount. */
+    limit?: number;
+    /** When `true`, skip all subscriptions and return an empty handle. */
+    skip?: boolean;
+  }) => ViewHandle<TEvent, TMessage>;
   /**
    * Track active turns across all clients on the channel.
-   * @param transport - The transport to observe.
+   * Pass `transport` to override; defaults to the nearest {@link TransportProvider}.
    */
-  useActiveTurns: (transport: ClientTransport<TEvent, TMessage> | null | undefined) => Map<string, Set<string>>;
+  useActiveTurns: (props?: {
+    /** Override transport; defaults to the nearest {@link TransportProvider}. */
+    transport?: ClientTransport<TEvent, TMessage> | null;
+  }) => Map<string, Set<string>>;
   /**
    * Navigate conversation branches in the transport tree.
-   * @param transport - The transport to read from.
-   */
-  useTree: (transport: ClientTransport<TEvent, TMessage>) => TreeHandle<TMessage>;
-  /**
-   * Return a stable `regenerate` callback.
-   * The returned function regenerates the given message and returns an {@link ActiveTurn} handle.
-   * @param transport - The transport to send through.
+   * Pass `transport` to override; defaults to the nearest {@link TransportProvider}.
    */
-  useRegenerate: (
-    transport: ClientTransport<TEvent, TMessage>,
-  ) => (messageId: string, options?: SendOptions) => Promise<ActiveTurn<TEvent>>;
+  useTree: (props?: {
+    /** Override transport; defaults to the nearest {@link TransportProvider}. */
+    transport?: ClientTransport<TEvent, TMessage>;
+  }) => TreeHandle<TMessage>;
   /**
-   * Return a stable `edit` callback.
-   * The returned function edits the given message and returns an {@link ActiveTurn} handle.
-   * @param transport - The transport to send through.
+   * Subscribe to raw Ably messages on the transport channel.
+   * Pass `transport` to override; defaults to the nearest {@link TransportProvider}.
+   * Pass `skip: true` to return an empty array without subscribing.
    */
-  useEdit: (
-    transport: ClientTransport<TEvent, TMessage>,
-  ) => (messageId: string, newMessages: TMessage | TMessage[], options?: SendOptions) => Promise<ActiveTurn<TEvent>>;
+  useAblyMessages: (props?: {
+    /** Override transport; defaults to the nearest {@link TransportProvider}. */
+    transport?: ClientTransport<TEvent, TMessage>;
+    /** When `true`, skip all subscriptions and return an empty array. */
+    skip?: boolean;
+  }) => Ably.InboundMessage[];
   /**
-   * Subscribe to raw Ably messages on the transport channel.
-   * @param transport - The transport to observe.
+   * Create an independent view over the same tree.
+   * Pass `transport` to override; defaults to the nearest {@link TransportProvider}.
+   * Pass `skip: true` to return an empty handle without creating a view.
    */
-  useAblyMessages: (transport: ClientTransport<TEvent, TMessage>) => Ably.InboundMessage[];
+  useCreateView: (props?: {
+    /** Override transport; defaults to the nearest {@link TransportProvider}. */
+    transport?: ClientTransport<TEvent, TMessage> | null;
+    /** When provided, auto-loads the first page on mount. */
+    limit?: number;
+    /** When `true`, skip view creation and return an empty handle. */
+    skip?: boolean;
+  }) => ViewHandle<TEvent, TMessage>;
 }
 
 /**
@@ -118,12 +127,10 @@ export interface TransportHooks<TEvent, TMessage> {
 export const createTransportHooks = <TEvent, TMessage>(): TransportHooks<TEvent, TMessage> => ({
   // CAST: TransportProvider is generic; factory narrows it to TEvent/TMessage.
   TransportProvider: _TransportProvider as ComponentType<TransportProviderProps<TEvent, TMessage>>,
-  useClientTransport: (channelName: string) => _useClientTransport<TEvent, TMessage>(channelName),
-  useView: (transport, options) => _useView(transport, options),
-  useSend: (transport) => _useSend(transport),
-  useActiveTurns: (transport) => _useActiveTurns(transport),
-  useTree: (transport) => _useTree(transport),
-  useRegenerate: (transport) => _useRegenerate(transport),
-  useEdit: (transport) => _useEdit(transport),
-  useAblyMessages: (transport) => _useAblyMessages(transport),
+  useClientTransport: (props) => _useClientTransport<TEvent, TMessage>(props ?? {}),
+  useView: (props) => _useView<TEvent, TMessage>(props ?? {}),
+  useActiveTurns: (props) => _useActiveTurns<TEvent, TMessage>(props ?? {}),
+  useTree: (props) => _useTree<TEvent, TMessage>(props ?? {}),
+  useAblyMessages: (props) => _useAblyMessages<TEvent, TMessage>(props ?? {}),
+  useCreateView: (props) => _useCreateView<TEvent, TMessage>(props ?? {}),
 });

src/react/index.ts

@@ -1,8 +1,9 @@
+export type { EventsNode, MessageNode } from '../core/transport/types.js';
+export { NearestTransportContext } from './contexts/transport-context.js';
 export type { TransportProviderProps } from './contexts/transport-provider.js';
 export { TransportProvider } from './contexts/transport-provider.js';
 export type { TransportHooks } from './create-transport-hooks.js';
 export { createTransportHooks } from './create-transport-hooks.js';
-export type { EventsNode, MessageNode } from '../core/transport/types.js';
 // eslint-disable-next-line @typescript-eslint/no-deprecated -- intentional re-export for backwards compatibility
 export type { EventNode, TreeNode } from '../core/transport/types.js';
 export { useAblyMessages } from './use-ably-messages.js';

src/react/use-ably-messages.ts

@@ -3,21 +3,36 @@
  *
  * Accumulates raw Ably InboundMessages from the transport's tree
  * 'ably-message' event. Messages are appended in arrival order.
+ *
+ * When `transport` is omitted, defaults to the nearest
+ * {@link TransportProvider}'s transport via context.
+ * Pass `skip: true` to bypass all subscriptions and return an empty array.
  */
 
 import type * as Ably from 'ably';
-import { useEffect, useRef, useState } from 'react';
+import { useContext, useEffect, useRef, useState } from 'react';
 
 import type { ClientTransport } from '../core/transport/types.js';
+import { NearestTransportContext } from './contexts/transport-context.js';
 
 /**
  * Subscribe to raw Ably message updates from a client transport's tree.
- * @param transport - The client transport to observe.
+ * When `transport` is omitted, uses the nearest {@link TransportProvider}'s transport via context.
+ * @param props - Options including optional `transport` and `skip`.
+ * @param props.transport - Transport to subscribe to; defaults to the nearest provider.
+ * @param props.skip - When `true`, skip all subscriptions and return an empty array.
  * @returns The accumulated raw Ably messages in chronological order.
  */
-export const useAblyMessages = <TEvent, TMessage>(
-  transport: ClientTransport<TEvent, TMessage>,
-): Ably.InboundMessage[] => {
+export const useAblyMessages = <TEvent, TMessage>({
+  transport,
+  skip,
+}: { transport?: ClientTransport<TEvent, TMessage>; skip?: boolean } = {}): Ably.InboundMessage[] => {
+  const nearestTransport = useContext(NearestTransportContext);
+  // CAST: NearestTransportContext stores transport with erased generics; types fixed at call site.
+  const resolved = skip
+    ? undefined
+    : ((transport ?? nearestTransport) as ClientTransport<TEvent, TMessage> | undefined);
+
   const [messages, setMessages] = useState<Ably.InboundMessage[]>([]);
   const messagesRef = useRef<Ably.InboundMessage[]>([]);
 
@@ -26,13 +41,15 @@ export const useAblyMessages = <TEvent, TMessage>(
     messagesRef.current = [];
     setMessages([]);
 
-    const unsub = transport.tree.on('ably-message', (msg: Ably.InboundMessage) => {
+    if (!resolved) return;
+
+    const unsub = resolved.tree.on('ably-message', (msg: Ably.InboundMessage) => {
       const next = [...messagesRef.current, msg];
       messagesRef.current = next;
       setMessages(next);
     });
     return unsub;
-  }, [transport]);
+  }, [resolved]);
 
   return messages;
 };