@ably/ai-transport 0.0.1 → 0.1.0

package/dist/react/contexts/transport-context.d.ts

@@ -0,0 +1,31 @@
+import { ClientTransport } from '../../core/transport/types.js';
+import type * as Ably from 'ably';
+/**
+ * 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} 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 declare const TransportContext: import('react').Context<Readonly<Record<string, TransportSlot>>>;
+/**
+ * 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 declare const NearestTransportContext: import('react').Context<TransportSlot | undefined>;

package/dist/react/contexts/transport-provider.d.ts

@@ -0,0 +1,49 @@
+import { PropsWithChildren, ReactNode } from 'react';
+import { ClientTransportOptions } from '../../core/transport/types.js';
+/**
+ * Props for {@link TransportProvider}.
+ *
+ * All {@link ClientTransportOptions} except `channel` (managed internally) plus `channelName`.
+ */
+export interface TransportProviderProps<TEvent, TMessage> extends Omit<ClientTransportOptions<TEvent, TMessage>, 'channel'>, PropsWithChildren {
+    /** The Ably channel name to subscribe to. Also used as the context registry key. */
+    channelName: string;
+}
+/**
+ * Provide a {@link ClientTransport} to descendant components.
+ *
+ * Wraps children with Ably's `ChannelProvider` using `channelName`, creates a
+ * transport from the resolved channel and the remaining options, and registers it
+ * 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, transportError } = useClientTransport({ channelName: 'ai:demo' });
+ * ```
+ *
+ * For multiple transports, nest providers with distinct channelNames:
+ *
+ * ```tsx
+ * <TransportProvider channelName="ai:main" codec={UIMessageCodec}>
+ *   <TransportProvider channelName="ai:aux" codec={UIMessageCodec}>
+ *     <App />
+ *   </TransportProvider>
+ * </TransportProvider>
+ *
+ * // Inside App:
+ * 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.
+ */
+export declare const TransportProvider: <TEvent, TMessage>(props: TransportProviderProps<TEvent, TMessage>) => ReactNode;

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

@@ -0,0 +1,124 @@
+import { ComponentType } from 'react';
+import { ClientTransport, View } from '../core/transport/types.js';
+import { TransportProviderProps } from './contexts/transport-provider.js';
+import { ClientTransportHandle } from './use-client-transport.js';
+import { TreeHandle } from './use-tree.js';
+import { ViewHandle } from './use-view.js';
+/**
+ * createTransportHooks: factory that captures TEvent and TMessage once and returns
+ * a bundle of type-safe hooks + TransportProvider. Hook call sites need no type
+ * parameters at every use — just call the hooks directly.
+ * @example
+ * // Once per app (e.g. in a shared transport.ts):
+ * export const {
+ *   TransportProvider,
+ *   useClientTransport,
+ *   useView,
+ *   useActiveTurns,
+ * } = createTransportHooks<UIMessageChunk, UIMessage>();
+ *
+ * // In page:
+ * <TransportProvider channelName="ai:demo" codec={UIMessageCodec}>
+ *   <Chat />
+ * </TransportProvider>
+ *
+ * // 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';
+/**
+ * Bundle of type-safe hooks and provider returned by {@link createTransportHooks}.
+ *
+ * `TEvent` and `TMessage` are baked in at factory creation time so no type params
+ * are needed at hook call sites.
+ */
+export interface TransportHooks<TEvent, TMessage> {
+    /**
+     * `TransportProvider` narrowed to `TEvent`/`TMessage`. No JSX type params needed.
+     */
+    TransportProvider: ComponentType<TransportProviderProps<TEvent, TMessage>>;
+    /**
+     * Read the transport from context. No type params needed.
+     *
+     * 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;
+        /** 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
+     * directly. Pass `limit` to auto-load on mount. Pass `skip: true` for an empty handle.
+     */
+    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.
+     * Pass `transport` to override; defaults to the nearest {@link TransportProvider}.
+     */
+    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.
+     * Pass `transport` to override; defaults to the nearest {@link TransportProvider}.
+     */
+    useTree: (props?: {
+        /** Override transport; defaults to the nearest {@link TransportProvider}. */
+        transport?: ClientTransport<TEvent, TMessage>;
+    }) => TreeHandle<TMessage>;
+    /**
+     * 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.
+     */
+    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[];
+    /**
+     * 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.
+     */
+    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>;
+}
+/**
+ * Create a bundle of type-safe hooks and provider for a given `TEvent`/`TMessage` pair.
+ *
+ * `TEvent` and `TMessage` 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 TransportHooks} bundle.
+ */
+export declare const createTransportHooks: <TEvent, TMessage>() => TransportHooks<TEvent, TMessage>;

package/dist/react/index.d.ts

@@ -1,11 +1,17 @@
+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';
+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 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 { useCreateView } from './use-create-view.js';
+export type { TreeHandle } 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/use-ably-messages.d.ts

@@ -2,17 +2,23 @@ import { ClientTransport } from '../core/transport/types.js';
 /**
  * useAblyMessages — reactive raw Ably message log from a ClientTransport.
  *
- * 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 transport'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 `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';
 /**
- * Subscribe to raw Ably message updates from a client transport.
- * @param transport - The client transport to observe.
+ * 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.
+ * @param props.skip - When `true`, skip all subscriptions and return an empty array.
  * @returns The accumulated raw Ably messages in chronological order.
  */
-export declare const useAblyMessages: <TEvent, TMessage>(transport: ClientTransport<TEvent, TMessage>) => Ably.InboundMessage[];
+export declare const useAblyMessages: <TEvent, TMessage>({ transport, skip, }?: {
+    transport?: ClientTransport<TEvent, TMessage>;
+    skip?: boolean;
+}) => Ably.InboundMessage[];

package/dist/react/use-active-turns.d.ts

@@ -1,8 +1,12 @@
 import { ClientTransport } from '../core/transport/types.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 declare const useActiveTurns: <TEvent, TMessage>(transport: ClientTransport<TEvent, TMessage> | null | undefined) => Map<string, Set<string>>;
+export declare const useActiveTurns: <TEvent, TMessage>({ transport, }?: {
+    transport?: ClientTransport<TEvent, TMessage> | null;
+}) => Map<string, Set<string>>;

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

@@ -1,7 +1,80 @@
-import { ClientTransport, ClientTransportOptions } from '../core/transport/types.js';
+import { ClientTransport } from '../core/transport/types.js';
 /**
- * Create and memoize a {@link ClientTransport} across renders.
- * @param options - Configuration for the client transport.
- * @returns The memoized transport instance.
+ * useClientTransport — read a ClientTransport from the nearest TransportProvider.
+ *
+ * The transport is created by {@link TransportProvider}, which also wraps the subtree
+ * with Ably's `ChannelProvider`. This hook is a thin context reader — it does not
+ * create or manage transport state.
+ *
+ * **Provider lookup**
+ * - Omit `channelName` to use the innermost `TransportProvider` in the tree.
+ * - Pass `channelName` to look up a specific provider by name.
+ * - Pass `skip: true` to receive a stub transport 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 `createClientTransport`
+ *   call threw, `transportError` 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 transport errors (e.g. send failures,
+ *   channel continuity loss) without wiring `transport.on('error', ...)` manually.
  */
-export declare const useClientTransport: <TEvent, TMessage>(options: ClientTransportOptions<TEvent, TMessage>) => ClientTransport<TEvent, TMessage>;
+import * as Ably from 'ably';
+/**
+ * Return value of {@link useClientTransport}.
+ *
+ * `transport` is always a valid object. When `skip` is `true`, when no provider was
+ * found, or when the provider's transport construction failed, `transport` is a stub
+ * that throws {@link Ably.ErrorInfo} on every access.
+ * Check `transportError` before using `transport` to avoid those throws.
+ */
+export interface ClientTransportHandle<TEvent, TMessage> {
+    /**
+     * The resolved transport.
+     *
+     * A throwing stub when `skip` is `true`, when no matching {@link TransportProvider}
+     * was found in the tree, or when transport construction failed.
+     */
+    transport: ClientTransport<TEvent, TMessage>;
+    /**
+     * Set when no matching {@link TransportProvider} was found, when transport
+     * construction failed, and `skip` is `false`.
+     * `undefined` when the transport resolved successfully or when `skip` is `true`.
+     */
+    transportError?: Ably.ErrorInfo | undefined;
+}
+/**
+ * Read a {@link ClientTransport} from the nearest {@link TransportProvider}.
+ *
+ * Returns `{ transport, transportError }`. When no provider is found or transport
+ * construction failed, `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. {@link ErrorCode.TransportSendFailed}, {@link ErrorCode.ChannelContinuityLost})
+ * without calling `transport.on('error', …)` manually. The subscription is
+ * created when the transport 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 transport immediately without reading context.
+ * @param props.onError - Called whenever the resolved transport emits an error event.
+ * @returns `{ transport, transportError }`.
+ */
+export declare const useClientTransport: <TEvent, TMessage>({ channelName, skip, onError, }?: {
+    /**
+     * Channel name passed to the enclosing {@link TransportProvider}.
+     * Omit to use the nearest provider in the tree.
+     */
+    channelName?: string;
+    /**
+     * When `true`, skip context lookup and return a stub transport that throws on
+     * any access. Use when a condition (auth, feature flag) is not yet resolved.
+     */
+    skip?: boolean;
+    /**
+     * Called whenever the resolved transport emits an error event.
+     * The subscription is established once the transport resolves and
+     * automatically removed on unmount or when the transport changes.
+     */
+    onError?: (error: Ably.ErrorInfo) => void;
+}) => ClientTransportHandle<TEvent, TMessage>;

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

@@ -0,0 +1,22 @@
+import { ClientTransport } from '../core/transport/types.js';
+import { ViewHandle } from './use-view.js';
+/**
+ * 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 transport changes.
+ * When `transport` is omitted, uses the nearest {@link TransportProvider}'s transport via context.
+ * @param props - Options including optional `transport`, `limit` for auto-load, and `skip`.
+ * @param props.transport - Transport 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: <TEvent, TMessage>({ transport, limit, skip, }?: {
+    /** The transport to create a view from, or null/undefined to use the nearest provider. */
+    transport?: ClientTransport<TEvent, TMessage> | null;
+    /** 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;
+}) => ViewHandle<TEvent, TMessage>;

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

@@ -0,0 +1,20 @@
+import { ClientTransport, MessageNode } from '../core/transport/types.js';
+/** Handle for querying the conversation tree structure. */
+export interface TreeHandle<TMessage> {
+    /** Get all sibling messages at a fork point, ordered chronologically by serial. */
+    getSiblings: (msgId: string) => TMessage[];
+    /** Whether a message has sibling alternatives (i.e., show navigation arrows). */
+    hasSiblings: (msgId: string) => boolean;
+    /** Get a node by msgId, or undefined if not found. */
+    getNode: (msgId: string) => MessageNode<TMessage> | undefined;
+}
+/**
+ * Provide stable structural query callbacks backed by the transport's tree.
+ * When `transport` is omitted, uses the nearest {@link TransportProvider}'s transport via context.
+ * @param props - Options including optional `transport`.
+ * @param props.transport - Transport to read tree structure from; defaults to the nearest provider.
+ * @returns A {@link TreeHandle} with structural query methods.
+ */
+export declare const useTree: <TEvent, TMessage>({ transport, }?: {
+    transport?: ClientTransport<TEvent, TMessage>;
+}) => TreeHandle<TMessage>;

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

@@ -0,0 +1,79 @@
+import { ActiveTurn, ClientTransport, MessageNode, SendOptions, View } from '../core/transport/types.js';
+/**
+ * useView — reactive paginated view of the conversation.
+ *
+ * Subscribes to view updates and exposes the visible nodes, branch navigation,
+ * write operations, pagination state, and a `loadOlder` callback. Pass `transport`
+ * to use a transport's default view, or `view` to subscribe to a specific
+ * {@link View} directly. When both are omitted, defaults to the nearest
+ * {@link TransportProvider}'s transport via context.
+ */
+import * as Ably from 'ably';
+/** Options for configuring the view's initial load behavior. */
+export interface UseViewOptions {
+    /** Maximum number of older messages to load per page. Defaults to 100. */
+    limit?: number;
+}
+/** Handle for the paginated, branch-aware conversation view. */
+export interface ViewHandle<TEvent, TMessage> {
+    /** The visible domain messages along the selected branch. */
+    messages: TMessage[];
+    /** Visible conversation nodes along the selected branch. */
+    nodes: MessageNode<TMessage>[];
+    /** Whether there are older messages 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, `error` is set; on success, `error` is cleared.
+     */
+    loadOlder: () => Promise<void>;
+    /** Select a sibling at a fork point by index. Triggers a view update with the new branch. */
+    select: (msgId: string, index: number) => void;
+    /** Index of the currently selected sibling at a fork point. */
+    getSelectedIndex: (msgId: string) => number;
+    /** Get all sibling messages at a fork point, ordered chronologically by serial. */
+    getSiblings: (msgId: string) => TMessage[];
+    /** Whether a message has sibling alternatives (i.e., show navigation arrows). */
+    hasSiblings: (msgId: string) => boolean;
+    /** Get a node by msgId, or undefined if not found. */
+    getNode: (msgId: string) => MessageNode<TMessage> | undefined;
+    /** Send one or more messages in the context of this view's selected branch. */
+    send: (messages: TMessage | TMessage[], options?: SendOptions) => Promise<ActiveTurn<TEvent>>;
+    /** Regenerate an assistant message, using this view's branch for history. */
+    regenerate: (messageId: string, options?: SendOptions) => Promise<ActiveTurn<TEvent>>;
+    /** Edit a user message, forking from this view's branch. */
+    edit: (messageId: string, newMessages: TMessage | TMessage[], options?: SendOptions) => Promise<ActiveTurn<TEvent>>;
+    /** Amend an existing message and start a continuation turn (e.g. tool results). */
+    update: (msgId: string, events: TEvent[], options?: SendOptions) => Promise<ActiveTurn<TEvent>>;
+}
+/**
+ * Subscribe to a view and return the visible node list with pagination, navigation, and write operations.
+ *
+ * `view` takes priority over `transport`. When neither is provided, the nearest
+ * {@link TransportProvider}'s transport 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.transport - Client transport 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 `transport`.
+ * @param props.limit - Max older messages per page; when provided, auto-loads on mount.
+ * @param props.skip - When `true`, skip all subscriptions and return an empty handle.
+ * @returns A {@link ViewHandle} with nodes, pagination state, navigation, write operations, and loadOlder.
+ */
+export declare const useView: <TEvent, TMessage>({ transport, view, limit, skip, }?: {
+    /** Client transport whose default view to subscribe to; defaults to the nearest provider when omitted. */
+    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. Omit for manual loading. */
+    limit?: number;
+    /** When `true`, skip all subscriptions and return an empty handle immediately. */
+    skip?: boolean;
+}) => ViewHandle<TEvent, TMessage>;