@langchain/react 0.3.4 → 1.0.0

package/dist/index.d.ts

@@ -1,14 +1,17 @@
-import { SubagentStream, SubagentStreamInterface, UseStream, UseStreamCustom, UseSuspenseStream } from "./types.js";
-import { ClassSubagentStreamInterface, useStream } from "./stream.js";
-import { SuspenseCache, createSuspenseCache, invalidateSuspenseCache, useSuspenseStream } from "./suspense-stream.js";
-import { FetchStreamTransport } from "./stream.custom.js";
+import { AgentServerOptions, AnyStream, CustomAdapterOptions, STREAM_CONTROLLER, UseStreamOptions, UseStreamResult, UseStreamReturn, useStream } from "./use-stream.js";
+import { useProjection } from "./use-projection.js";
+import { SelectorTarget, SubmissionQueueEntry, SubmissionQueueSnapshot, UseSubmissionQueueReturn, useAudio, useChannel, useExtension, useFiles, useImages, useMessageMetadata, useMessages, useSubmissionQueue, useToolCalls, useValues, useVideo } from "./selectors.js";
+import { useMediaURL } from "./use-media-url.js";
+import { AudioPlayerHandle, PlayerStatus, UseAudioPlayerOptions, useAudioPlayer } from "./use-audio-player.js";
+import { UseVideoPlayerOptions, VideoPlayerHandle, useVideoPlayer } from "./use-video-player.js";
+import { UseSuspenseStreamReturn, useSuspenseStream } from "./suspense-stream.js";
 import { StreamProvider, StreamProviderCustomProps, StreamProviderProps, useStreamContext } from "./context.js";
-import { AgentTypeConfigLike, BaseStream, BaseSubagentState, CompiledSubAgentLike, DeepAgentTypeConfigLike, DefaultSubagentStates, ExtractAgentConfig, ExtractDeepAgentConfig, ExtractSubAgentMiddleware, GetToolCallsType, InferAgentToolCalls, InferBag, InferDeepAgentSubagents, InferNodeNames, InferStateType, InferSubagentByName, InferSubagentNames, InferSubagentState, InferSubagentStates, InferToolCalls, IsAgentLike, IsDeepAgentLike, MessageMetadata, QueueEntry, QueueInterface, ResolveStreamInterface, ResolveStreamOptions, SubAgentLike, SubagentManager, SubagentStateMap, SubagentStatus, SubagentToolCall, UseAgentStream, UseAgentStreamOptions, UseDeepAgentStream, UseDeepAgentStreamOptions, UseStreamCustomOptions, UseStreamOptions, UseStreamThread, UseStreamTransport, calculateDepthFromNamespace, extractParentIdFromNamespace, extractToolCallIdFromNamespace, isSubagentNamespace } from "@langchain/langgraph-sdk/ui";
-import { AnyHeadlessToolImplementation, DefaultToolCall, DefaultToolCall as DefaultToolCall$1, FlushPendingHeadlessToolInterruptsOptions, HeadlessToolImplementation, HeadlessToolInterrupt, OnToolCallback, ToolCallFromTool, ToolCallState, ToolCallWithResult as ToolCallWithResult$1, ToolCallsFromTools, ToolEvent, executeHeadlessTool, filterOutHeadlessToolInterrupts, findHeadlessTool, flushPendingHeadlessToolInterrupts, handleHeadlessToolInterrupt, headlessToolResumeCommand, isHeadlessToolInterrupt, parseHeadlessToolInterruptPayload } from "@langchain/langgraph-sdk";
+import { AnyHeadlessToolImplementation, DefaultToolCall, DefaultToolCall as DefaultToolCall$1, FlushPendingHeadlessToolInterruptsOptions, HeadlessToolImplementation, HeadlessToolInterrupt, HttpAgentServerAdapter, HttpAgentServerAdapterOptions, OnToolCallback, ToolCallFromTool, ToolCallState, ToolCallWithResult as ToolCallWithResult$1, ToolCallsFromTools, ToolEvent, executeHeadlessTool, filterOutHeadlessToolInterrupts, findHeadlessTool, flushPendingHeadlessToolInterrupts, handleHeadlessToolInterrupt, headlessToolResumeCommand, isHeadlessToolInterrupt, parseHeadlessToolInterruptPayload } from "@langchain/langgraph-sdk";
+import { AgentServerAdapter, AnyMediaHandle, AssembledToolCall, AudioMedia, Channel, Event, FileMedia, ImageMedia, InferStateType, InferSubagentStates, InferToolCalls, MediaAssemblyError, MediaAssemblyErrorKind, MediaBase, MediaBlockType, MessageMetadata, MessageMetadataMap, StreamSubmitOptions, SubagentDiscoverySnapshot, SubgraphDiscoverySnapshot, ToolCallStatus, VideoMedia, WidenUpdateMessages } from "@langchain/langgraph-sdk/stream";
 import { AIMessage, ToolMessage } from "@langchain/core/messages";
 
 //#region src/index.d.ts
 type ToolCallWithResult<ToolCall = DefaultToolCall$1> = ToolCallWithResult$1<ToolCall, ToolMessage, AIMessage>;
 //#endregion
-export { type AgentTypeConfigLike, type AnyHeadlessToolImplementation, type BaseStream, type BaseSubagentState, type ClassSubagentStreamInterface, type CompiledSubAgentLike, type DeepAgentTypeConfigLike, type DefaultSubagentStates, type DefaultToolCall, type ExtractAgentConfig, type ExtractDeepAgentConfig, type ExtractSubAgentMiddleware, FetchStreamTransport, type FlushPendingHeadlessToolInterruptsOptions, type GetToolCallsType, type HeadlessToolImplementation, type HeadlessToolInterrupt, type InferAgentToolCalls, type InferBag, type InferDeepAgentSubagents, type InferNodeNames, type InferStateType, type InferSubagentByName, type InferSubagentNames, type InferSubagentState, type InferSubagentStates, type InferToolCalls, type IsAgentLike, type IsDeepAgentLike, type MessageMetadata, type OnToolCallback, type QueueEntry, type QueueInterface, type ResolveStreamInterface, type ResolveStreamOptions, StreamProvider, type StreamProviderCustomProps, type StreamProviderProps, type SubAgentLike, SubagentManager, type SubagentStateMap, type SubagentStatus, type SubagentStream, type SubagentStreamInterface, type SubagentToolCall, type SuspenseCache, type ToolCallFromTool, type ToolCallState, ToolCallWithResult, type ToolCallsFromTools, type ToolEvent, type UseAgentStream, type UseAgentStreamOptions, type UseDeepAgentStream, type UseDeepAgentStreamOptions, type UseStream, type UseStreamCustom, type UseStreamCustomOptions, type UseStreamOptions, type UseStreamThread, type UseStreamTransport, type UseSuspenseStream, calculateDepthFromNamespace, createSuspenseCache, executeHeadlessTool, extractParentIdFromNamespace, extractToolCallIdFromNamespace, filterOutHeadlessToolInterrupts, findHeadlessTool, flushPendingHeadlessToolInterrupts, handleHeadlessToolInterrupt, headlessToolResumeCommand, invalidateSuspenseCache, isHeadlessToolInterrupt, isSubagentNamespace, parseHeadlessToolInterruptPayload, useStream, useStreamContext, useSuspenseStream };
+export { type AgentServerAdapter, type AgentServerOptions, type AnyHeadlessToolImplementation, type AnyMediaHandle, type AnyStream, type AssembledToolCall, type AudioMedia, type AudioPlayerHandle, type Channel, type CustomAdapterOptions, type DefaultToolCall, type Event, type FileMedia, type FlushPendingHeadlessToolInterruptsOptions, type HeadlessToolImplementation, type HeadlessToolInterrupt, HttpAgentServerAdapter, type HttpAgentServerAdapterOptions, type ImageMedia, type InferStateType, type InferSubagentStates, type InferToolCalls, MediaAssemblyError, type MediaAssemblyErrorKind, type MediaBase, type MediaBlockType, type MessageMetadata, type MessageMetadataMap, type OnToolCallback, type PlayerStatus, STREAM_CONTROLLER, type SelectorTarget, StreamProvider, type StreamProviderCustomProps, type StreamProviderProps, type StreamSubmitOptions, type SubagentDiscoverySnapshot, type SubgraphDiscoverySnapshot, type SubmissionQueueEntry, type SubmissionQueueSnapshot, type ToolCallFromTool, type ToolCallState, type ToolCallStatus, ToolCallWithResult, type ToolCallsFromTools, type ToolEvent, type UseAudioPlayerOptions, type UseStreamOptions, type UseStreamResult, type UseStreamReturn, type UseSubmissionQueueReturn, type UseSuspenseStreamReturn, type UseVideoPlayerOptions, type VideoMedia, type VideoPlayerHandle, type WidenUpdateMessages, executeHeadlessTool, filterOutHeadlessToolInterrupts, findHeadlessTool, flushPendingHeadlessToolInterrupts, handleHeadlessToolInterrupt, headlessToolResumeCommand, isHeadlessToolInterrupt, parseHeadlessToolInterruptPayload, useAudio, useAudioPlayer, useChannel, useExtension, useFiles, useImages, useMediaURL, useMessageMetadata, useMessages, useProjection, useStream, useStreamContext, useSubmissionQueue, useSuspenseStream, useToolCalls, useValues, useVideo, useVideoPlayer };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"mappings":";;;;;;;;;;KAkFY,kBAAA,YAA8B,iBAAA,IACxC,oBAAA,CAAoB,QAAA,EAAU,WAAA,EAAiB,SAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"mappings":";;;;;;;;;;;;;KAkGY,kBAAA,YAA8B,iBAAA,IACxC,oBAAA,CAAoB,QAAA,EAAU,WAAA,EAAiB,SAAA"}

package/dist/index.js

@@ -1,7 +1,11 @@
-import { FetchStreamTransport } from "./stream.custom.js";
-import { useStream } from "./stream.js";
-import { createSuspenseCache, invalidateSuspenseCache, useSuspenseStream } from "./suspense-stream.js";
+import { STREAM_CONTROLLER, useStream } from "./use-stream.js";
+import { useProjection } from "./use-projection.js";
+import { useAudio, useChannel, useExtension, useFiles, useImages, useMessageMetadata, useMessages, useSubmissionQueue, useToolCalls, useValues, useVideo } from "./selectors.js";
+import { useMediaURL } from "./use-media-url.js";
+import { useAudioPlayer } from "./use-audio-player.js";
+import { useVideoPlayer } from "./use-video-player.js";
+import { useSuspenseStream } from "./suspense-stream.js";
 import { StreamProvider, useStreamContext } from "./context.js";
-import { SubagentManager, calculateDepthFromNamespace, extractParentIdFromNamespace, extractToolCallIdFromNamespace, isSubagentNamespace } from "@langchain/langgraph-sdk/ui";
-import { executeHeadlessTool, filterOutHeadlessToolInterrupts, findHeadlessTool, flushPendingHeadlessToolInterrupts, handleHeadlessToolInterrupt, headlessToolResumeCommand, isHeadlessToolInterrupt, parseHeadlessToolInterruptPayload } from "@langchain/langgraph-sdk";
-export { FetchStreamTransport, StreamProvider, SubagentManager, calculateDepthFromNamespace, createSuspenseCache, executeHeadlessTool, extractParentIdFromNamespace, extractToolCallIdFromNamespace, filterOutHeadlessToolInterrupts, findHeadlessTool, flushPendingHeadlessToolInterrupts, handleHeadlessToolInterrupt, headlessToolResumeCommand, invalidateSuspenseCache, isHeadlessToolInterrupt, isSubagentNamespace, parseHeadlessToolInterruptPayload, useStream, useStreamContext, useSuspenseStream };
+import { HttpAgentServerAdapter, executeHeadlessTool, filterOutHeadlessToolInterrupts, findHeadlessTool, flushPendingHeadlessToolInterrupts, handleHeadlessToolInterrupt, headlessToolResumeCommand, isHeadlessToolInterrupt, parseHeadlessToolInterruptPayload } from "@langchain/langgraph-sdk";
+import { MediaAssemblyError } from "@langchain/langgraph-sdk/stream";
+export { HttpAgentServerAdapter, MediaAssemblyError, STREAM_CONTROLLER, StreamProvider, executeHeadlessTool, filterOutHeadlessToolInterrupts, findHeadlessTool, flushPendingHeadlessToolInterrupts, handleHeadlessToolInterrupt, headlessToolResumeCommand, isHeadlessToolInterrupt, parseHeadlessToolInterruptPayload, useAudio, useAudioPlayer, useChannel, useExtension, useFiles, useImages, useMediaURL, useMessageMetadata, useMessages, useProjection, useStream, useStreamContext, useSubmissionQueue, useSuspenseStream, useToolCalls, useValues, useVideo, useVideoPlayer };

package/dist/selectors.cjs

@@ -0,0 +1,178 @@
+"use client";
+const require_use_stream = require("./use-stream.cjs");
+const require_use_projection = require("./use-projection.cjs");
+let react = require("react");
+let _langchain_langgraph_sdk_stream = require("@langchain/langgraph-sdk/stream");
+//#region src/selectors.ts
+function resolveNamespace(target) {
+	if (target == null) return EMPTY_NAMESPACE;
+	if (Array.isArray(target)) return target;
+	return target.namespace ?? EMPTY_NAMESPACE;
+}
+const EMPTY_NAMESPACE = [];
+function isRoot(namespace) {
+	return namespace.length === 0;
+}
+function namespaceKey(namespace) {
+	return namespace.join(_langchain_langgraph_sdk_stream.NAMESPACE_SEPARATOR);
+}
+/**
+* Subscribe to a scoped `messages` stream. Pass `stream` and
+* optionally a subagent/subgraph snapshot (or any namespaced target).
+*
+* Contract:
+*  - At the root (no target) this returns `stream.messages` directly
+*    — no extra subscription is opened. `stream.messages` is the
+*    live merge of `messages`-channel token deltas and
+*    `values.messages` snapshots (see
+*    {@link UseStreamReturn.messages}), so token-by-token
+*    streaming here depends on the backend emitting `messages`
+*    channel events. Backends that only emit `values` updates will
+*    render full turns at once rather than streaming.
+*  - For any other namespace, the mount triggers a ref-counted
+*    `messages` subscription scoped to that namespace. Unmounting
+*    the last component that watches this namespace closes the
+*    subscription automatically.
+*
+* Messages are always `BaseMessage` class instances from
+* `@langchain/core/messages`.
+*/
+function useMessages(stream, target) {
+	const namespace = resolveNamespace(target);
+	const key = `messages|${namespaceKey(namespace)}`;
+	const scoped = require_use_projection.useProjection(isRoot(namespace) ? null : require_use_stream.getRegistry(stream), () => (0, _langchain_langgraph_sdk_stream.messagesProjection)(namespace), key, EMPTY_MESSAGES);
+	return isRoot(namespace) ? stream.messages : scoped;
+}
+const EMPTY_MESSAGES = [];
+function useToolCalls(stream, target) {
+	const namespace = resolveNamespace(target);
+	const key = `toolCalls|${namespaceKey(namespace)}`;
+	const scoped = require_use_projection.useProjection(isRoot(namespace) ? null : require_use_stream.getRegistry(stream), () => (0, _langchain_langgraph_sdk_stream.toolCallsProjection)(namespace), key, EMPTY_TOOLCALLS);
+	return isRoot(namespace) ? stream.toolCalls : scoped;
+}
+const EMPTY_TOOLCALLS = [];
+function useValues(stream, target, options) {
+	const namespace = resolveNamespace(target);
+	const messagesKey = options?.messagesKey ?? "messages";
+	const key = `values|${messagesKey}|${namespaceKey(namespace)}`;
+	const scoped = require_use_projection.useProjection(isRoot(namespace) ? null : require_use_stream.getRegistry(stream), () => (0, _langchain_langgraph_sdk_stream.valuesProjection)(namespace, messagesKey), key, void 0);
+	return isRoot(namespace) ? stream.values : scoped;
+}
+/**
+* Subscribe to a `custom:<name>` stream extension — most-recent
+* payload emitted by the transformer, scoped to the target namespace.
+*/
+function useExtension(stream, name, target) {
+	const namespace = resolveNamespace(target);
+	const key = `extension|${name}|${namespaceKey(namespace)}`;
+	return require_use_projection.useProjection(require_use_stream.getRegistry(stream), () => (0, _langchain_langgraph_sdk_stream.extensionProjection)(name, namespace), key, void 0);
+}
+/**
+* Raw-events escape hatch. Subscribes to one or more channels at a
+* namespace and returns a bounded buffer of raw protocol events.
+* Prefer {@link useMessages} / {@link useToolCalls} / {@link useValues}
+* for the common cases.
+*/
+/**
+* Subscribe to a scoped audio-media stream. Returns an array of
+* {@link AudioMedia} handles, one per message containing at least one
+* `AudioBlock` in the target namespace.
+*
+* Each handle is yielded on its first matching `content-block-start`,
+* exposes `.partialBytes` for live access, settles `.blob` /
+* `.objectURL` / `.transcript` on `message-finish`, and surfaces
+* fail-loud errors via `.error`.
+*
+* Pair with {@link useMediaURL} to turn a handle into an `<audio src>`.
+*/
+function useAudio(stream, target) {
+	const namespace = resolveNamespace(target);
+	const key = `audio|${namespaceKey(namespace)}`;
+	return require_use_projection.useProjection(require_use_stream.getRegistry(stream), () => (0, _langchain_langgraph_sdk_stream.audioProjection)(namespace), key, EMPTY_AUDIO);
+}
+const EMPTY_AUDIO = [];
+/**
+* Subscribe to a scoped image-media stream. See {@link useAudio} for
+* shared semantics; pair with {@link useMediaURL} for `<img src>`.
+*/
+function useImages(stream, target) {
+	const namespace = resolveNamespace(target);
+	const key = `images|${namespaceKey(namespace)}`;
+	return require_use_projection.useProjection(require_use_stream.getRegistry(stream), () => (0, _langchain_langgraph_sdk_stream.imagesProjection)(namespace), key, EMPTY_IMAGES);
+}
+const EMPTY_IMAGES = [];
+/**
+* Subscribe to a scoped video-media stream. See {@link useAudio} for
+* shared semantics; pair with {@link useMediaURL} for `<video src>`.
+*/
+function useVideo(stream, target) {
+	const namespace = resolveNamespace(target);
+	const key = `video|${namespaceKey(namespace)}`;
+	return require_use_projection.useProjection(require_use_stream.getRegistry(stream), () => (0, _langchain_langgraph_sdk_stream.videoProjection)(namespace), key, EMPTY_VIDEO);
+}
+const EMPTY_VIDEO = [];
+/**
+* Subscribe to a scoped file-media stream. See {@link useAudio} for
+* shared semantics; pair with {@link useMediaURL} for an
+* `<a download href>` target.
+*/
+function useFiles(stream, target) {
+	const namespace = resolveNamespace(target);
+	const key = `files|${namespaceKey(namespace)}`;
+	return require_use_projection.useProjection(require_use_stream.getRegistry(stream), () => (0, _langchain_langgraph_sdk_stream.filesProjection)(namespace), key, EMPTY_FILES);
+}
+const EMPTY_FILES = [];
+function useChannel(stream, channels, target, options) {
+	const namespace = resolveNamespace(target);
+	const channelKey = (0, react.useMemo)(() => [...channels].sort().join(","), [channels]);
+	const key = `channel|${options?.bufferSize ?? "default"}|${options?.replay ?? true ? "replay" : "live"}|${channelKey}|${namespaceKey(namespace)}`;
+	return require_use_projection.useProjection(require_use_stream.getRegistry(stream), () => (0, _langchain_langgraph_sdk_stream.channelProjection)(channels, namespace, options), key, EMPTY_EVENTS);
+}
+const EMPTY_EVENTS = [];
+/**
+* Read metadata recorded for a specific message id — today exposes
+* `parentCheckpointId`, the checkpoint the message was first seen on.
+* Designed for fork / edit flows:
+*
+* ```tsx
+* const { parentCheckpointId } = useMessageMetadata(stream, msg.id) ?? {};
+* if (parentCheckpointId) {
+*   await stream.submit(input, { forkFrom: { checkpointId: parentCheckpointId } });
+* }
+* ```
+*
+* Returns `undefined` when the id isn't known yet (e.g. the server
+* hasn't emitted `parent_checkpoint` for that message, or the message
+* arrived via `messages`-channel deltas only and no `values` snapshot
+* has landed for it yet).
+*/
+function useMessageMetadata(stream, messageId) {
+	const store = stream[require_use_stream.STREAM_CONTROLLER].messageMetadataStore;
+	const snapshot = (0, react.useSyncExternalStore)(store.subscribe, store.getSnapshot, store.getSnapshot);
+	return messageId == null ? void 0 : snapshot.get(messageId);
+}
+function useSubmissionQueue(stream) {
+	const controller = stream[require_use_stream.STREAM_CONTROLLER];
+	const store = controller.queueStore;
+	const entries = (0, react.useSyncExternalStore)(store.subscribe, store.getSnapshot, store.getSnapshot);
+	return (0, react.useMemo)(() => ({
+		entries,
+		size: entries.length,
+		cancel: (id) => controller.cancelQueued(id),
+		clear: () => controller.clearQueue()
+	}), [entries, controller]);
+}
+//#endregion
+exports.useAudio = useAudio;
+exports.useChannel = useChannel;
+exports.useExtension = useExtension;
+exports.useFiles = useFiles;
+exports.useImages = useImages;
+exports.useMessageMetadata = useMessageMetadata;
+exports.useMessages = useMessages;
+exports.useSubmissionQueue = useSubmissionQueue;
+exports.useToolCalls = useToolCalls;
+exports.useValues = useValues;
+exports.useVideo = useVideo;
+
+//# sourceMappingURL=selectors.cjs.map

package/dist/selectors.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"selectors.cjs","names":["NAMESPACE_SEPARATOR","useProjection","getRegistry","STREAM_CONTROLLER"],"sources":["../src/selectors.ts"],"sourcesContent":["/* __LC_ALLOW_ENTRYPOINT_SIDE_EFFECTS__ */\n\n\"use client\";\n\nimport { useMemo, useSyncExternalStore } from \"react\";\nimport type { BaseMessage } from \"@langchain/core/messages\";\nimport type {\n  MessageMetadata,\n  MessageMetadataMap,\n  SubmissionQueueEntry,\n  SubmissionQueueSnapshot,\n} from \"@langchain/langgraph-sdk/stream\";\nimport {\n  NAMESPACE_SEPARATOR,\n  audioProjection,\n  channelProjection,\n  extensionProjection,\n  filesProjection,\n  imagesProjection,\n  messagesProjection,\n  toolCallsProjection,\n  valuesProjection,\n  videoProjection,\n  type AssembledToolCall,\n  type AudioMedia,\n  type Channel,\n  type ChannelProjectionOptions,\n  type Event,\n  type FileMedia,\n  type ImageMedia,\n  type InferStateType,\n  type SubagentDiscoverySnapshot,\n  type SubgraphDiscoverySnapshot,\n  type VideoMedia,\n} from \"@langchain/langgraph-sdk/stream\";\nimport {\n  getRegistry,\n  STREAM_CONTROLLER,\n  type UseStreamReturn,\n} from \"./use-stream.js\";\nimport { useProjection } from \"./use-projection.js\";\n\n/**\n * Selector hooks don't need to carry `InterruptType` /\n * `ConfigurableType` — they only ever read state. Accepting a\n * `StateType`-parameterised stream (with the other two generics\n * widened to `any`) lets callers keep their full\n * `useStream<State, Interrupt, Configurable>()` handle\n * without re-declaring the interrupt / configurable shapes at every\n * selector call site.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\ntype StreamHandle<StateType extends object> = UseStreamReturn<\n  StateType,\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  any,\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  any\n>;\n\n/**\n * What a selector hook can be targeted at. Callers can pass any of:\n *  - `undefined`                      — root namespace (cheap: served by the always-on root store)\n *  - a {@link SubagentDiscoverySnapshot}  — the snapshot returned by `stream.subagents.get(...)`\n *  - a {@link SubgraphDiscoverySnapshot}  — the snapshot returned by `stream.subgraphs.get(...)`\n *  - an explicit `{ namespace: string[] }` — any other namespaced scope\n *  - a raw `string[]`                  — escape hatch identical to the object form\n */\nexport type SelectorTarget =\n  | undefined\n  | null\n  | readonly string[]\n  | { namespace: readonly string[] }\n  | SubagentDiscoverySnapshot\n  | SubgraphDiscoverySnapshot;\n\nfunction resolveNamespace(target: SelectorTarget): readonly string[] {\n  if (target == null) return EMPTY_NAMESPACE;\n  if (Array.isArray(target)) return target;\n  const obj = target as { namespace?: readonly string[] };\n  return obj.namespace ?? EMPTY_NAMESPACE;\n}\n\nconst EMPTY_NAMESPACE: readonly string[] = [];\n\nfunction isRoot(namespace: readonly string[]): boolean {\n  return namespace.length === 0;\n}\n\nfunction namespaceKey(namespace: readonly string[]): string {\n  return namespace.join(NAMESPACE_SEPARATOR);\n}\n\n// The stream type we accept for selectors — purposely loose so\n// selector hooks remain callable from components that don't carry\n// the exact State/Interrupt/Configurable generics. We use `any` for\n// all three generics because `UseStreamReturn` is\n// invariant in `State` and `Configurable` (they flow through both\n// reader and writer positions), so a concrete\n// `useStream<typeof agent>()` handle wouldn't flow into\n// a `<object, unknown, object>` slot otherwise.\n//\n// Typed selectors (`useValues<S>` etc.) use {@link StreamHandle}\n// above so the concrete `StateType` flows into the return; hooks\n// that don't depend on state (`useMessages`, `useAudio`, …) stay on\n// `AnyStream` for maximum flexibility.\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\ntype AnyStream = UseStreamReturn<any, any, any>;\n\n/**\n * Subscribe to a scoped `messages` stream. Pass `stream` and\n * optionally a subagent/subgraph snapshot (or any namespaced target).\n *\n * Contract:\n *  - At the root (no target) this returns `stream.messages` directly\n *    — no extra subscription is opened. `stream.messages` is the\n *    live merge of `messages`-channel token deltas and\n *    `values.messages` snapshots (see\n *    {@link UseStreamReturn.messages}), so token-by-token\n *    streaming here depends on the backend emitting `messages`\n *    channel events. Backends that only emit `values` updates will\n *    render full turns at once rather than streaming.\n *  - For any other namespace, the mount triggers a ref-counted\n *    `messages` subscription scoped to that namespace. Unmounting\n *    the last component that watches this namespace closes the\n *    subscription automatically.\n *\n * Messages are always `BaseMessage` class instances from\n * `@langchain/core/messages`.\n */\nexport function useMessages(\n  stream: AnyStream,\n  target?: SelectorTarget\n): BaseMessage[] {\n  const namespace = resolveNamespace(target);\n  const key = `messages|${namespaceKey(namespace)}`;\n  const registry = isRoot(namespace) ? null : getRegistry(stream);\n  const scoped = useProjection<BaseMessage[]>(\n    registry,\n    () => messagesProjection(namespace),\n    key,\n    EMPTY_MESSAGES\n  );\n  return isRoot(namespace) ? stream.messages : scoped;\n}\n\nconst EMPTY_MESSAGES: BaseMessage[] = [];\n\n/**\n * Subscribe to a scoped `tools` (tool-call) stream. Same target and\n * lifecycle rules as {@link useMessages}; at the root this just returns\n * `stream.toolCalls`.\n *\n * The optional generic `T` can be passed to narrow the type of\n * `toolCall.args` on the returned array. Accepts either:\n *  - an agent brand (`typeof agent`) — union is derived from the\n *    agent's declared tools;\n *  - an array of LangGraph tools (`typeof tools`) — union is derived\n *    from `ToolCallFromTool<T[number]>`;\n *  - any direct `DefaultToolCall` shape.\n *\n * When omitted, returns the plain `AssembledToolCall[]` union used by\n * the controller.\n */\n// eslint-disable-next-line @typescript-eslint/no-unused-vars\nexport function useToolCalls(\n  stream: AnyStream,\n  target?: SelectorTarget\n): AssembledToolCall[];\nexport function useToolCalls(\n  stream: AnyStream,\n  target?: SelectorTarget\n): AssembledToolCall[];\nexport function useToolCalls(\n  stream: AnyStream,\n  target?: SelectorTarget\n): AssembledToolCall[] {\n  const namespace = resolveNamespace(target);\n  const key = `toolCalls|${namespaceKey(namespace)}`;\n  const registry = isRoot(namespace) ? null : getRegistry(stream);\n  const scoped = useProjection<AssembledToolCall[]>(\n    registry,\n    () => toolCallsProjection(namespace),\n    key,\n    EMPTY_TOOLCALLS\n  );\n  return isRoot(namespace) ? stream.toolCalls : scoped;\n}\n\nconst EMPTY_TOOLCALLS: AssembledToolCall[] = [];\n\n/**\n * Subscribe to a scoped `values` stream — most-recent state payload\n * for a namespace. Equivalent to reading `stream.values` at the root.\n *\n * When the payload carries a `messages` array, it is coerced to\n * `BaseMessage` instances to keep parity with the root projection.\n *\n * Typing:\n *  - **Root** (`useValues(stream)`): returns the `StateType` declared\n *    on the parent `useStream<State>()` — no explicit\n *    generic required. Non-nullable because the root snapshot always\n *    carries `values` (falling back to `initialValues ?? {}`).\n *  - **Scoped** (`useValues(stream, target)`): the scoped payload can\n *    have a different shape than the root state (e.g. a subagent\n *    returning its own substate). Callers should annotate the\n *    expected shape explicitly: `useValues<SubagentState>(stream, sub)`.\n *    Defaults to `unknown` when not annotated.\n */\nexport function useValues<StateType extends object>(\n  stream: StreamHandle<StateType>\n): StateType;\n/**\n * Explicit-generic override. Accepts:\n *  - an agent brand or compiled graph (unwrapped via\n *    {@link InferStateType});\n *  - a plain state shape (returned as-is).\n *\n * The root-call form is non-nullable (the root snapshot is always\n * present); the scoped form returns `T | undefined` because a\n * projection may not have emitted a payload yet.\n */\nexport function useValues<T>(stream: AnyStream): InferStateType<T>;\nexport function useValues<T = unknown>(\n  stream: AnyStream,\n  target: SelectorTarget,\n  options?: { messagesKey?: string }\n): T | undefined;\nexport function useValues(\n  stream: AnyStream,\n  target?: SelectorTarget,\n  options?: { messagesKey?: string }\n): unknown {\n  const namespace = resolveNamespace(target);\n  const messagesKey = options?.messagesKey ?? \"messages\";\n  const key = `values|${messagesKey}|${namespaceKey(namespace)}`;\n  const registry = isRoot(namespace) ? null : getRegistry(stream);\n  const scoped = useProjection<unknown>(\n    registry,\n    () => valuesProjection<unknown>(namespace, messagesKey),\n    key,\n    undefined\n  );\n  return isRoot(namespace) ? stream.values : scoped;\n}\n\n/**\n * Subscribe to a `custom:<name>` stream extension — most-recent\n * payload emitted by the transformer, scoped to the target namespace.\n */\nexport function useExtension<T = unknown>(\n  stream: AnyStream,\n  name: string,\n  target?: SelectorTarget\n): T | undefined {\n  const namespace = resolveNamespace(target);\n  const key = `extension|${name}|${namespaceKey(namespace)}`;\n  return useProjection<T | undefined>(\n    getRegistry(stream),\n    () => extensionProjection<T>(name, namespace),\n    key,\n    undefined\n  );\n}\n\n/**\n * Raw-events escape hatch. Subscribes to one or more channels at a\n * namespace and returns a bounded buffer of raw protocol events.\n * Prefer {@link useMessages} / {@link useToolCalls} / {@link useValues}\n * for the common cases.\n */\n/**\n * Subscribe to a scoped audio-media stream. Returns an array of\n * {@link AudioMedia} handles, one per message containing at least one\n * `AudioBlock` in the target namespace.\n *\n * Each handle is yielded on its first matching `content-block-start`,\n * exposes `.partialBytes` for live access, settles `.blob` /\n * `.objectURL` / `.transcript` on `message-finish`, and surfaces\n * fail-loud errors via `.error`.\n *\n * Pair with {@link useMediaURL} to turn a handle into an `<audio src>`.\n */\nexport function useAudio(\n  stream: AnyStream,\n  target?: SelectorTarget\n): AudioMedia[] {\n  const namespace = resolveNamespace(target);\n  const key = `audio|${namespaceKey(namespace)}`;\n  return useProjection<AudioMedia[]>(\n    getRegistry(stream),\n    () => audioProjection(namespace),\n    key,\n    EMPTY_AUDIO\n  );\n}\n\nconst EMPTY_AUDIO: AudioMedia[] = [];\n\n/**\n * Subscribe to a scoped image-media stream. See {@link useAudio} for\n * shared semantics; pair with {@link useMediaURL} for `<img src>`.\n */\nexport function useImages(\n  stream: AnyStream,\n  target?: SelectorTarget\n): ImageMedia[] {\n  const namespace = resolveNamespace(target);\n  const key = `images|${namespaceKey(namespace)}`;\n  return useProjection<ImageMedia[]>(\n    getRegistry(stream),\n    () => imagesProjection(namespace),\n    key,\n    EMPTY_IMAGES\n  );\n}\n\nconst EMPTY_IMAGES: ImageMedia[] = [];\n\n/**\n * Subscribe to a scoped video-media stream. See {@link useAudio} for\n * shared semantics; pair with {@link useMediaURL} for `<video src>`.\n */\nexport function useVideo(\n  stream: AnyStream,\n  target?: SelectorTarget\n): VideoMedia[] {\n  const namespace = resolveNamespace(target);\n  const key = `video|${namespaceKey(namespace)}`;\n  return useProjection<VideoMedia[]>(\n    getRegistry(stream),\n    () => videoProjection(namespace),\n    key,\n    EMPTY_VIDEO\n  );\n}\n\nconst EMPTY_VIDEO: VideoMedia[] = [];\n\n/**\n * Subscribe to a scoped file-media stream. See {@link useAudio} for\n * shared semantics; pair with {@link useMediaURL} for an\n * `<a download href>` target.\n */\nexport function useFiles(\n  stream: AnyStream,\n  target?: SelectorTarget\n): FileMedia[] {\n  const namespace = resolveNamespace(target);\n  const key = `files|${namespaceKey(namespace)}`;\n  return useProjection<FileMedia[]>(\n    getRegistry(stream),\n    () => filesProjection(namespace),\n    key,\n    EMPTY_FILES\n  );\n}\n\nconst EMPTY_FILES: FileMedia[] = [];\n\nexport type UseChannelOptions = ChannelProjectionOptions;\n\nexport function useChannel(\n  stream: AnyStream,\n  channels: readonly Channel[],\n  target?: SelectorTarget,\n  options?: UseChannelOptions\n): Event[] {\n  const namespace = resolveNamespace(target);\n  const channelKey = useMemo(() => [...channels].sort().join(\",\"), [channels]);\n  const key = `channel|${options?.bufferSize ?? \"default\"}|${(options?.replay ?? true) ? \"replay\" : \"live\"}|${channelKey}|${namespaceKey(namespace)}`;\n  return useProjection<Event[]>(\n    getRegistry(stream),\n    () => channelProjection(channels, namespace, options),\n    key,\n    EMPTY_EVENTS\n  );\n}\n\nconst EMPTY_EVENTS: Event[] = [];\n\n/**\n * Read metadata recorded for a specific message id — today exposes\n * `parentCheckpointId`, the checkpoint the message was first seen on.\n * Designed for fork / edit flows:\n *\n * ```tsx\n * const { parentCheckpointId } = useMessageMetadata(stream, msg.id) ?? {};\n * if (parentCheckpointId) {\n *   await stream.submit(input, { forkFrom: { checkpointId: parentCheckpointId } });\n * }\n * ```\n *\n * Returns `undefined` when the id isn't known yet (e.g. the server\n * hasn't emitted `parent_checkpoint` for that message, or the message\n * arrived via `messages`-channel deltas only and no `values` snapshot\n * has landed for it yet).\n */\nexport function useMessageMetadata(\n  stream: AnyStream,\n  messageId: string | undefined\n): MessageMetadata | undefined {\n  const store = stream[STREAM_CONTROLLER].messageMetadataStore;\n  const snapshot = useSyncExternalStore<MessageMetadataMap>(\n    store.subscribe,\n    store.getSnapshot,\n    store.getSnapshot\n  );\n  return messageId == null ? undefined : snapshot.get(messageId);\n}\n\n/**\n * Reactive handle on the server-side submission queue.\n *\n * Populated when `submit()` is invoked with `multitaskStrategy:\n * \"enqueue\"` while another run is in flight. The returned object is\n * stable per snapshot so consumers can pass `entries` straight into a\n * `<Fragment key={e.id}>` list without extra memoisation.\n *\n * Today the queue is maintained client-side; once the server starts\n * emitting a dedicated queue channel (roadmap A0.3) the controller\n * will mirror that state directly — the hook surface will not change.\n */\nexport interface UseSubmissionQueueReturn<\n  StateType extends object = Record<string, unknown>,\n> {\n  readonly entries: SubmissionQueueSnapshot<StateType>;\n  readonly size: number;\n  cancel(id: string): Promise<boolean>;\n  clear(): Promise<void>;\n}\n\nexport function useSubmissionQueue<StateType extends object>(\n  stream: StreamHandle<StateType>\n): UseSubmissionQueueReturn<StateType>;\nexport function useSubmissionQueue(stream: AnyStream): UseSubmissionQueueReturn;\nexport function useSubmissionQueue(\n  stream: AnyStream\n): UseSubmissionQueueReturn {\n  const controller = stream[STREAM_CONTROLLER];\n  const store = controller.queueStore;\n  const entries = useSyncExternalStore<SubmissionQueueSnapshot>(\n    store.subscribe,\n    store.getSnapshot,\n    store.getSnapshot\n  );\n  return useMemo<UseSubmissionQueueReturn>(\n    () => ({\n      entries,\n      size: entries.length,\n      cancel: (id) => controller.cancelQueued(id),\n      clear: () => controller.clearQueue(),\n    }),\n    [entries, controller]\n  );\n}\n\nexport type { SubmissionQueueEntry, SubmissionQueueSnapshot };\n"],"mappings":"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"}

package/dist/selectors.d.cts

@@ -0,0 +1,183 @@
+import { UseStreamReturn } from "./use-stream.cjs";
+import { BaseMessage } from "@langchain/core/messages";
+import { AssembledToolCall, AudioMedia, Channel, ChannelProjectionOptions, Event, FileMedia, ImageMedia, InferStateType, MessageMetadata, SubagentDiscoverySnapshot, SubgraphDiscoverySnapshot, SubmissionQueueEntry, SubmissionQueueSnapshot, VideoMedia } from "@langchain/langgraph-sdk/stream";
+
+//#region src/selectors.d.ts
+/**
+ * Selector hooks don't need to carry `InterruptType` /
+ * `ConfigurableType` — they only ever read state. Accepting a
+ * `StateType`-parameterised stream (with the other two generics
+ * widened to `any`) lets callers keep their full
+ * `useStream<State, Interrupt, Configurable>()` handle
+ * without re-declaring the interrupt / configurable shapes at every
+ * selector call site.
+ */
+type StreamHandle<StateType extends object> = UseStreamReturn<StateType, any, any>;
+/**
+ * What a selector hook can be targeted at. Callers can pass any of:
+ *  - `undefined`                      — root namespace (cheap: served by the always-on root store)
+ *  - a {@link SubagentDiscoverySnapshot}  — the snapshot returned by `stream.subagents.get(...)`
+ *  - a {@link SubgraphDiscoverySnapshot}  — the snapshot returned by `stream.subgraphs.get(...)`
+ *  - an explicit `{ namespace: string[] }` — any other namespaced scope
+ *  - a raw `string[]`                  — escape hatch identical to the object form
+ */
+type SelectorTarget = undefined | null | readonly string[] | {
+  namespace: readonly string[];
+} | SubagentDiscoverySnapshot | SubgraphDiscoverySnapshot;
+type AnyStream = UseStreamReturn<any, any, any>;
+/**
+ * Subscribe to a scoped `messages` stream. Pass `stream` and
+ * optionally a subagent/subgraph snapshot (or any namespaced target).
+ *
+ * Contract:
+ *  - At the root (no target) this returns `stream.messages` directly
+ *    — no extra subscription is opened. `stream.messages` is the
+ *    live merge of `messages`-channel token deltas and
+ *    `values.messages` snapshots (see
+ *    {@link UseStreamReturn.messages}), so token-by-token
+ *    streaming here depends on the backend emitting `messages`
+ *    channel events. Backends that only emit `values` updates will
+ *    render full turns at once rather than streaming.
+ *  - For any other namespace, the mount triggers a ref-counted
+ *    `messages` subscription scoped to that namespace. Unmounting
+ *    the last component that watches this namespace closes the
+ *    subscription automatically.
+ *
+ * Messages are always `BaseMessage` class instances from
+ * `@langchain/core/messages`.
+ */
+declare function useMessages(stream: AnyStream, target?: SelectorTarget): BaseMessage[];
+/**
+ * Subscribe to a scoped `tools` (tool-call) stream. Same target and
+ * lifecycle rules as {@link useMessages}; at the root this just returns
+ * `stream.toolCalls`.
+ *
+ * The optional generic `T` can be passed to narrow the type of
+ * `toolCall.args` on the returned array. Accepts either:
+ *  - an agent brand (`typeof agent`) — union is derived from the
+ *    agent's declared tools;
+ *  - an array of LangGraph tools (`typeof tools`) — union is derived
+ *    from `ToolCallFromTool<T[number]>`;
+ *  - any direct `DefaultToolCall` shape.
+ *
+ * When omitted, returns the plain `AssembledToolCall[]` union used by
+ * the controller.
+ */
+declare function useToolCalls(stream: AnyStream, target?: SelectorTarget): AssembledToolCall[];
+declare function useToolCalls(stream: AnyStream, target?: SelectorTarget): AssembledToolCall[];
+/**
+ * Subscribe to a scoped `values` stream — most-recent state payload
+ * for a namespace. Equivalent to reading `stream.values` at the root.
+ *
+ * When the payload carries a `messages` array, it is coerced to
+ * `BaseMessage` instances to keep parity with the root projection.
+ *
+ * Typing:
+ *  - **Root** (`useValues(stream)`): returns the `StateType` declared
+ *    on the parent `useStream<State>()` — no explicit
+ *    generic required. Non-nullable because the root snapshot always
+ *    carries `values` (falling back to `initialValues ?? {}`).
+ *  - **Scoped** (`useValues(stream, target)`): the scoped payload can
+ *    have a different shape than the root state (e.g. a subagent
+ *    returning its own substate). Callers should annotate the
+ *    expected shape explicitly: `useValues<SubagentState>(stream, sub)`.
+ *    Defaults to `unknown` when not annotated.
+ */
+declare function useValues<StateType extends object>(stream: StreamHandle<StateType>): StateType;
+/**
+ * Explicit-generic override. Accepts:
+ *  - an agent brand or compiled graph (unwrapped via
+ *    {@link InferStateType});
+ *  - a plain state shape (returned as-is).
+ *
+ * The root-call form is non-nullable (the root snapshot is always
+ * present); the scoped form returns `T | undefined` because a
+ * projection may not have emitted a payload yet.
+ */
+declare function useValues<T>(stream: AnyStream): InferStateType<T>;
+declare function useValues<T = unknown>(stream: AnyStream, target: SelectorTarget, options?: {
+  messagesKey?: string;
+}): T | undefined;
+/**
+ * Subscribe to a `custom:<name>` stream extension — most-recent
+ * payload emitted by the transformer, scoped to the target namespace.
+ */
+declare function useExtension<T = unknown>(stream: AnyStream, name: string, target?: SelectorTarget): T | undefined;
+/**
+ * Raw-events escape hatch. Subscribes to one or more channels at a
+ * namespace and returns a bounded buffer of raw protocol events.
+ * Prefer {@link useMessages} / {@link useToolCalls} / {@link useValues}
+ * for the common cases.
+ */
+/**
+ * Subscribe to a scoped audio-media stream. Returns an array of
+ * {@link AudioMedia} handles, one per message containing at least one
+ * `AudioBlock` in the target namespace.
+ *
+ * Each handle is yielded on its first matching `content-block-start`,
+ * exposes `.partialBytes` for live access, settles `.blob` /
+ * `.objectURL` / `.transcript` on `message-finish`, and surfaces
+ * fail-loud errors via `.error`.
+ *
+ * Pair with {@link useMediaURL} to turn a handle into an `<audio src>`.
+ */
+declare function useAudio(stream: AnyStream, target?: SelectorTarget): AudioMedia[];
+/**
+ * Subscribe to a scoped image-media stream. See {@link useAudio} for
+ * shared semantics; pair with {@link useMediaURL} for `<img src>`.
+ */
+declare function useImages(stream: AnyStream, target?: SelectorTarget): ImageMedia[];
+/**
+ * Subscribe to a scoped video-media stream. See {@link useAudio} for
+ * shared semantics; pair with {@link useMediaURL} for `<video src>`.
+ */
+declare function useVideo(stream: AnyStream, target?: SelectorTarget): VideoMedia[];
+/**
+ * Subscribe to a scoped file-media stream. See {@link useAudio} for
+ * shared semantics; pair with {@link useMediaURL} for an
+ * `<a download href>` target.
+ */
+declare function useFiles(stream: AnyStream, target?: SelectorTarget): FileMedia[];
+type UseChannelOptions = ChannelProjectionOptions;
+declare function useChannel(stream: AnyStream, channels: readonly Channel[], target?: SelectorTarget, options?: UseChannelOptions): Event[];
+/**
+ * Read metadata recorded for a specific message id — today exposes
+ * `parentCheckpointId`, the checkpoint the message was first seen on.
+ * Designed for fork / edit flows:
+ *
+ * ```tsx
+ * const { parentCheckpointId } = useMessageMetadata(stream, msg.id) ?? {};
+ * if (parentCheckpointId) {
+ *   await stream.submit(input, { forkFrom: { checkpointId: parentCheckpointId } });
+ * }
+ * ```
+ *
+ * Returns `undefined` when the id isn't known yet (e.g. the server
+ * hasn't emitted `parent_checkpoint` for that message, or the message
+ * arrived via `messages`-channel deltas only and no `values` snapshot
+ * has landed for it yet).
+ */
+declare function useMessageMetadata(stream: AnyStream, messageId: string | undefined): MessageMetadata | undefined;
+/**
+ * Reactive handle on the server-side submission queue.
+ *
+ * Populated when `submit()` is invoked with `multitaskStrategy:
+ * "enqueue"` while another run is in flight. The returned object is
+ * stable per snapshot so consumers can pass `entries` straight into a
+ * `<Fragment key={e.id}>` list without extra memoisation.
+ *
+ * Today the queue is maintained client-side; once the server starts
+ * emitting a dedicated queue channel (roadmap A0.3) the controller
+ * will mirror that state directly — the hook surface will not change.
+ */
+interface UseSubmissionQueueReturn<StateType extends object = Record<string, unknown>> {
+  readonly entries: SubmissionQueueSnapshot<StateType>;
+  readonly size: number;
+  cancel(id: string): Promise<boolean>;
+  clear(): Promise<void>;
+}
+declare function useSubmissionQueue<StateType extends object>(stream: StreamHandle<StateType>): UseSubmissionQueueReturn<StateType>;
+declare function useSubmissionQueue(stream: AnyStream): UseSubmissionQueueReturn;
+//#endregion
+export { SelectorTarget, type SubmissionQueueEntry, type SubmissionQueueSnapshot, UseSubmissionQueueReturn, useAudio, useChannel, useExtension, useFiles, useImages, useMessageMetadata, useMessages, useSubmissionQueue, useToolCalls, useValues, useVideo };
+//# sourceMappingURL=selectors.d.cts.map

package/dist/selectors.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"selectors.d.cts","names":[],"sources":["../src/selectors.ts"],"mappings":";;;;;;AAuCyB;;;;;;;;KAapB,YAAA,6BAAyC,eAAA,CAC5C,SAAA;AAeF;;;;;;;;AAAA,KAAY,cAAA;EAIN,SAAA;AAAA,IACF,yBAAA,GACA,yBAAA;AAAA,KAiCC,SAAA,GAAY,eAAA;;;AAuBjB;;;;;;;;;;;;;;;AAmCA;;;;iBAnCgB,WAAA,CACd,MAAA,EAAQ,SAAA,EACR,MAAA,GAAS,cAAA,GACR,WAAA;;;;;;;;;;;AAoCH;;;;;;iBAJgB,YAAA,CACd,MAAA,EAAQ,SAAA,EACR,MAAA,GAAS,cAAA,GACR,iBAAA;AAAA,iBACa,YAAA,CACd,MAAA,EAAQ,SAAA,EACR,MAAA,GAAS,cAAA,GACR,iBAAA;;;;;;;;AAqCH;;;;;;;;;;;iBAAgB,SAAA,0BAAA,CACd,MAAA,EAAQ,YAAA,CAAa,SAAA,IACpB,SAAA;;;;AAWH;;;;;;;iBAAgB,SAAA,GAAA,CAAa,MAAA,EAAQ,SAAA,GAAY,cAAA,CAAe,CAAA;AAAA,iBAChD,SAAA,aAAA,CACd,MAAA,EAAQ,SAAA,EACR,MAAA,EAAQ,cAAA,EACR,OAAA;EAAY,WAAA;AAAA,IACX,CAAA;;;;;iBAuBa,YAAA,aAAA,CACd,MAAA,EAAQ,SAAA,EACR,IAAA,UACA,MAAA,GAAS,cAAA,GACR,CAAA;;;;;;;;;;;;;;;;;;AAJH;iBAiCgB,QAAA,CACd,MAAA,EAAQ,SAAA,EACR,MAAA,GAAS,cAAA,GACR,UAAA;;;;;iBAiBa,SAAA,CACd,MAAA,EAAQ,SAAA,EACR,MAAA,GAAS,cAAA,GACR,UAAA;;;;;iBAiBa,QAAA,CACd,MAAA,EAAQ,SAAA,EACR,MAAA,GAAS,cAAA,GACR,UAAA;;;;;;iBAkBa,QAAA,CACd,MAAA,EAAQ,SAAA,EACR,MAAA,GAAS,cAAA,GACR,SAAA;AAAA,KAaS,iBAAA,GAAoB,wBAAA;AAAA,iBAEhB,UAAA,CACd,MAAA,EAAQ,SAAA,EACR,QAAA,WAAmB,OAAA,IACnB,MAAA,GAAS,cAAA,EACT,OAAA,GAAU,iBAAA,GACT,KAAA;;;;;;;;;;;;;AAhEH;;;;;iBA+FgB,kBAAA,CACd,MAAA,EAAQ,SAAA,EACR,SAAA,uBACC,eAAA;;;;;;;;;;AA9EH;;;UAoGiB,wBAAA,4BACY,MAAA;EAAA,SAElB,OAAA,EAAS,uBAAA,CAAwB,SAAA;EAAA,SACjC,IAAA;EACT,MAAA,CAAO,EAAA,WAAa,OAAA;EACpB,KAAA,IAAS,OAAA;AAAA;AAAA,iBAGK,kBAAA,0BAAA,CACd,MAAA,EAAQ,YAAA,CAAa,SAAA,IACpB,wBAAA,CAAyB,SAAA;AAAA,iBACZ,kBAAA,CAAmB,MAAA,EAAQ,SAAA,GAAY,wBAAA"}