@ably/ai-transport 0.1.0 → 0.3.0

package/src/react/contexts/client-session-provider.tsx

@@ -0,0 +1,222 @@
+/**
+ * ClientSessionProvider: creates a ClientSession and makes it available to
+ * descendants via ClientSessionContext.
+ *
+ * Reads the Ably Realtime client from the surrounding `<AblyProvider>` and
+ * forwards it to `createClientSession` along with the supplied `channelName`.
+ *
+ * The session is created on first render (via useRef) and recreated when
+ * `channelName` changes; the previous session is queued for disposal.
+ * `connect()` is invoked from a `useEffect` so the session is
+ * subscribed/attached before the first descendant operation. If
+ * `createClientSession` throws,
+ * the error is stored in the ClientSessionSlot (alongside an undefined
+ * session) so that useClientSession can surface it as `sessionError`
+ * without crashing the component tree.
+ *
+ * The session 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 session teardown in development.
+ *
+ * Multiple ClientSessionProviders can be nested using distinct channelNames.
+ * Each provider merges its slot into the parent record so descendants
+ * can access all registered sessions via useClientSession(channelName).
+ *
+ * The provider also wraps its children in ably-js's `<ChannelProvider>` for the
+ * session's channel, so descendants can use ably-js channel hooks
+ * (`usePresence`, `useChannel`, etc.) against it without adding their own. It
+ * seeds the ChannelProvider's `options` with this SDK's channel agent so the
+ * hooks' agent is appended rather than overwriting it (ably-js >= 2.22).
+ */
+
+import * as Ably from 'ably';
+import { ChannelProvider, useAbly } from 'ably/react';
+import { type PropsWithChildren, type ReactNode, useContext, useEffect, useMemo, useRef } from 'react';
+
+import { channelAgent } from '../../core/agent.js';
+import { resolveChannelModes } from '../../core/channel-options.js';
+import type { CodecInputEvent, CodecOutputEvent } from '../../core/codec/types.js';
+import { createClientSession } from '../../core/transport/client-session.js';
+import type { ClientSession, ClientSessionOptions } from '../../core/transport/types.js';
+import { ErrorCode } from '../../errors.js';
+import type { ClientSessionSlot } from './client-session-context.js';
+import { ClientSessionContext } from './client-session-context.js';
+
+/**
+ * Props for {@link ClientSessionProvider}.
+ *
+ * All {@link ClientSessionOptions} except `client` (read from the surrounding
+ * `<AblyProvider>`).
+ */
+export interface ClientSessionProviderProps<
+  TInput extends CodecInputEvent,
+  TOutput extends CodecOutputEvent,
+  TProjection,
+  TMessage,
+>
+  extends Omit<ClientSessionOptions<TInput, TOutput, TProjection, TMessage>, 'client'>, PropsWithChildren {}
+
+/**
+ * Provide a {@link ClientSession} to descendant components.
+ *
+ * Reads the Ably Realtime client from the surrounding `<AblyProvider>`,
+ * creates a session bound to `channelName`, calls `connect()` on mount,
+ * and registers it in `ClientSessionContext` under `channelName`.
+ * Descendants call {@link useClientSession} with the same `channelName` to
+ * access the session.
+ *
+ * If `createClientSession` throws during construction, the error is surfaced
+ * through `useClientSession` as `sessionError` — the component tree does not
+ * crash and children are still rendered.
+ *
+ * ```tsx
+ * <AblyProvider client={ably}>
+ *   <ClientSessionProvider channelName="ai:demo" codec={UIMessageCodec}>
+ *     <Chat />
+ *   </ClientSessionProvider>
+ * </AblyProvider>
+ *
+ * // Inside Chat:
+ * const { session, sessionError } = useClientSession({ channelName: 'ai:demo' });
+ * ```
+ *
+ * For multiple sessions, nest providers with distinct channelNames:
+ *
+ * ```tsx
+ * <ClientSessionProvider channelName="ai:main" codec={UIMessageCodec}>
+ *   <ClientSessionProvider channelName="ai:aux" codec={UIMessageCodec}>
+ *     <App />
+ *   </ClientSessionProvider>
+ * </ClientSessionProvider>
+ *
+ * // Inside App:
+ * const { session: main } = useClientSession({ channelName: 'ai:main' });
+ * const { session: aux }  = useClientSession({ channelName: 'ai:aux' });
+ * ```
+ * `channelModes` must stay constant for the provider's lifetime: the session is
+ * only recreated when `channelName` changes, and removing the modes after mount
+ * silently reverts the channel's mode set without a reattach.
+ * @param props - Provider configuration including `channelName`, `codec`, and all other {@link ClientSessionOptions} except `client`.
+ * @param props.children - Descendant components that consume the session via {@link useClientSession}.
+ * @returns A React element wrapping children with ClientSessionContext.
+ */
+export const ClientSessionProvider = <
+  TInput extends CodecInputEvent,
+  TOutput extends CodecOutputEvent,
+  TProjection,
+  TMessage,
+>({
+  children,
+  ...sessionOptions
+}: ClientSessionProviderProps<TInput, TOutput, TProjection, TMessage>): ReactNode => {
+  const client = useAbly();
+  const { channelName } = sessionOptions;
+
+  // Seed the ChannelProvider with this SDK's channel agent so ably-js's React
+  // hooks append their agent (`channelOptionsForReactHooks`) rather than
+  // overwriting it. Memoised on the codec, which determines the agent string.
+  //
+  // Spec: AIT-CT23 — resolve the channel modes through the same helper the
+  // session uses so the provider and the session request an identical,
+  // identically-ordered mode set. ably-js compares modes order- and
+  // duplicate-sensitively, so matching arrays mean the provider's setOptions
+  // never triggers a reattach and never silently reverts the session's modes.
+  const channelOptions = useMemo<Ably.ChannelOptions>(() => {
+    const options: Ably.ChannelOptions = { params: { agent: channelAgent(sessionOptions.codec) } };
+    const modes = resolveChannelModes(sessionOptions.channelModes);
+    if (modes) options.modes = modes;
+    return options;
+  }, [sessionOptions.codec, sessionOptions.channelModes]);
+  const sessionRef = useRef<ClientSession<TInput, TOutput, TProjection, TMessage> | undefined>(undefined);
+  const sessionChannelRef = useRef<string>(channelName);
+  const sessionsToDisposeRef = useRef<ClientSession<CodecInputEvent, CodecOutputEvent, unknown, unknown>[]>([]);
+  const pendingCloseRef = useRef(false);
+  const constructionErrorRef = useRef<Ably.ErrorInfo | undefined>(undefined);
+
+  const alreadyCreatedOrFailed = !!sessionRef.current || !!constructionErrorRef.current;
+
+  if (!alreadyCreatedOrFailed || sessionChannelRef.current !== channelName) {
+    sessionChannelRef.current = channelName;
+    if (sessionRef.current) sessionsToDisposeRef.current.push(sessionRef.current);
+    try {
+      sessionRef.current = createClientSession({ ...sessionOptions, client });
+      constructionErrorRef.current = undefined;
+    } catch (error) {
+      sessionRef.current = undefined;
+      constructionErrorRef.current =
+        error instanceof Ably.ErrorInfo
+          ? error
+          : new Ably.ErrorInfo('Unknown error while creating client session', ErrorCode.BadRequest, 400);
+    }
+  }
+
+  const parentContext = useContext(ClientSessionContext);
+
+  // Capture ref values as locals so useMemo deps track changes correctly.
+  // CAST: ClientSessionContext stores sessions with erased generics.
+  // The generic types are fixed at the ClientSessionProvider<TInput, TOutput, TProjection, TMessage> boundary.
+  const currentSession = sessionRef.current as
+    | ClientSession<CodecInputEvent, CodecOutputEvent, unknown, unknown>
+    | undefined;
+  const currentError = constructionErrorRef.current;
+
+  const slot = useMemo<ClientSessionSlot>(
+    () => ({ session: currentSession, sessionError: currentError }),
+    [currentSession, currentError],
+  );
+
+  const contextValue = useMemo(
+    () => ({ nearest: slot, providers: { ...parentContext.providers, [channelName]: slot } }),
+    [channelName, parentContext, slot],
+  );
+
+  // Dispose sessions superseded by a channelName change. When channelName
+  // changes, the render path above pushes the now-stale session into
+  // sessionsToDisposeRef and creates a replacement. This effect's cleanup —
+  // which runs on the next channelName change or on unmount — closes every
+  // queued session.
+  useEffect(
+    () => () => {
+      for (const session of sessionsToDisposeRef.current) void session.close();
+    },
+    [channelName],
+  );
+
+  // Trigger connect() once the session is created. Re-runs when channelName
+  // changes so the freshly-recreated session connects too. Any error is
+  // stored on the session's emitter and surfaced via on('error');
+  // useClientSession doesn't need to await this.
+  useEffect(() => {
+    void sessionRef.current?.connect();
+  }, [channelName]);
+
+  // Close the session when the component truly unmounts. The close is
+  // scheduled as a microtask: in React Strict Mode (dev) the component
+  // remounts synchronously before any microtask can drain, so the remount's
+  // effect setup resets pendingCloseRef.current = false and cancels the
+  // close. On a real unmount no remount follows, the microtask fires, and
+  // the session is closed.
+  useEffect(() => {
+    pendingCloseRef.current = false;
+    return () => {
+      pendingCloseRef.current = true;
+      void Promise.resolve().then(() => {
+        if (pendingCloseRef.current) {
+          void sessionRef.current?.close();
+        }
+      });
+    };
+  }, []);
+
+  return (
+    <ClientSessionContext.Provider value={contextValue}>
+      <ChannelProvider
+        channelName={channelName}
+        options={channelOptions}
+      >
+        {children}
+      </ChannelProvider>
+    </ClientSessionContext.Provider>
+  );
+};

package/src/react/create-session-hooks.ts

@@ -0,0 +1,141 @@
+/**
+ * createSessionHooks: factory that captures the codec's type parameters once and
+ * returns a bundle of type-safe hooks + ClientSessionProvider. Hook call sites need
+ * no type parameters at every use — just call the hooks directly.
+ * @example
+ * // Once per app (e.g. in a shared session.ts):
+ * export const {
+ *   ClientSessionProvider,
+ *   useClientSession,
+ *   useView,
+ * } = createSessionHooks<VercelInput, VercelOutput, VercelProjection, UIMessage>();
+ *
+ * // In page:
+ * <ClientSessionProvider channelName="ai:demo" codec={UIMessageCodec}>
+ *   <Chat />
+ * </ClientSessionProvider>
+ *
+ * // In Chat — no type params needed, session is implicit from nearest provider:
+ * const { nodes } = useView({ limit: 30 });
+ */
+
+import type * as Ably from 'ably';
+import type { ComponentType } from 'react';
+
+import type { CodecInputEvent, CodecOutputEvent } from '../core/codec/types.js';
+import type { ClientSession, View } from '../core/transport/types.js';
+import type { ClientSessionProviderProps } from './contexts/client-session-provider.js';
+import { ClientSessionProvider as _ClientSessionProvider } from './contexts/client-session-provider.js';
+import { useAblyMessages as _useAblyMessages } from './use-ably-messages.js';
+import type { ClientSessionHandle } from './use-client-session.js';
+import { useClientSession as _useClientSession } from './use-client-session.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 } from './use-view.js';
+import { useView as _useView } from './use-view.js';
+
+/**
+ * Bundle of type-safe hooks and provider returned by {@link createSessionHooks}.
+ *
+ * The codec's `TInput`, `TOutput`, `TProjection`, and `TMessage` are baked in at
+ * factory creation time so no type params are needed at hook call sites.
+ */
+export interface SessionHooks<TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage> {
+  /**
+   * `ClientSessionProvider` narrowed to the codec's `TInput`/`TOutput`/`TMessage`. No JSX type params needed.
+   */
+  ClientSessionProvider: ComponentType<ClientSessionProviderProps<TInput, TOutput, TProjection, TMessage>>;
+  /**
+   * Read the session from context. No type params needed.
+   *
+   * Returns `{ session, sessionError }`. When no provider is found (or session
+   * construction failed), `sessionError` is set and `session` is a stub that
+   * throws on access — the hook never throws during render.
+   *
+   * Pass `onError` to subscribe to post-construction session errors
+   * (e.g. send failures, channel continuity loss) without wiring
+   * `session.on('error', …)` manually.
+   */
+  useClientSession: (props?: {
+    /** Channel name to look up; omit to use the nearest {@link ClientSessionProvider}. */
+    channelName?: string;
+    /** When `true`, return a stub session that throws on any access. */
+    skip?: boolean;
+    /** Called whenever the resolved session emits an error event. */
+    onError?: (error: Ably.ErrorInfo) => void;
+  }) => ClientSessionHandle<TInput, TOutput, TProjection, TMessage>;
+  /**
+   * Subscribe to the nearest session's view and return the visible message list with pagination.
+   * Pass `session` to use a session'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: (props?: {
+    /** Client session whose default view to subscribe to; defaults to the nearest {@link ClientSessionProvider}. */
+    session?: ClientSession<TInput, TOutput, TProjection, TMessage> | null;
+    /** A specific {@link View} to subscribe to directly. Takes priority over `session`. */
+    view?: View<TInput, 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<TInput, TMessage>;
+  /**
+   * Navigate conversation branches in the session tree.
+   * Pass `session` to override; defaults to the nearest {@link ClientSessionProvider}.
+   */
+  useTree: (props?: {
+    /** Override session; defaults to the nearest {@link ClientSessionProvider}. */
+    session?: ClientSession<TInput, TOutput, TProjection, TMessage>;
+  }) => TreeHandle<TProjection>;
+  /**
+   * Subscribe to raw Ably messages on the session channel.
+   * Pass `session` to override; defaults to the nearest {@link ClientSessionProvider}.
+   * Pass `skip: true` to return an empty array without subscribing.
+   */
+  useAblyMessages: (props?: {
+    /** Override session; defaults to the nearest {@link ClientSessionProvider}. */
+    session?: ClientSession<TInput, TOutput, TProjection, TMessage>;
+    /** When `true`, skip all subscriptions and return an empty array. */
+    skip?: boolean;
+  }) => Ably.InboundMessage[];
+  /**
+   * Create an independent view over the same tree.
+   * Pass `session` to override; defaults to the nearest {@link ClientSessionProvider}.
+   * Pass `skip: true` to return an empty handle without creating a view.
+   */
+  useCreateView: (props?: {
+    /** Override session; defaults to the nearest {@link ClientSessionProvider}. */
+    session?: ClientSession<TInput, TOutput, TProjection, 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<TInput, TMessage>;
+}
+
+/**
+ * Create a bundle of type-safe hooks and provider for a given codec's
+ * `TInput`/`TOutput`/`TProjection`/`TMessage`.
+ *
+ * These type parameters are captured at factory creation time; hook call sites need
+ * no type parameters. The returned hooks are thin wrappers around the standalone hooks
+ * with the types resolved.
+ * @returns A {@link SessionHooks} bundle.
+ */
+export const createSessionHooks = <
+  TInput extends CodecInputEvent,
+  TOutput extends CodecOutputEvent,
+  TProjection,
+  TMessage,
+>(): SessionHooks<TInput, TOutput, TProjection, TMessage> => ({
+  // CAST: ClientSessionProvider is generic; factory narrows it to the codec's TInput/TOutput/TProjection/TMessage.
+  ClientSessionProvider: _ClientSessionProvider as ComponentType<
+    ClientSessionProviderProps<TInput, TOutput, TProjection, TMessage>
+  >,
+  useClientSession: (props) => _useClientSession<TInput, TOutput, TProjection, TMessage>(props ?? {}),
+  useView: (props) => _useView<TInput, TOutput, TProjection, TMessage>(props ?? {}),
+  useTree: (props) => _useTree<TInput, TOutput, TProjection, TMessage>(props ?? {}),
+  useAblyMessages: (props) => _useAblyMessages<TInput, TOutput, TProjection, TMessage>(props ?? {}),
+  useCreateView: (props) => _useCreateView<TInput, TOutput, TProjection, TMessage>(props ?? {}),
+});

package/src/react/index.ts

@@ -1,18 +1,29 @@
-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';
-export type { TransportHooks } from './create-transport-hooks.js';
-export { createTransportHooks } from './create-transport-hooks.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 { OBJECT_MODES } from '../core/channel-options.js';
+export type { CodecMessage } from '../core/codec/types.js';
+export type {
+  ActiveRun,
+  BranchSelection,
+  ClientSession,
+  ConversationNode,
+  InputNode,
+  MessageNode,
+  RunInfo,
+  RunNode,
+  RunNodeState,
+  SendOptions,
+} from '../core/transport/types.js';
+export type { ClientSessionSlot } from './contexts/client-session-context.js';
+export type { ClientSessionProviderProps } from './contexts/client-session-provider.js';
+export { ClientSessionProvider } from './contexts/client-session-provider.js';
+export type { SessionHooks } from './create-session-hooks.js';
+export { createSessionHooks } from './create-session-hooks.js';
+export type { UseAblyMessagesOptions } from './use-ably-messages.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 type { ClientSessionHandle } from './use-client-session.js';
+export { useClientSession } from './use-client-session.js';
+export type { UseCreateViewOptions } from './use-create-view.js';
 export { useCreateView } from './use-create-view.js';
-export type { TreeHandle } from './use-tree.js';
+export type { TreeHandle, UseTreeOptions } from './use-tree.js';
 export { useTree } from './use-tree.js';
 export type { UseViewOptions, ViewHandle } from './use-view.js';
 export { useView } from './use-view.js';

package/src/react/internal/skipped-session.ts

@@ -0,0 +1,62 @@
+/**
+ * The stub {@link ClientSession} returned by the context-reader hooks when they
+ * are skipped, when no provider is found, or when session construction failed.
+ * Every member throws so a held-but-unusable session fails loudly rather than
+ * silently no-ops. Generic so each consumer gets a session typed to its own
+ * codec parameters without a cast — the throwing bodies satisfy any instantiation.
+ */
+
+import * as Ably from 'ably';
+import type * as AblyObjects from 'ably/liveobjects';
+
+import type { CodecInputEvent, CodecOutputEvent } from '../../core/codec/types.js';
+import type { ClientSession, Tree, View } from '../../core/transport/types.js';
+import { ErrorCode } from '../../errors.js';
+
+/**
+ * Build the `hook is skipped` error for a stub member.
+ * @param operation - The attempted operation, phrased for the `unable to <operation>; hook is skipped` message.
+ * @returns The skipped-hook error.
+ */
+const skipped = (operation: string): Ably.ErrorInfo =>
+  new Ably.ErrorInfo(`unable to ${operation}; hook is skipped`, ErrorCode.InvalidArgument, 400);
+
+/**
+ * Create a throwing stub {@link ClientSession}. Held safely in state before a
+ * provider resolves; any access throws {@link Ably.ErrorInfo}.
+ * @returns A stub session whose every member throws.
+ */
+export const makeSkippedClientSession = <
+  TInput extends CodecInputEvent,
+  TOutput extends CodecOutputEvent,
+  TProjection,
+  TMessage,
+>(): ClientSession<TInput, TOutput, TProjection, TMessage> => ({
+  get tree(): Tree<TOutput, TProjection> {
+    throw skipped('access tree');
+  },
+  get view(): View<TInput, TMessage> {
+    throw skipped('access view');
+  },
+  get presence(): Ably.RealtimePresence {
+    throw skipped('access presence');
+  },
+  get object(): AblyObjects.RealtimeObject {
+    throw skipped('access object');
+  },
+  connect: () => {
+    throw skipped('connect');
+  },
+  createView: (): View<TInput, TMessage> => {
+    throw skipped('create view');
+  },
+  cancel: () => {
+    throw skipped('cancel');
+  },
+  on: () => {
+    throw skipped('subscribe');
+  },
+  close: () => {
+    throw skipped('close');
+  },
+});

package/src/react/internal/use-resolved-session.ts

@@ -0,0 +1,63 @@
+import { useContext } from 'react';
+
+import type { CodecInputEvent, CodecOutputEvent } from '../../core/codec/types.js';
+import type { ClientSession } from '../../core/transport/types.js';
+import { ClientSessionContext } from '../contexts/client-session-context.js';
+
+/**
+ * Shared base for hook options that accept an explicit session override.
+ * Extend this interface for any hook whose `session` option defaults to the
+ * nearest {@link ClientSessionProvider} when omitted. Pass `null` to defer
+ * resolution (e.g. when a split pane is collapsed) — the helper returns
+ * `undefined` rather than falling back to the nearest provider.
+ */
+export interface BaseSessionOption<
+  TInput extends CodecInputEvent,
+  TOutput extends CodecOutputEvent,
+  TProjection,
+  TMessage,
+> {
+  /**
+   * Session to operate on; defaults to the nearest {@link ClientSessionProvider}.
+   * Pass `null` to defer (returns undefined; nearest provider is not used).
+   */
+  session?: ClientSession<TInput, TOutput, TProjection, TMessage> | null;
+}
+
+/**
+ * Resolve the active `ClientSession` for a hook.
+ *
+ * Reads `ClientSessionContext` and applies the standard three-way
+ * priority: explicit `session` argument → nearest provider → `undefined`.
+ * When `skip` is `true`, returns `undefined` regardless of context.
+ * When `session` is `null`, returns `undefined` (caller is deferring).
+ *
+ * Internal — not part of the public API.
+ * @param root0 - Options.
+ * @param root0.session - Explicit session; takes priority over the nearest provider. `null` to defer.
+ * @param root0.skip - When `true`, returns `undefined` immediately; context is still read but its value is ignored.
+ * @returns The resolved session, or `undefined` if none is available or `skip` is `true`.
+ */
+export const useResolvedSession = <
+  TInput extends CodecInputEvent,
+  TOutput extends CodecOutputEvent,
+  TProjection,
+  TMessage,
+>({
+  session,
+  skip,
+}: {
+  /** Explicit session; takes priority over the nearest provider. `null` to defer. */
+  session?: ClientSession<TInput, TOutput, TProjection, TMessage> | null;
+  /** When `true`, return `undefined` immediately (context is still read, but ignored). */
+  skip?: boolean;
+} = {}): ClientSession<TInput, TOutput, TProjection, TMessage> | undefined => {
+  const { nearest } = useContext(ClientSessionContext);
+  // CAST: ClientSessionContext stores session with erased generics; types fixed at call site.
+  const nearestSession = nearest?.session as unknown as
+    | ClientSession<TInput, TOutput, TProjection, TMessage>
+    | undefined;
+  if (skip) return undefined;
+  if (session === null) return undefined;
+  return session ?? nearestSession;
+};

package/src/react/use-ably-messages.ts

@@ -1,43 +1,53 @@
 /**
- * useAblyMessages — reactive raw Ably message log from a ClientTransport.
+ * useAblyMessages — reactive raw Ably message log from a ClientSession.
  *
- * Accumulates raw Ably InboundMessages from the transport's tree
+ * Accumulates raw Ably InboundMessages from the session'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.
+ * When `session` is omitted, defaults to the nearest
+ * {@link ClientSessionProvider}'s session via context.
  * Pass `skip: true` to bypass all subscriptions and return an empty array.
  */
 
 import type * as Ably from 'ably';
-import { useContext, useEffect, useRef, useState } from 'react';
+import { useEffect, useRef, useState } from 'react';
 
-import type { ClientTransport } from '../core/transport/types.js';
-import { NearestTransportContext } from './contexts/transport-context.js';
+import type { CodecInputEvent, CodecOutputEvent } from '../core/codec/types.js';
+import type { BaseSessionOption } from './internal/use-resolved-session.js';
+import { useResolvedSession } from './internal/use-resolved-session.js';
+
+/** Options for {@link useAblyMessages}. */
+export interface UseAblyMessagesOptions<
+  TInput extends CodecInputEvent,
+  TOutput extends CodecOutputEvent,
+  TProjection,
+  TMessage,
+> extends BaseSessionOption<TInput, TOutput, TProjection, TMessage> {
+  /** When `true`, skip all subscriptions and return an empty array. */
+  skip?: boolean;
+}
 
 /**
- * Subscribe to raw Ably message updates from a client transport's tree.
- * 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.
+ * Subscribe to raw Ably message updates from a client session's tree.
+ * When `session` is omitted, uses the nearest {@link ClientSessionProvider}'s session via context.
+ * @param props - Options including optional `session` and `skip`.
+ * @param props.session - Session 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.
+ * @returns The accumulated raw Ably messages in event-arrival order — older history messages loaded later are appended after the live messages already present, so this is not strictly chronological.
  */
-export const useAblyMessages = <TEvent, TMessage>({
-  transport,
-  skip,
-}: { transport?: ClientTransport<TEvent, TMessage>; skip?: boolean } = {}): Ably.InboundMessage[] => {
-  const nearestSlot = useContext(NearestTransportContext);
-  // CAST: NearestTransportContext stores transport with erased generics; types fixed at call site.
-  const resolved = skip
-    ? undefined
-    : ((transport ?? nearestSlot?.transport) as ClientTransport<TEvent, TMessage> | undefined);
+export const useAblyMessages = <
+  TInput extends CodecInputEvent,
+  TOutput extends CodecOutputEvent,
+  TProjection,
+  TMessage,
+>({ session, skip }: UseAblyMessagesOptions<TInput, TOutput, TProjection, TMessage> = {}): Ably.InboundMessage[] => {
+  const resolved = useResolvedSession({ session, skip });
 
   const [messages, setMessages] = useState<Ably.InboundMessage[]>([]);
   const messagesRef = useRef<Ably.InboundMessage[]>([]);
 
   useEffect(() => {
-    // Reset on transport change
+    // Reset on session change
     messagesRef.current = [];
     setMessages([]);