react: add error states and onError callbacks to hooks

useClientTransport now returns { transport, transportError } instead of
throwing when no provider is found or when createClientTransport throws.
A new onError option subscribes to post-construction transport errors
via transport.on('error', ...) with automatic cleanup on unmount.

useView adds an error field to ViewHandle set when loadOlder fails and
cleared on the next successful load. useSend switches to an options-based
API ({ view?, onError? }) with context-fallback view resolution and an
onError callback that fires before re-throwing.

TransportSlot replaces the raw transport in both TransportContext and
NearestTransportContext, holding { transport, error }. TransportProvider
wraps createClientTransport in try/catch so construction errors surface
as transportError in useClientTransport rather than crashing the tree.

Tests cover missing provider, construction failure, onError subscription
and cleanup, loadOlder error/clear cycle, and useSend context fallback.

Author: ttypic

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

@@ -17,7 +17,7 @@ const { useClientTransport, useActiveTurns, useView, useAblyMessages } = Transpo
 
 export function Chat({ chatId, clientId, historyLimit }: { chatId: string; clientId?: string; historyLimit?: number }) {
   // Transport is created by TransportProvider in page.tsx
-  const transport = useClientTransport();
+  const { transport } = useClientTransport();
   const chatTransport = useChatTransport(transport);
 
   // -- Callback & status logging for debug pane ----------------------------

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

@@ -31,7 +31,7 @@ interface ChatProps {
 
 export function Chat({ clientId, historyLimit }: ChatProps) {
   // Transport is created by TransportProvider in page.tsx
-  const transport = useClientTransport();
+  const { transport } = useClientTransport();
   const [split, setSplit] = useState(false);
 
   const limit = historyLimit ?? 30;

src/react/contexts/transport-context.ts

@@ -1,20 +1,37 @@
+import type * as Ably from 'ably';
 import { createContext } from 'react';
 
 import type { ClientTransport } from '../../core/transport/types.js';
 
-/** The shape of the TransportContext value — a record of channelName → transport. */
-export type TransportContextValue = Readonly<Record<string, ClientTransport<unknown, unknown>>>;
+/**
+ * A single entry in the transport registry, holding the transport and any
+ * error that occurred during its construction.
+ *
+ * `transport` is `undefined` when construction failed.
+ * `error` is set when `createClientTransport` threw during provider render.
+ */
+export interface TransportSlot {
+  /** The constructed transport, or `undefined` if construction failed. */
+  transport: ClientTransport<unknown, unknown> | undefined;
+  /** Construction error from `createClientTransport`, or `undefined` on success. */
+  error: Ably.ErrorInfo | undefined;
+}
+
+/** The shape of the TransportContext value — a record of channelName → slot. */
+export type TransportContextValue = Readonly<Record<string, TransportSlot>>;
 
 /**
- * Context that holds the registered {@link ClientTransport} instances, keyed by channelName.
+ * Context that holds the registered {@link ClientTransport} slots, keyed by channelName.
+ * Each slot contains the transport (or `undefined` on construction failure) and any error.
  * 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
+ * Context that holds the nearest (innermost) transport slot.
+ * Each {@link TransportProvider} sets this to its own slot, so descendants
  * can access the nearest transport without knowing its channel name.
+ * `undefined` when no provider is present.
  * Read by hooks whose `transport` argument is omitted.
  */
-export const NearestTransportContext = createContext<ClientTransport<unknown, unknown> | undefined>(undefined);
+export const NearestTransportContext = createContext<TransportSlot | undefined>(undefined);

src/react/contexts/transport-provider.tsx

@@ -7,21 +7,27 @@
  * to get the stable channel reference and creates the transport once on
  * first render (via useRef).
  *
+ * If createClientTransport throws, the error is stored in the TransportSlot
+ * (alongside an undefined transport) so that useClientTransport can surface it
+ * as transportError without crashing the component tree.
+ *
  * The transport is closed when the provider truly unmounts. The close is
  * scheduled as a microtask so that React Strict Mode's synchronous
  * remount cycle (mount → fake-unmount → remount) can cancel it before it
  * fires, avoiding unnecessary transport teardown in development.
  *
  * Multiple TransportProviders can be nested using distinct channelNames.
- * Each provider merges its transport into the parent record, so descendants
+ * Each provider merges its slot into the parent record so descendants
  * can access all registered transports via useClientTransport(channelName).
  */
 
+import * as Ably from 'ably';
 import { ChannelProvider, useChannel } from 'ably/react';
 import { type PropsWithChildren, type ReactNode, useContext, useEffect, useMemo, useRef } from 'react';
 
 import { createClientTransport } from '../../core/transport/client-transport.js';
 import type { ClientTransport, ClientTransportOptions } from '../../core/transport/types.js';
+import type { TransportSlot } from '../contexts/transport-context.js';
 import { NearestTransportContext, TransportContext } from '../contexts/transport-context.js';
 
 /**
@@ -47,25 +53,35 @@ const TransportProviderInner = <TEvent, TMessage>({
   const transportChannelRef = useRef<string>(channelName);
   const transportsToDisposeRef = useRef<ClientTransport<unknown, unknown>[]>([]);
   const pendingCloseRef = useRef(false);
+  const constructionErrorRef = useRef<Ably.ErrorInfo | undefined>(undefined);
 
   if (!transportRef.current || transportChannelRef.current !== channelName) {
     transportChannelRef.current = channelName;
     if (transportRef.current) transportsToDisposeRef.current.push(transportRef.current);
-    transportRef.current = createClientTransport({ ...transportOptions, channel });
+    try {
+      transportRef.current = createClientTransport({ ...transportOptions, channel });
+      constructionErrorRef.current = undefined;
+    } catch (error) {
+      transportRef.current = undefined;
+      constructionErrorRef.current = error as Ably.ErrorInfo;
+    }
   }
 
   const parentMap = useContext(TransportContext);
 
-  const contextValue = useMemo(
-    () => ({
-      ...parentMap,
-      // CAST: TransportContext stores transports with erased generics.
-      // The generic types are fixed at the TransportProvider<TEvent, TMessage> boundary.
-      [channelName]: transportRef.current as ClientTransport<unknown, unknown>,
-    }),
-    [channelName, parentMap],
+  // Capture ref values as locals so useMemo deps track changes correctly.
+  // CAST: TransportContext stores transports with erased generics.
+  // The generic types are fixed at the TransportProvider<TEvent, TMessage> boundary.
+  const currentTransport = transportRef.current as ClientTransport<unknown, unknown> | undefined;
+  const currentError = constructionErrorRef.current;
+
+  const slot = useMemo<TransportSlot>(
+    () => ({ transport: currentTransport, error: currentError }),
+    [currentTransport, currentError],
   );
 
+  const contextValue = useMemo(() => ({ ...parentMap, [channelName]: slot }), [channelName, parentMap, slot]);
+
   useEffect(
     () => () => {
       for (const transport of transportsToDisposeRef.current) void transport.close();
@@ -93,9 +109,7 @@ const TransportProviderInner = <TEvent, TMessage>({
 
   return (
     <TransportContext.Provider value={contextValue}>
-      <NearestTransportContext.Provider value={transportRef.current as ClientTransport<unknown, unknown>}>
-        {children}
-      </NearestTransportContext.Provider>
+      <NearestTransportContext.Provider value={slot}>{children}</NearestTransportContext.Provider>
     </TransportContext.Provider>
   );
 };
@@ -108,13 +122,17 @@ const TransportProviderInner = <TEvent, TMessage>({
  * in `TransportContext` under `channelName`. Descendants call
  * {@link useClientTransport} with the same `channelName` to access the transport.
  *
+ * If `createClientTransport` throws during construction, the error is surfaced
+ * through `useClientTransport` as `transportError` — the component tree does not
+ * crash and children are still rendered.
+ *
  * ```tsx
  * <TransportProvider channelName="ai:demo" codec={UIMessageCodec}>
  *   <Chat />
  * </TransportProvider>
  *
  * // Inside Chat:
- * const transport = useClientTransport({ channelName: 'ai:demo' });
+ * const { transport, transportError } = useClientTransport({ channelName: 'ai:demo' });
  * ```
  *
  * For multiple transports, nest providers with distinct channelNames:
@@ -127,8 +145,8 @@ const TransportProviderInner = <TEvent, TMessage>({
  * </TransportProvider>
  *
  * // Inside App:
- * const main = useClientTransport({ channelName: 'ai:main' });
- * const aux  = useClientTransport({ channelName: 'ai:aux' });
+ * const { transport: main } = useClientTransport({ channelName: 'ai:main' });
+ * const { transport: aux }  = useClientTransport({ channelName: 'ai:aux' });
  * ```
  * @param props - Provider configuration including `channelName`, `codec`, and all other {@link ClientTransportOptions}.
  * @returns A React element wrapping children with ChannelProvider and TransportContext.

src/react/create-transport-hooks.ts

@@ -29,6 +29,7 @@ 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 type { ClientTransportHandle } from './use-client-transport.js';
 import { useClientTransport as _useClientTransport } from './use-client-transport.js';
 import { useCreateView as _useCreateView } from './use-create-view.js';
 import type { TreeHandle } from './use-tree.js';
@@ -49,16 +50,23 @@ export interface TransportHooks<TEvent, TMessage> {
   TransportProvider: ComponentType<TransportProviderProps<TEvent, TMessage>>;
   /**
    * Read the transport from context. No type params needed.
-   * 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.
+   *
+   * Returns `{ transport, transportError }`. When no provider is found,
+   * `transportError` is set and `transport` is a stub that throws on access —
+   * the hook never throws during render.
+   *
+   * Pass `onError` to subscribe to post-construction transport errors
+   * (e.g. send failures, channel continuity loss) without wiring
+   * `transport.on('error', …)` manually.
    */
   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>;
+    /** Called whenever the resolved transport emits an error event. */
+    onError?: (error: Ably.ErrorInfo) => void;
+  }) => ClientTransportHandle<TEvent, TMessage>;
   /**
    * 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

src/react/index.ts

@@ -1,4 +1,5 @@
 export type { EventsNode, MessageNode } from '../core/transport/types.js';
+export type { TransportSlot } from './contexts/transport-context.js';
 export { NearestTransportContext } from './contexts/transport-context.js';
 export type { TransportProviderProps } from './contexts/transport-provider.js';
 export { TransportProvider } from './contexts/transport-provider.js';
@@ -8,6 +9,7 @@ export { createTransportHooks } from './create-transport-hooks.js';
 export type { EventNode, TreeNode } from '../core/transport/types.js';
 export { useAblyMessages } from './use-ably-messages.js';
 export { useActiveTurns } from './use-active-turns.js';
+export type { ClientTransportHandle } from './use-client-transport.js';
 export { useClientTransport } from './use-client-transport.js';
 export { useCreateView } from './use-create-view.js';
 export { useEdit } from './use-edit.js';

src/react/use-ably-messages.ts

@@ -27,11 +27,11 @@ export const useAblyMessages = <TEvent, TMessage>({
   transport,
   skip,
 }: { transport?: ClientTransport<TEvent, TMessage>; skip?: boolean } = {}): Ably.InboundMessage[] => {
-  const nearestTransport = useContext(NearestTransportContext);
+  const nearestSlot = 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);
+    : ((transport ?? nearestSlot?.transport) as ClientTransport<TEvent, TMessage> | undefined);
 
   const [messages, setMessages] = useState<Ably.InboundMessage[]>([]);
   const messagesRef = useRef<Ably.InboundMessage[]>([]);

src/react/use-active-turns.ts

@@ -28,9 +28,9 @@ import { NearestTransportContext } from './contexts/transport-context.js';
 export const useActiveTurns = <TEvent, TMessage>({
   transport,
 }: { transport?: ClientTransport<TEvent, TMessage> | null } = {}): Map<string, Set<string>> => {
-  const nearestTransport = useContext(NearestTransportContext);
+  const nearestSlot = useContext(NearestTransportContext);
   // CAST: NearestTransportContext stores transport with erased generics; types fixed at call site.
-  const resolved = (transport ?? nearestTransport) as ClientTransport<TEvent, TMessage> | undefined;
+  const resolved = (transport ?? nearestSlot?.transport) as ClientTransport<TEvent, TMessage> | undefined;
 
   const [turns, setTurns] = useState<Map<string, Set<string>>>(() => new Map());