@ably/ai-transport 0.0.1 → 0.2.0

package/dist/react/contexts/client-session-context.d.ts

@@ -0,0 +1,36 @@
+import { CodecInputEvent, CodecOutputEvent } from '../../core/codec/types.js';
+import { ClientSession } from '../../core/transport/types.js';
+import type * as Ably from 'ably';
+/**
+ * A single entry in the client-session registry, holding the session and any
+ * error that occurred during its construction.
+ *
+ * `session` is `undefined` when construction failed.
+ * `sessionError` is set when `createClientSession` threw during provider render.
+ */
+export interface ClientSessionSlot {
+    /** The constructed session, or `undefined` if construction failed. */
+    session: ClientSession<CodecInputEvent, CodecOutputEvent, unknown, unknown> | undefined;
+    /** Construction error from `createClientSession`, or `undefined` on success. */
+    sessionError?: Ably.ErrorInfo | undefined;
+}
+/**
+ * The shape of the {@link ClientSessionContext} value.
+ *
+ * `nearest` is the slot from the innermost enclosing {@link ClientSessionProvider}.
+ * `providers` is the full registry of all enclosing providers, keyed by channelName.
+ */
+export interface ClientSessionContextValue {
+    /** The innermost {@link ClientSessionProvider}'s slot. `undefined` when no provider is present. */
+    nearest: ClientSessionSlot | undefined;
+    /** All registered session slots from enclosing providers, keyed by channelName. */
+    providers: Readonly<Record<string, ClientSessionSlot>>;
+}
+/**
+ * Unified client-session context.
+ *
+ * Holds the nearest client-session slot and the full registry of all registered
+ * slots keyed by channelName. Populated by {@link ClientSessionProvider};
+ * read by {@link useClientSession} and internal hooks.
+ */
+export declare const ClientSessionContext: import('react').Context<ClientSessionContextValue>;

package/dist/react/contexts/client-session-provider.d.ts

@@ -0,0 +1,53 @@
+import { PropsWithChildren, ReactNode } from 'react';
+import { CodecInputEvent, CodecOutputEvent } from '../../core/codec/types.js';
+import { ClientSessionOptions } from '../../core/transport/types.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' });
+ * ```
+ * @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 declare const ClientSessionProvider: <TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage>({ children, ...sessionOptions }: ClientSessionProviderProps<TInput, TOutput, TProjection, TMessage>) => ReactNode;

package/dist/react/create-session-hooks.d.ts

@@ -0,0 +1,116 @@
+import { ComponentType } from 'react';
+import { CodecInputEvent, CodecOutputEvent } from '../core/codec/types.js';
+import { ClientSession, View } from '../core/transport/types.js';
+import { ClientSessionProviderProps } from './contexts/client-session-provider.js';
+import { ClientSessionHandle } from './use-client-session.js';
+import { TreeHandle } from './use-tree.js';
+import { ViewHandle } from './use-view.js';
+/**
+ * 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';
+/**
+ * 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 declare const createSessionHooks: <TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage>() => SessionHooks<TInput, TOutput, TProjection, TMessage>;

package/dist/react/index.d.ts

@@ -1,11 +1,17 @@
+export type { CodecMessage } from '../core/codec/types.js';
+export type { ActiveRun, BranchSelection, ClientSession, ConversationNode, EventsNode, InputNode, MessageNode, RunInfo, RunNode, 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 { useClientTransport } from './use-client-transport.js';
-export type { ConversationTreeHandle } from './use-conversation-tree.js';
-export { useConversationTree } from './use-conversation-tree.js';
-export { useEdit } from './use-edit.js';
-export type { HistoryHandle } from './use-history.js';
-export { useHistory } from './use-history.js';
-export { useMessages } from './use-messages.js';
-export { useRegenerate } from './use-regenerate.js';
-export { useSend } from './use-send.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, 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/dist/react/internal/use-resolved-session.d.ts

@@ -0,0 +1,36 @@
+import { CodecInputEvent, CodecOutputEvent } from '../../core/codec/types.js';
+import { ClientSession } from '../../core/transport/types.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 declare 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;

package/dist/react/use-ably-messages.d.ts

@@ -1,18 +1,27 @@
-import { ClientTransport } from '../core/transport/types.js';
+import { CodecInputEvent, CodecOutputEvent } from '../core/codec/types.js';
+import { BaseSessionOption } from './internal/use-resolved-session.js';
 /**
- * useAblyMessages — reactive raw Ably message log from a ClientTransport.
+ * useAblyMessages — reactive raw Ably message log from a ClientSession.
  *
- * Returns the accumulated raw Ably InboundMessages in chronological order,
- * including both live messages (from the channel subscription) and
- * history-loaded messages (from transport.history() calls).
+ * Accumulates raw Ably InboundMessages from the session's tree
+ * 'ably-message' event. Messages are appended in arrival order.
  *
- * Subscribes to the transport's "ably-message" event and re-reads the
- * list on each update.
+ * 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';
+/** 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.
- * @param transport - The client transport to observe.
- * @returns The accumulated raw Ably messages in chronological order.
+ * 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 event-arrival order — older history messages loaded later are appended after the live messages already present, so this is not strictly chronological.
  */
-export declare const useAblyMessages: <TEvent, TMessage>(transport: ClientTransport<TEvent, TMessage>) => Ably.InboundMessage[];
+export declare const useAblyMessages: <TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage>({ session, skip }?: UseAblyMessagesOptions<TInput, TOutput, TProjection, TMessage>) => Ably.InboundMessage[];

package/dist/react/use-client-session.d.ts

@@ -0,0 +1,81 @@
+import { CodecInputEvent, CodecOutputEvent } from '../core/codec/types.js';
+import { ClientSession } from '../core/transport/types.js';
+/**
+ * useClientSession — read a ClientSession from the nearest ClientSessionProvider.
+ *
+ * The session is created by {@link ClientSessionProvider}, which reads the Ably
+ * Realtime client from the surrounding `<AblyProvider>`. This hook is a thin
+ * context reader — it does not create or manage session state.
+ *
+ * **Provider lookup**
+ * - Omit `channelName` to use the innermost `ClientSessionProvider` in the tree.
+ * - Pass `channelName` to look up a specific provider by name.
+ * - Pass `skip: true` to receive a stub session that throws on any access —
+ *   safe to hold in state before auth or other conditions are ready.
+ *
+ * **Error handling**
+ * - When no matching provider is found, or when the provider's `createClientSession`
+ *   call threw, `sessionError` is set on the returned object instead of throwing.
+ *   The component can render an error state without an error boundary.
+ * - Pass `onError` to receive post-construction session errors (e.g. send failures,
+ *   channel continuity loss) without wiring `session.on('error', ...)` manually.
+ */
+import * as Ably from 'ably';
+/**
+ * Return value of {@link useClientSession}.
+ *
+ * `session` is always a valid object. When `skip` is `true`, when no provider was
+ * found, or when the provider's session construction failed, `session` is a stub
+ * that throws {@link Ably.ErrorInfo} on every access.
+ * Check `sessionError` before using `session` to avoid those throws.
+ */
+export interface ClientSessionHandle<TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage> {
+    /**
+     * The resolved session.
+     *
+     * A throwing stub when `skip` is `true`, when no matching {@link ClientSessionProvider}
+     * was found in the tree, or when session construction failed.
+     */
+    session: ClientSession<TInput, TOutput, TProjection, TMessage>;
+    /**
+     * Set when no matching {@link ClientSessionProvider} was found, when session
+     * construction failed, and `skip` is `false`.
+     * `undefined` when the session resolved successfully or when `skip` is `true`.
+     */
+    sessionError?: Ably.ErrorInfo | undefined;
+}
+/**
+ * Read a {@link ClientSession} from the nearest {@link ClientSessionProvider}.
+ *
+ * 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. {@link ErrorCode.SessionSendFailed}, {@link ErrorCode.ChannelContinuityLost})
+ * without calling `session.on('error', …)` manually. The subscription is
+ * created when the session resolves and removed on unmount.
+ * @param props - Hook options.
+ * @param props.channelName - Look up a specific provider by channel name; omit for the nearest.
+ * @param props.skip - When `true`, return the stub session immediately without resolving a provider slot.
+ * @param props.onError - Called whenever the resolved session emits an error event.
+ * @returns `{ session, sessionError }`.
+ */
+export declare const useClientSession: <TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage>({ channelName, skip, onError, }?: {
+    /**
+     * Channel name passed to the enclosing {@link ClientSessionProvider}.
+     * Omit to use the nearest provider in the tree.
+     */
+    channelName?: string;
+    /**
+     * When `true`, skip context lookup and return a stub session that throws on
+     * any access. Use when a condition (auth, feature flag) is not yet resolved.
+     */
+    skip?: boolean;
+    /**
+     * Called whenever the resolved session emits an error event.
+     * The subscription is established once the session resolves and
+     * automatically removed on unmount or when the session changes.
+     */
+    onError?: (error: Ably.ErrorInfo) => void;
+}) => ClientSessionHandle<TInput, TOutput, TProjection, TMessage>;

package/dist/react/use-create-view.d.ts

@@ -0,0 +1,23 @@
+import { CodecInputEvent, CodecOutputEvent } from '../core/codec/types.js';
+import { BaseSessionOption } from './internal/use-resolved-session.js';
+import { ViewHandle } from './use-view.js';
+/** Options for {@link useCreateView}. */
+export interface UseCreateViewOptions<TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage> extends BaseSessionOption<TInput, TOutput, TProjection, TMessage> {
+    /** When provided, auto-loads the first page on mount. Omit for manual load. */
+    limit?: number;
+    /** When `true`, skip view creation and return an empty handle immediately. */
+    skip?: boolean;
+}
+/**
+ * Create an independent {@link View} and subscribe to it.
+ * Returns the same {@link ViewHandle} as {@link useView}, but backed by a
+ * newly created view with its own branch selections and pagination state.
+ * The view is closed on unmount or when the session changes.
+ * When `session` is omitted, uses the nearest {@link ClientSessionProvider}'s session via context.
+ * @param props - Options including optional `session`, `limit` for auto-load, and `skip`.
+ * @param props.session - Session to create a view from; defaults to the nearest provider.
+ * @param props.limit - Max older messages per page; when provided, auto-loads on mount.
+ * @param props.skip - When `true`, skip view creation and return an empty handle.
+ * @returns A {@link ViewHandle} with nodes, pagination, navigation, and write operations.
+ */
+export declare const useCreateView: <TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage>({ session, limit, skip, }?: UseCreateViewOptions<TInput, TOutput, TProjection, TMessage>) => ViewHandle<TInput, TMessage>;

package/dist/react/use-tree.d.ts

@@ -0,0 +1,35 @@
+import { CodecInputEvent, CodecOutputEvent } from '../core/codec/types.js';
+import { ConversationNode, RunNode } from '../core/transport/types.js';
+import { BaseSessionOption } from './internal/use-resolved-session.js';
+/** Handle for querying the conversation tree structure. */
+export interface TreeHandle<TProjection> {
+    /**
+     * Get the RunNode for `runId`, or undefined if no node is keyed by `runId`
+     * (or the keyed node is an input node, not a reply run).
+     */
+    getRunNode: (runId: string) => RunNode<TProjection> | undefined;
+    /**
+     * Get the node that owns a given codec-message-id, or undefined if not
+     * observed. Returns a {@link ConversationNode} union — narrow on `kind`
+     * (`'input'` vs `'run'`) before reading kind-specific fields.
+     */
+    getNodeByCodecMessageId: (codecMessageId: string) => ConversationNode<TProjection> | undefined;
+    /**
+     * Get the sibling group (both kinds) the node keyed by `key` belongs to —
+     * edit versions for an input node, regenerate runs for a reply run — ordered
+     * oldest-first. A single-element array when the node has no siblings; empty
+     * when `key` is unknown. `key` is a {@link RunNode.runId} or an
+     * {@link InputNode.codecMessageId}.
+     */
+    getSiblingNodes: (key: string) => ConversationNode<TProjection>[];
+}
+/** Options for {@link useTree}. */
+export type UseTreeOptions<TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage> = BaseSessionOption<TInput, TOutput, TProjection, TMessage>;
+/**
+ * Provide stable structural query callbacks backed by the session's tree.
+ * When `session` is omitted, uses the nearest {@link ClientSessionProvider}'s session via context.
+ * @param props - Options including optional `session`.
+ * @param props.session - Session to read tree structure from; defaults to the nearest provider.
+ * @returns A {@link TreeHandle} with structural query methods.
+ */
+export declare const useTree: <TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage>({ session, }?: UseTreeOptions<TInput, TOutput, TProjection, TMessage>) => TreeHandle<TProjection>;

package/dist/react/use-view.d.ts

@@ -0,0 +1,110 @@
+import { CodecInputEvent, CodecMessage, CodecOutputEvent } from '../core/codec/types.js';
+import { ActiveRun, BranchSelection, RunInfo, SendOptions, View } from '../core/transport/types.js';
+import { BaseSessionOption } from './internal/use-resolved-session.js';
+/**
+ * useView — reactive paginated view of the conversation.
+ *
+ * Subscribes to view updates and exposes the visible messages, msg-anchored
+ * branch navigation, write operations, pagination state, and a `loadOlder`
+ * callback. Pass `session` to use a session's default view, or `view` to
+ * subscribe to a specific {@link View} directly. When both are omitted,
+ * defaults to the nearest {@link ClientSessionProvider}'s session via context.
+ */
+import * as Ably from 'ably';
+/** Options for {@link useView}. */
+export interface UseViewOptions<TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage> extends BaseSessionOption<TInput, TOutput, TProjection, TMessage> {
+    /** A specific {@link View} to subscribe to directly. Takes priority over `session`. */
+    view?: View<TInput, TMessage> | null;
+    /** Maximum number of older Runs to reveal per page (the pagination unit is the Run, not the message). When provided, auto-loads the first page on mount. */
+    limit?: number;
+    /** When `true`, skip all subscriptions and return an empty handle immediately. */
+    skip?: boolean;
+}
+/** Handle for the paginated, branch-aware conversation view. */
+export interface ViewHandle<TInput extends CodecInputEvent, TMessage> {
+    /**
+     * The visible messages along the selected branch, concatenated across all
+     * visible Runs, each paired with its codec-message-id (see
+     * {@link CodecMessage}). Read the domain object from each entry's
+     * `message` field.
+     *
+     * Correlate a rendered message back to the View — `runOf`,
+     * `branchSelection`, `selectSibling`, `regenerate`, or `edit` — via its
+     * `codecMessageId`, which the SDK assigns and tracks independently of any
+     * identity the domain `message` may carry. See {@link View.getMessages}.
+     */
+    messages: CodecMessage<TMessage>[];
+    /** Whether there are older Runs that can be revealed via `loadOlder`. */
+    hasOlder: boolean;
+    /** Whether a page load is currently in progress. */
+    loading: boolean;
+    /**
+     * Set when the most recent `loadOlder` call failed.
+     * Cleared automatically on the next successful load.
+     * `undefined` when no error has occurred or when `skip` is `true`.
+     */
+    loadError: Ably.ErrorInfo | undefined;
+    /**
+     * Load older messages into the view. No-op if already loading.
+     * On failure, `loadError` is set; on success, `loadError` is cleared.
+     */
+    loadOlder: () => Promise<void>;
+    /**
+     * Look up the {@link RunInfo} for the Run that owns `codecMessageId`.
+     * Returns `undefined` when the codec-message-id hasn't been observed.
+     * See {@link View.runOf}.
+     */
+    runOf: (codecMessageId: string) => RunInfo | undefined;
+    /**
+     * Direct lookup by runId. Returns `undefined` when the Run hasn't been
+     * observed. See {@link View.run}.
+     */
+    run: (runId: string) => RunInfo | undefined;
+    /**
+     * Snapshot of the visible Runs along the selected branch, in
+     * chronological order. Returns `[]` when the view isn't resolved.
+     * See {@link View.runs}.
+     */
+    runs: () => RunInfo[];
+    /**
+     * Resolve the {@link BranchSelection} bundle anchored at
+     * `codecMessageId`. Always returns a safe object — see
+     * {@link BranchSelection}. See {@link View.branchSelection}.
+     */
+    branchSelection: (codecMessageId: string) => BranchSelection<TMessage>;
+    /**
+     * Select a sibling at the branch point anchored at `codecMessageId`.
+     * `index` is clamped to `[0, siblings.length - 1]`. Silent no-op when
+     * `codecMessageId` isn't a branch anchor. See {@link View.selectSibling}.
+     */
+    selectSibling: (codecMessageId: string, index: number) => void;
+    /**
+     * Send one or more TInputs on the channel and fire a POST. See {@link View.send}.
+     * @throws Ably.ErrorInfo with code {@link ErrorCode.InvalidArgument} when no view is resolved (before the session is available, or when `skip` is `true`).
+     */
+    send: (events: TInput | TInput[], options?: SendOptions) => Promise<ActiveRun>;
+    /**
+     * Regenerate an assistant message, using this view's branch for history.
+     * @throws Ably.ErrorInfo with code {@link ErrorCode.InvalidArgument} when no view is resolved (before the session is available, or when `skip` is `true`).
+     */
+    regenerate: (messageId: string, options?: SendOptions) => Promise<ActiveRun>;
+    /**
+     * Edit a user message, forking from this view's branch.
+     * Rejects with an `Ably.ErrorInfo` (code {@link ErrorCode.InvalidArgument}) if no view is resolved — e.g. before the session is available, or when `skip` is `true`.
+     */
+    edit: (messageId: string, inputs: TInput | TInput[], options?: SendOptions) => Promise<ActiveRun>;
+}
+/**
+ * Subscribe to a view and return the visible messages with pagination, navigation, and write operations.
+ *
+ * `view` takes priority over `session`. When neither is provided, the nearest
+ * {@link ClientSessionProvider}'s session is used. When `limit` is provided, auto-loads
+ * the first page on mount (SWR-style).
+ * @param props - Options for selecting the view source and configuring auto-load.
+ * @param props.session - Client session whose default view to subscribe to; defaults to the nearest provider.
+ * @param props.view - A specific {@link View} to subscribe to directly. Takes priority over `session`.
+ * @param props.limit - Max older Runs to reveal per page; when provided, auto-loads the first page on mount.
+ * @param props.skip - When `true`, skip all subscriptions and return an empty handle.
+ * @returns A {@link ViewHandle} with messages, pagination state, navigation, write operations, and loadOlder.
+ */
+export declare const useView: <TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage>({ session, view, limit, skip, }?: UseViewOptions<TInput, TOutput, TProjection, TMessage>) => ViewHandle<TInput, TMessage>;