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

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

@@ -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({ source: 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

@@ -34,13 +34,13 @@ export function Chat({ chatId, clientId, historyLimit }: ChatProps) {
   const [split, setSplit] = useState(false);
 
   const limit = historyLimit ?? 30;
-  const view = useView(transport, { limit });
-  const splitView = useCreateView(split ? transport : undefined, { limit });
+  const view = useView({ source: transport, limit });
+  const splitView = useCreateView({ transport: split ? transport : undefined, limit });
 
   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';
 
 /**
@@ -58,53 +54,49 @@ export interface TransportHooks<TEvent, TMessage> {
    */
   useClientTransport: (channelName: string) => 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 `source` to override the transport/view. Pass `limit` to auto-load on mount.
    */
-  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?: {
+    /** Override transport or view; defaults to the nearest {@link TransportProvider}. */
+    source?: ClientTransport<TEvent, TMessage> | View<TEvent, TMessage> | null;
+    /** When provided, auto-loads the first page on mount. */
+    limit?: number;
+  }) => 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}.
    */
-  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>;
+  }) => 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}.
    */
-  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;
+  }) => ViewHandle<TEvent, TMessage>;
 }
 
 /**
@@ -119,11 +111,9 @@ export const createTransportHooks = <TEvent, TMessage>(): TransportHooks<TEvent,
   // 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),
+  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,31 @@
  *
  * 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.
  */
 
 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`.
+ * @param props.transport - Transport to subscribe to; defaults to the nearest provider.
  * @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,
+}: { transport?: ClientTransport<TEvent, TMessage> } = {}): Ably.InboundMessage[] => {
+  const nearestTransport = useContext(NearestTransportContext);
+  // CAST: NearestTransportContext stores transport with erased generics; types fixed at call site.
+  const resolved = (transport ?? nearestTransport) as ClientTransport<TEvent, TMessage> | undefined;
+
   const [messages, setMessages] = useState<Ably.InboundMessage[]>([]);
   const messagesRef = useRef<Ably.InboundMessage[]>([]);
 
@@ -26,13 +36,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;
 };

src/react/use-active-turns.ts

@@ -11,29 +11,36 @@
  * Generic — works with any codec, not tied to Vercel types.
  */
 
-import { useEffect, useState } from 'react';
+import { useContext, useEffect, useState } from 'react';
 
 import { EVENT_TURN_START } from '../constants.js';
 import type { ClientTransport, TurnLifecycleEvent } from '../core/transport/types.js';
+import { NearestTransportContext } from './contexts/transport-context.js';
 
 /**
  * Returns a reactive Map of all active turns on the channel, keyed by clientId.
- * Updates when turns start or end.
- * @param transport - The client transport to observe, or null/undefined if not yet available.
+ * Updates when turns start or end. When `transport` is omitted, uses the nearest
+ * {@link TransportProvider}'s transport via context.
+ * @param props - Options including optional `transport`.
+ * @param props.transport - Transport to track turns for; defaults to the nearest provider.
  * @returns A Map where keys are clientIds and values are Sets of active turnIds.
  */
-export const useActiveTurns = <TEvent, TMessage>(
-  transport: ClientTransport<TEvent, TMessage> | null | undefined,
-): Map<string, Set<string>> => {
+export const useActiveTurns = <TEvent, TMessage>({
+  transport,
+}: { transport?: ClientTransport<TEvent, TMessage> | null } = {}): Map<string, Set<string>> => {
+  const nearestTransport = useContext(NearestTransportContext);
+  // CAST: NearestTransportContext stores transport with erased generics; types fixed at call site.
+  const resolved = (transport ?? nearestTransport) as ClientTransport<TEvent, TMessage> | undefined;
+
   const [turns, setTurns] = useState<Map<string, Set<string>>>(() => new Map());
 
   useEffect(() => {
-    if (!transport) return;
+    if (!resolved) return;
 
     // Initialize from current state
-    setTurns(transport.tree.getActiveTurnIds());
+    setTurns(resolved.tree.getActiveTurnIds());
 
-    const unsubscribe = transport.tree.on('turn', (event: TurnLifecycleEvent) => {
+    const unsubscribe = resolved.tree.on('turn', (event: TurnLifecycleEvent) => {
       setTurns((prev) => {
         const next = new Map(prev);
 
@@ -42,9 +49,9 @@ export const useActiveTurns = <TEvent, TMessage>(
           set.add(event.turnId);
           next.set(event.clientId, set);
         } else {
-          const prev = next.get(event.clientId);
-          if (prev) {
-            const updated = new Set(prev);
+          const existing = next.get(event.clientId);
+          if (existing) {
+            const updated = new Set(existing);
             updated.delete(event.turnId);
             if (updated.size === 0) {
               next.delete(event.clientId);
@@ -59,7 +66,7 @@ export const useActiveTurns = <TEvent, TMessage>(
     });
 
     return unsubscribe;
-  }, [transport]);
+  }, [resolved]);
 
   return turns;
 };