@epam/ai-dial-chat-hooks 1.3.0-dev.10 → 1.3.0-dev.103

package/conversation/useConversationHandlers/useConversationHandlers.d.ts

@@ -0,0 +1,66 @@
+import { ConversationsApi, FilesApi, RateApi, SendCompletionDtoModeEnum } from '@epam/ai-dial-chat-api-client';
+import { Attachment, Conversation, DisplayAttachment, MessageCustomContent, MessageRating, RequestSkill, StarterOption, UploadedAttachmentResult } from '@epam/ai-dial-chat-shared';
+import { ConversationStateAccessor, StartStreamOptions } from '../useConversationStream/useConversationStream';
+/** The exact `startStream` shape `useConversationStream` returns. */
+export type ConversationStreamStarter = (conversationPath: string, userContent: string, messageIndex: number, model: string, customContent?: MessageCustomContent, generationId?: string, mode?: SendCompletionDtoModeEnum, options?: StartStreamOptions) => void;
+/** Parameters for {@link useConversationHandlers}. */
+export interface UseConversationHandlersParams {
+    conversation: Conversation | null;
+    conversationId: string | undefined;
+    bucket: string | undefined;
+    isStreaming: boolean;
+    /** The `startStream` function returned by `useConversationStream`. */
+    startStream: ConversationStreamStarter;
+    /** Shared mutable channel for the displayed conversation — the same one passed to `useConversationStream`. */
+    state: ConversationStateAccessor;
+    /** Already-configured generated-client instance used to upload attachments. */
+    filesApi: Pick<FilesApi, 'uploadFile'>;
+    /** Already-configured generated-client instance used to save/delete the conversation. */
+    conversationsApi: Pick<ConversationsApi, 'saveConversation' | 'deleteConversation'>;
+    /** Already-configured generated-client instance used to rate a message. */
+    rateApi: Pick<RateApi, 'rateMessage'>;
+    /** Resolves the model id to send with the next completion. Re-evaluated on every call — never cached. */
+    resolveModelId: () => string;
+    /** Called when deleting the last message also deletes the whole conversation. */
+    onConversationDeleted?: () => void;
+    /** Called with batched filenames after a burst of network-error upload failures. */
+    showNetworkError?: (filenames: string[]) => void;
+    /** Tool toggle configuration values merged into every outgoing completion request. */
+    toolConfigurationValue?: Record<string, boolean>;
+}
+/** Return value of {@link useConversationHandlers}. */
+export interface UseConversationHandlersResult {
+    handleSend: (message: string, attachments: Attachment[], skills?: RequestSkill[]) => Promise<void>;
+    handleUploadAttachment: (attachment: Attachment) => Promise<UploadedAttachmentResult>;
+    handleRegenerateMessage: (messageIndex: number) => void;
+    handleDeleteMessage: (messageIndex: number) => void;
+    handleConfirmDelete: () => void;
+    handleRateMessage: (messageIndex: number, rating: MessageRating | null, comment?: string) => Promise<boolean>;
+    handleButtonSelect: (starter: StarterOption, propertyKey?: string, description?: string) => void;
+    handleConfirmStarter: () => void;
+    handleStartEdit: (messageIndex: number) => void;
+    handleCancelEdit: (messageIndex: number) => void;
+    handleEditMessage: (messageIndex: number, text: string, keptDisplayAttachments: DisplayAttachment[], newAttachments: Attachment[], skills?: RequestSkill[]) => Promise<void>;
+    editingMessageIndexes: Set<number>;
+    pendingDeleteIndex: number | null;
+    setPendingDeleteIndex: (index: number | null) => void;
+    pendingStarterContext: {
+        starter: StarterOption;
+        propertyKey?: string;
+        description?: string;
+    } | null;
+    setPendingStarterContext: (context: {
+        starter: StarterOption;
+        propertyKey?: string;
+        description?: string;
+    } | null) => void;
+}
+/**
+ * Composes send/regenerate/edit/delete/rate/starter-submission orchestration
+ * on top of the library's own `useAttachmentUpload` and the injected
+ * `startStream` (from `useConversationStream`). Optimistic message-pair
+ * insertion, delete confirmation, and rate revert-on-failure all mutate the
+ * shared `state` channel directly, in lockstep with the streaming hook.
+ */
+export declare const useConversationHandlers: ({ conversation, conversationId, bucket, isStreaming, startStream, state: { setConversation, conversationRef }, filesApi, conversationsApi, rateApi, resolveModelId, onConversationDeleted, showNetworkError, toolConfigurationValue, }: UseConversationHandlersParams) => UseConversationHandlersResult;
+//# sourceMappingURL=useConversationHandlers.d.ts.map

package/conversation/useConversationHandlers/useConversationHandlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useConversationHandlers.d.ts","sourceRoot":"","sources":["../../../src/conversation/useConversationHandlers/useConversationHandlers.ts"],"names":[],"mappings":"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"}

package/conversation/useConversationImport/useConversationImport.d.ts

@@ -0,0 +1,54 @@
+import { ConversationsApi, FilesApi } from '@epam/ai-dial-chat-api-client';
+import { ConversationTransferJob } from '@epam/ai-dial-chat-shared';
+import { ConversationTransferErrorEvent, ConversationTransferSuccessEvent, ConversationTransferWarningEvent } from '../conversation-transfer/types';
+/** Parameters for {@link useConversationImport}. */
+export interface UseConversationImportParams {
+    /** Already-configured generated-client instance used to persist imported conversations. */
+    conversationsApi: Pick<ConversationsApi, 'saveConversation'>;
+    /** Already-configured generated-client instance used to list/upload attachments. */
+    filesApi: Pick<FilesApi, 'listFiles' | 'uploadFile'>;
+    /** The current user's DIAL Core storage bucket. Import fails with `MissingBucket` when `undefined`. */
+    bucket: string | undefined;
+    /** Called after at least one conversation in a job was imported successfully. */
+    onImported?: () => Promise<void> | void;
+    /** Classifies a thrown error as unauthorized. Host-owned error taxonomy; defaults to never. */
+    classifyTransferError?: (error: unknown) => {
+        isUnauthorized?: boolean;
+    };
+    /** Resolves a trace id for a failing request, for display in an error notification. */
+    resolveErrorTraceId?: (error: unknown) => Promise<string | undefined>;
+    /** Called when a job completes with at least one successfully imported conversation. */
+    onSuccess?: (event: ConversationTransferSuccessEvent) => void;
+    /** Called when a job succeeds but had to skip an attachment. */
+    onWarning?: (event: ConversationTransferWarningEvent) => void;
+    /** Called when a job fails, or when some conversations within it failed. */
+    onError?: (event: ConversationTransferErrorEvent) => void;
+}
+/** Return value of {@link useConversationImport}. */
+export interface UseConversationImportResult {
+    /** Import jobs, most recently added last. Multiple jobs can be in progress concurrently. */
+    jobs: ConversationTransferJob[];
+    /** Parses the given file and starts importing it as a new job. */
+    importConversations: (file: File) => Promise<void>;
+    /** Aborts a job's underlying requests and marks it canceled, keeping it in `jobs`. */
+    cancelJob: (jobId: string) => void;
+    /** Removes a job from the queue. If still in progress, aborts its underlying requests. */
+    dismissJob: (jobId: string) => void;
+    /** Re-attempts a failed or canceled job in place (same job id, reusing the already-parsed file). */
+    retryJob: (jobId: string) => void;
+    /** Aborts all in-progress jobs and clears the entire queue. */
+    dismissAll: () => void;
+}
+/**
+ * Owns the import job queue: parses a selected export file (`.json` or
+ * `.dial`/`.zip`, v5 envelope, old- or new-chat origin) once per file, then
+ * re-uploads any archive attachments to `uploads/<YYYY-MM>/` —
+ * disambiguating a name collision with a ` (n)` suffix instead of rejecting
+ * it — rewrites attachment references (and renamed titles), drops any
+ * reference still pointing into another user's bucket, regenerates each
+ * conversation's id/path with a fresh UUID (collision-free save, no replace
+ * dialog), and persists every conversation through the injected
+ * `conversationsApi`. One job per imported file, not per conversation.
+ */
+export declare const useConversationImport: ({ conversationsApi, filesApi, bucket, onImported, classifyTransferError, resolveErrorTraceId, onSuccess, onWarning, onError, }: UseConversationImportParams) => UseConversationImportResult;
+//# sourceMappingURL=useConversationImport.d.ts.map

package/conversation/useConversationImport/useConversationImport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useConversationImport.d.ts","sourceRoot":"","sources":["../../../src/conversation/useConversationImport/useConversationImport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,gBAAgB,EAChB,QAAQ,EACT,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAEL,KAAK,uBAAuB,EAK7B,MAAM,2BAA2B,CAAC;AAwBnC,OAAO,EACL,KAAK,8BAA8B,EACnC,KAAK,gCAAgC,EAErC,KAAK,gCAAgC,EACtC,MAAM,gCAAgC,CAAC;AAgExC,oDAAoD;AACpD,MAAM,WAAW,2BAA2B;IAC1C,2FAA2F;IAC3F,gBAAgB,EAAE,IAAI,CAAC,gBAAgB,EAAE,kBAAkB,CAAC,CAAC;IAC7D,oFAAoF;IACpF,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,WAAW,GAAG,YAAY,CAAC,CAAC;IACrD,uGAAuG;IACvG,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,iFAAiF;IACjF,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACxC,+FAA+F;IAC/F,qBAAqB,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK;QAAE,cAAc,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IACzE,uFAAuF;IACvF,mBAAmB,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACtE,wFAAwF;IACxF,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,gCAAgC,KAAK,IAAI,CAAC;IAC9D,gEAAgE;IAChE,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,gCAAgC,KAAK,IAAI,CAAC;IAC9D,4EAA4E;IAC5E,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,8BAA8B,KAAK,IAAI,CAAC;CAC3D;AA8GD,qDAAqD;AACrD,MAAM,WAAW,2BAA2B;IAC1C,4FAA4F;IAC5F,IAAI,EAAE,uBAAuB,EAAE,CAAC;IAChC,kEAAkE;IAClE,mBAAmB,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,sFAAsF;IACtF,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC,0FAA0F;IAC1F,UAAU,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC,oGAAoG;IACpG,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,+DAA+D;IAC/D,UAAU,EAAE,MAAM,IAAI,CAAC;CACxB;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB,GAAI,gIAUnC,2BAA2B,KAAG,2BA+ThC,CAAC"}

package/conversation/useConversationLookupMaps/useConversationLookupMaps.d.ts

@@ -0,0 +1,24 @@
+import { ConversationListItemDto } from '@epam/ai-dial-chat-api-client';
+/** Parameters for `useConversationLookupMaps`. */
+export interface UseConversationLookupMapsParams {
+    /** Raw conversation list from the API. */
+    items: ConversationListItemDto[];
+    /** Converts a raw conversation id to the panel-space id. App-specific. */
+    toPanelConversationId: (id: string) => string;
+}
+/** Stable reverse-lookup maps returned by `useConversationLookupMaps`. */
+export interface ConversationLookupMaps {
+    /** Returns the raw context id for a panel-space conversation id, or `undefined` when not found. */
+    toContextId: (panelId: string) => string | undefined;
+    /** Returns the raw `ConversationListItemDto` for a panel-space conversation id, or `undefined` when not found. */
+    getRawItem: (panelId: string) => ConversationListItemDto | undefined;
+}
+/**
+ * Builds two memoised reverse-lookup maps from the raw conversation list:
+ * panel-space id → context id and panel-space id → raw DTO.
+ *
+ * Replaces the inlined `panelToContextId` map and `items.find` calls that
+ * previously appeared at each row-action call site in `ConversationPanelView`.
+ */
+export declare const useConversationLookupMaps: ({ items, toPanelConversationId, }: UseConversationLookupMapsParams) => ConversationLookupMaps;
+//# sourceMappingURL=useConversationLookupMaps.d.ts.map

package/conversation/useConversationLookupMaps/useConversationLookupMaps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useConversationLookupMaps.d.ts","sourceRoot":"","sources":["../../../src/conversation/useConversationLookupMaps/useConversationLookupMaps.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AAG7E,kDAAkD;AAClD,MAAM,WAAW,+BAA+B;IAC9C,0CAA0C;IAC1C,KAAK,EAAE,uBAAuB,EAAE,CAAC;IACjC,0EAA0E;IAC1E,qBAAqB,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,CAAC;CAC/C;AAED,0EAA0E;AAC1E,MAAM,WAAW,sBAAsB;IACrC,mGAAmG;IACnG,WAAW,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IACrD,kHAAkH;IAClH,UAAU,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,uBAAuB,GAAG,SAAS,CAAC;CACtE;AAED;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,GAAI,mCAGvC,+BAA+B,KAAG,sBAaD,CAAC"}

package/conversation/useConversationPanelItems/useConversationPanelItems.d.ts

@@ -0,0 +1,64 @@
+import { ConversationListItemDto, DeploymentItemDto } from '@epam/ai-dial-chat-api-client';
+import { FilterTab } from '@epam/ai-dial-chat-shared';
+import { ReactNode } from 'react';
+/**
+ * Classifies a conversation's ownership using the shared filter-tab contract.
+ */
+export declare const getConversationSource: (item: Pick<ConversationListItemDto, "sharedWithMe" | "publishedWithMe">) => FilterTab;
+/** Resolver callbacks injected by the host app into `useConversationPanelItems`. */
+export interface UseConversationPanelItemsResolvers {
+    /** Converts a raw conversation id to the panel-space id. App-specific. */
+    toPanelConversationId: (id: string) => string;
+    /** Resolves the icon URL for a deployment. Returns `undefined` when not available. */
+    resolveIconUrl: (deployment: DeploymentItemDto | undefined) => string | undefined;
+    /**
+     * Resolves the icon tooltip text. Receives the matched deployment (or
+     * `undefined`) and a decoded fallback string derived from the model path.
+     */
+    resolveIconTooltip: (deployment: DeploymentItemDto | undefined, fallback: string) => string | undefined;
+    /** Resolves the href to navigate to when the conversation row is clicked. */
+    resolveHref: (panelConversationId: string) => string;
+    /**
+     * Returns the row presentation for a scheduled-task conversation — a
+     * host-rendered leading icon that replaces the deployment avatar, and the
+     * unread flag — or `undefined` for an ordinary conversation.
+     */
+    resolveTaskPresentation?: (item: ConversationListItemDto) => {
+        leadingIcon?: ReactNode;
+        isUnread: boolean;
+    } | undefined;
+}
+/** Parameters accepted by `useConversationPanelItems`. */
+export interface UseConversationPanelItemsParams extends UseConversationPanelItemsResolvers {
+    /** Raw conversation list from the API. */
+    items: ConversationListItemDto[];
+    /** Available deployments used to resolve icons and tooltips. */
+    deployments: DeploymentItemDto[];
+    /** Whether the deployments list is still loading (drives `isIconLoading`). */
+    isDeploymentsLoading: boolean;
+}
+/**
+ * Maps raw `ConversationListItemDto[]` to panel-compatible conversation items.
+ *
+ * Returns a memoised array whose shape is compatible with the conversation
+ * panel's item contract. All app-specific concerns (icon URL resolution,
+ * route generation, id normalisation) are injected via resolver callbacks.
+ *
+ * While every input except `items` is unchanged, a DTO that is referentially
+ * the same as in the previous render maps to the same item object, so a list
+ * change (or a navigation that re-derives the list) re-renders only the rows
+ * whose DTO actually changed.
+ */
+export declare const useConversationPanelItems: ({ items, deployments, isDeploymentsLoading, toPanelConversationId, resolveIconUrl, resolveIconTooltip, resolveHref, resolveTaskPresentation, }: UseConversationPanelItemsParams) => {
+    leadingIcon?: ReactNode;
+    isUnread?: boolean | undefined;
+    id: string;
+    title: string;
+    isPinned: boolean;
+    iconUrl: string | undefined;
+    iconTooltip: string | undefined;
+    isIconLoading: boolean;
+    source: FilterTab;
+    href: string;
+}[];
+//# sourceMappingURL=useConversationPanelItems.d.ts.map

package/conversation/useConversationPanelItems/useConversationPanelItems.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useConversationPanelItems.d.ts","sourceRoot":"","sources":["../../../src/conversation/useConversationPanelItems/useConversationPanelItems.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,uBAAuB,EACvB,iBAAiB,EAClB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AACtD,OAAO,EAA8B,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAOnE;;GAEG;AACH,eAAO,MAAM,qBAAqB,GAChC,MAAM,IAAI,CAAC,uBAAuB,EAAE,cAAc,GAAG,iBAAiB,CAAC,KACtE,SAIF,CAAC;AAEF,oFAAoF;AACpF,MAAM,WAAW,kCAAkC;IACjD,0EAA0E;IAC1E,qBAAqB,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,CAAC;IAC9C,sFAAsF;IACtF,cAAc,EAAE,CACd,UAAU,EAAE,iBAAiB,GAAG,SAAS,KACtC,MAAM,GAAG,SAAS,CAAC;IACxB;;;OAGG;IACH,kBAAkB,EAAE,CAClB,UAAU,EAAE,iBAAiB,GAAG,SAAS,EACzC,QAAQ,EAAE,MAAM,KACb,MAAM,GAAG,SAAS,CAAC;IACxB,6EAA6E;IAC7E,WAAW,EAAE,CAAC,mBAAmB,EAAE,MAAM,KAAK,MAAM,CAAC;IACrD;;;;OAIG;IACH,uBAAuB,CAAC,EAAE,CACxB,IAAI,EAAE,uBAAuB,KAC1B;QAAE,WAAW,CAAC,EAAE,SAAS,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAA;KAAE,GAAG,SAAS,CAAC;CACjE;AAED,0DAA0D;AAC1D,MAAM,WAAW,+BAAgC,SAAQ,kCAAkC;IACzF,0CAA0C;IAC1C,KAAK,EAAE,uBAAuB,EAAE,CAAC;IACjC,gEAAgE;IAChE,WAAW,EAAE,iBAAiB,EAAE,CAAC;IACjC,8EAA8E;IAC9E,oBAAoB,EAAE,OAAO,CAAC;CAC/B;AA+BD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,yBAAyB,GAAI,gJASvC,+BAA+B;;;;;;;;;;;GA6EjC,CAAC"}

package/conversation/useConversationScroll/useConversationScroll.d.ts

@@ -0,0 +1,46 @@
+import { RefObject } from 'react';
+/** Parameters for {@link useConversationScroll}. `T` is never read — only `messages.length` is used to detect growth/reset. */
+export interface UseConversationScrollParams<T> {
+    /** Messages currently rendered in the list. */
+    messages: T[];
+    /** Whether an assistant response is currently streaming in. */
+    isAssistantTyping: boolean;
+    /** Identifier of the conversation being displayed. */
+    conversationId: string;
+}
+/** Return value of {@link useConversationScroll}. */
+export interface UseConversationScrollResult {
+    /** Attach to the scrollable message-list element. */
+    containerRef: RefObject<HTMLDivElement | null>;
+    /** Attach to the element wrapping all rendered messages (used to detect content growth). */
+    contentRef: RefObject<HTMLDivElement | null>;
+    /**
+     * Attach to a spacer element, a sibling rendered right after `contentRef`
+     * inside `containerRef`. Its height is set imperatively, not via React
+     * state. Render it with `shrink-0` and an initial `style={{ height: 0 }}`.
+     */
+    spacerRef: RefObject<HTMLDivElement | null>;
+    /** Callback ref to register/unregister a rendered message's DOM node by index. */
+    setMessageRef: (index: number, el: HTMLDivElement | null) => void;
+    /** Whether the scroll-to-bottom button should be shown. */
+    isScrollButtonVisible: boolean;
+    /** Smoothly scrolls to the current bottom of the actual message content. */
+    scrollToBottom: () => void;
+    /**
+     * Arms the message at `index` to be scrolled near the top of the viewport
+     * on the next render — call right before triggering a send, regenerate,
+     * or edit-and-resubmit so the resulting message anchors near the top.
+     */
+    armAnchor: (index: number) => void;
+}
+/**
+ * Owns chat-list scrolling: anchors a new turn near the viewport top, keeps
+ * the position stable while the response streams, and reports whether the
+ * scroll-to-bottom button should be shown.
+ *
+ * The temporary spacer is technical scroll room, not user-visible content:
+ * it is sized to the minimum required to make the anchor reachable and manual
+ * scrolling is clamped before the user can move past the real message content.
+ */
+export declare const useConversationScroll: <T>({ messages, isAssistantTyping, conversationId, }: UseConversationScrollParams<T>) => UseConversationScrollResult;
+//# sourceMappingURL=useConversationScroll.d.ts.map

package/conversation/useConversationScroll/useConversationScroll.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useConversationScroll.d.ts","sourceRoot":"","sources":["../../../src/conversation/useConversationScroll/useConversationScroll.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAMf,+HAA+H;AAC/H,MAAM,WAAW,2BAA2B,CAAC,CAAC;IAC5C,+CAA+C;IAC/C,QAAQ,EAAE,CAAC,EAAE,CAAC;IACd,+DAA+D;IAC/D,iBAAiB,EAAE,OAAO,CAAC;IAC3B,sDAAsD;IACtD,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,qDAAqD;AACrD,MAAM,WAAW,2BAA2B;IAC1C,qDAAqD;IACrD,YAAY,EAAE,SAAS,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IAC/C,4FAA4F;IAC5F,UAAU,EAAE,SAAS,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IAC7C;;;;OAIG;IACH,SAAS,EAAE,SAAS,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IAC5C,kFAAkF;IAClF,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,cAAc,GAAG,IAAI,KAAK,IAAI,CAAC;IAClE,2DAA2D;IAC3D,qBAAqB,EAAE,OAAO,CAAC;IAC/B,4EAA4E;IAC5E,cAAc,EAAE,MAAM,IAAI,CAAC;IAC3B;;;;OAIG;IACH,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACpC;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,GAAI,CAAC,EAAE,kDAItC,2BAA2B,CAAC,CAAC,CAAC,KAAG,2BAwTnC,CAAC"}

package/conversation/useConversationStream/apply-chunk.d.ts

@@ -0,0 +1,35 @@
+import { Message, Stage, StreamChunk } from '@epam/ai-dial-chat-shared';
+/**
+ * Merges incoming stage deltas into an existing stage list, keyed by `index`.
+ *
+ * Partial `name` and `content` strings are concatenated across chunks;
+ * attachments are merged by their own `index` (concatenating partial `title`
+ * and `data`); every other field on the incoming delta overwrites the
+ * accumulated one. A brand-new stage whose first chunk carries `name: null`
+ * is normalized to `''`.
+ *
+ * Exported for hosts that keep a flattened `Stage[]` on the message instead
+ * of `Message.custom_content.stages` and therefore cannot reuse
+ * {@link applyChunkToMessages}. Prefer `useConversationStream` when the host
+ * can delegate the whole stream loop.
+ */
+export declare const mergeStages: (existing: Stage[], incoming: Stage[]) => Stage[];
+/**
+ * Applies a single SSE stream chunk to the message list.
+ *
+ *
+ * Attachments are accumulated: each chunk's attachments are appended to the
+ * existing array rather than replacing it.
+ *
+ * Annotations are merged by `index`: partial `body.title` and `body.quote`
+ * strings are concatenated across chunks, matching the same delta-merge
+ * semantics used for stages.
+ *
+ * `state` is overwritten (not merged) by each chunk that carries one,
+ * matching the DIAL stateful-app contract.
+ *
+ * @returns Updated message array, or `null` when the chunk carries no
+ *   actionable data (empty content, no form_schema, and no attachments).
+ */
+export declare const applyChunkToMessages: (messages: Message[], messageIndex: number, chunk: StreamChunk) => Message[] | null;
+//# sourceMappingURL=apply-chunk.d.ts.map

package/conversation/useConversationStream/apply-chunk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-chunk.d.ts","sourceRoot":"","sources":["../../../src/conversation/useConversationStream/apply-chunk.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAGV,OAAO,EAEP,KAAK,EACL,WAAW,EACZ,MAAM,2BAA2B,CAAC;AAqFnC;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,WAAW,GAAI,UAAU,KAAK,EAAE,EAAE,UAAU,KAAK,EAAE,KAAG,KAAK,EA+BvE,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,oBAAoB,GAC/B,UAAU,OAAO,EAAE,EACnB,cAAc,MAAM,EACpB,OAAO,WAAW,KACjB,OAAO,EAAE,GAAG,IAqEd,CAAC"}

package/conversation/useConversationStream/buffered-generation.d.ts

@@ -0,0 +1,15 @@
+import { Conversation, Message } from '@epam/ai-dial-chat-shared';
+/**
+ * A generation's assistant message accumulated while its conversation isn't
+ * the displayed one (a background stream, or a resume attach), keyed by
+ * conversation path so it can be restored once that conversation is shown
+ * again.
+ */
+export interface BufferedGeneration {
+    generationId: string;
+    messageIndex: number;
+    message: Message;
+}
+/** Restores `buffered.message` into `conversation` at `buffered.messageIndex`, merging into whatever message is already there. */
+export declare const restoreBufferedMessage: (conversation: Conversation, buffered: BufferedGeneration) => Conversation;
+//# sourceMappingURL=buffered-generation.d.ts.map

package/conversation/useConversationStream/buffered-generation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buffered-generation.d.ts","sourceRoot":"","sources":["../../../src/conversation/useConversationStream/buffered-generation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AAEvE;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,OAAO,CAAC;CAClB;AAgBD,kIAAkI;AAClI,eAAO,MAAM,sBAAsB,GACjC,cAAc,YAAY,EAC1B,UAAU,kBAAkB,KAC3B,YAeF,CAAC"}

package/conversation/useConversationStream/conversation-path.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Strips the leading bucket segment from a conversation id and decodes any
+ * already-percent-encoded remainder back to raw, so callers that re-encode
+ * the result once (e.g. an API client) don't double-encode it on the wire.
+ */
+export declare const getConversationPath: (conversationId: string) => string;
+//# sourceMappingURL=conversation-path.d.ts.map

package/conversation/useConversationStream/conversation-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation-path.d.ts","sourceRoot":"","sources":["../../../src/conversation/useConversationStream/conversation-path.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAAI,gBAAgB,MAAM,KAAG,MAO5D,CAAC"}

package/conversation/useConversationStream/frame-scheduler.d.ts

@@ -0,0 +1,14 @@
+/** Coalesces work per key into at most one run per animation frame. */
+export interface FrameScheduler {
+    /** Runs `task` on the next frame, replacing any task still pending for `key`. */
+    schedule: (key: string, task: () => void) => void;
+    /** Runs the task pending for `key` now, if any; it will not run again. */
+    flush: (key: string) => void;
+    /** Drops the task pending for `key` without running it. */
+    cancel: (key: string) => void;
+    /** Drops every pending task without running it. */
+    cancelAll: () => void;
+}
+/** Returns a scheduler that runs the latest task per key once per animation frame. */
+export declare const createFrameScheduler: () => FrameScheduler;
+//# sourceMappingURL=frame-scheduler.d.ts.map

package/conversation/useConversationStream/frame-scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame-scheduler.d.ts","sourceRoot":"","sources":["../../../src/conversation/useConversationStream/frame-scheduler.ts"],"names":[],"mappings":"AAGA,uEAAuE;AACvE,MAAM,WAAW,cAAc;IAC7B,iFAAiF;IACjF,QAAQ,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;IAClD,0EAA0E;IAC1E,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,2DAA2D;IAC3D,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9B,mDAAmD;IACnD,SAAS,EAAE,MAAM,IAAI,CAAC;CACvB;AAgBD,sFAAsF;AACtF,eAAO,MAAM,oBAAoB,QAAO,cAmCvC,CAAC"}

package/conversation/useConversationStream/generation-resume.d.ts

@@ -0,0 +1,85 @@
+import { Conversation, Message } from '@epam/ai-dial-chat-shared';
+import { Dispatch, MutableRefObject, SetStateAction } from 'react';
+import { BufferedGeneration } from './buffered-generation';
+import { FrameScheduler } from './frame-scheduler';
+import { ConversationStreamTransport } from './useConversationStream';
+/**
+ * True when the assistant message carries anything the backend's finalize save
+ * would have written. Text alone is not enough to tell a finished response from
+ * the start-state placeholder: an image-generation answer settles with an empty
+ * `content` and only `custom_content.attachments`, and a stage-only or
+ * form-only answer is just as text-free.
+ */
+export declare const hasGeneratedPayload: (message: Message) => boolean;
+/**
+ * Index of the conversation's message that a background generation is still
+ * producing (`backgroundGeneration.status` is `pending`), or -1. It can sit
+ * anywhere, e.g. before a model-changed status message.
+ */
+export declare const findPendingBackgroundMessageIndex: (conversation: Conversation) => number;
+/**
+ * True when the conversation has a pending background message, or its last
+ * message is an unresolved assistant placeholder: the backend only persists a
+ * conversation at generation start (empty placeholder) and at generation end
+ * (final content, or a partial flagged `streamErrorMessage`/`wasStoppedByUser`).
+ * This can mean generation is still active elsewhere, or that its terminal save
+ * failed.
+ */
+export declare const isAwaitingGenerationResume: (conversation: Conversation) => boolean;
+export declare const RECOVERY_REFETCH_DELAYS_MS: number[];
+/**
+ * Returns the conversation from `load`, retrying rejected attempts — and
+ * results `isPending` flags as not yet settled — on the
+ * {@link RECOVERY_REFETCH_DELAYS_MS} schedule; `null` once every attempt has
+ * failed or stayed pending, or `shouldStop` turns true between attempts.
+ */
+export declare const fetchConversationForRecovery: (load: () => Promise<Conversation>, shouldStop: () => boolean, isPending?: (conversation: Conversation) => boolean) => Promise<Conversation | null>;
+/** Internal options a resume started by the stream hook itself passes; the public API passes none. */
+export interface ResumeGenerationOptions {
+    /** Initial buffered message, used instead of the stored placeholder — the live partial answer a dropped stream had already shown. */
+    seedMessage?: Message;
+    /** Called once when the resume has resolved or lost ownership of the path to a newer generation. */
+    onSettled?: () => void;
+    /** Resumes even though the path is already in `resumingPathsRef`, for a caller that reserved it itself. */
+    skipDedupe?: boolean;
+}
+/** Host-owned state {@link createResumeIfAwaitingGeneration} reads/writes through. */
+export interface ResumeIfAwaitingGenerationDeps {
+    transport: ConversationStreamTransport;
+    setConversation: Dispatch<SetStateAction<Conversation | null>>;
+    conversationRef: MutableRefObject<Conversation | null>;
+    resumingPathsRef: MutableRefObject<Set<string>>;
+    bufferedGenerationsRef: MutableRefObject<Map<string, BufferedGeneration>>;
+    addStreamingPath: (path: string) => void;
+    removeStreamingPath: (path: string) => void;
+    isPathDisplayed: (path: string) => boolean;
+    generationPersistenceErrorMessage?: string;
+    /** Records a terminal read failure and its guarded read-only retry. */
+    onReloadError?: (path: string, retry: () => Promise<void>, isCurrent: () => boolean) => void;
+    /** Clears a previous read failure after reconciliation. */
+    onReloadSuccess?: (path: string) => void;
+    /** When set, replayed chunks are published at most once per frame through it. */
+    frameScheduler?: FrameScheduler;
+    /**
+     * Generation ids the user stopped. A resumed background generation in this set
+     * ignores further replayed chunks (DIAL Core does not always honour the cancel), and
+     * its id is removed when the resume settles.
+     */
+    stoppedGenerationIdsRef?: MutableRefObject<Set<string>>;
+}
+/**
+ * Builds `resumeIfAwaitingGeneration`: a hard refresh mid-generation loads a
+ * conversation whose last message is the backend's empty start-state
+ * placeholder (no incremental save exists to show partial content). Rather
+ * than leaving that static and forever empty, this marks the path as
+ * streaming — for free, reusing the same typing indicator and any
+ * `isStreaming` guards a composed handlers hook already applies — and
+ * attaches to the backend's live replay of the in-flight generation
+ * (`transport.attachToGeneration`), showing the assistant message populate
+ * progressively. It falls back to watching the conversation's generic
+ * resource-update channel (`transport.watchConversation`) until the
+ * backend's finalize save resolves the placeholder whenever attach is
+ * unavailable or ends without a terminal event.
+ */
+export declare const createResumeIfAwaitingGeneration: ({ transport, setConversation, conversationRef, resumingPathsRef, bufferedGenerationsRef, addStreamingPath, removeStreamingPath, isPathDisplayed, generationPersistenceErrorMessage, frameScheduler, stoppedGenerationIdsRef, onReloadError, onReloadSuccess, }: ResumeIfAwaitingGenerationDeps) => (currentConversationId: string, conversation: Conversation, options?: ResumeGenerationOptions) => void;
+//# sourceMappingURL=generation-resume.d.ts.map

package/conversation/useConversationStream/generation-resume.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generation-resume.d.ts","sourceRoot":"","sources":["../../../src/conversation/useConversationStream/generation-resume.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,YAAY,EAEjB,KAAK,OAAO,EAEb,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,QAAQ,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,OAAO,CAAC;AAOxE,OAAO,EACL,KAAK,kBAAkB,EAExB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,yBAAyB,CAAC;AAE3E;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,GAAI,SAAS,OAAO,KAAG,OAWtD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,iCAAiC,GAC5C,cAAc,YAAY,KACzB,MAKA,CAAC;AAEJ;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,GACrC,cAAc,YAAY,KACzB,OAUF,CAAC;AA6BF,eAAO,MAAM,0BAA0B,UAAkC,CAAC;AAe1E;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,GACvC,MAAM,MAAM,OAAO,CAAC,YAAY,CAAC,EACjC,YAAY,MAAM,OAAO,EACzB,YAAY,CAAC,YAAY,EAAE,YAAY,KAAK,OAAO,KAClD,OAAO,CAAC,YAAY,GAAG,IAAI,CAiB7B,CAAC;AAgEF,sGAAsG;AACtG,MAAM,WAAW,uBAAuB;IACtC,qIAAqI;IACrI,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,oGAAoG;IACpG,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB,2GAA2G;IAC3G,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,sFAAsF;AACtF,MAAM,WAAW,8BAA8B;IAC7C,SAAS,EAAE,2BAA2B,CAAC;IACvC,eAAe,EAAE,QAAQ,CAAC,cAAc,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC,CAAC;IAC/D,eAAe,EAAE,gBAAgB,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;IACvD,gBAAgB,EAAE,gBAAgB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;IAChD,sBAAsB,EAAE,gBAAgB,CAAC,GAAG,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC;IAC1E,gBAAgB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC,mBAAmB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5C,eAAe,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IAC3C,iCAAiC,CAAC,EAAE,MAAM,CAAC;IAC3C,uEAAuE;IACvE,aAAa,CAAC,EAAE,CACd,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,EAC1B,SAAS,EAAE,MAAM,OAAO,KACrB,IAAI,CAAC;IACV,2DAA2D;IAC3D,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC,iFAAiF;IACjF,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC;;;;OAIG;IACH,uBAAuB,CAAC,EAAE,gBAAgB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;CACzD;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,gCAAgC,GAAI,gQAc9C,8BAA8B,MAE7B,uBAAuB,MAAM,EAC7B,cAAc,YAAY,EAC1B,UAAS,uBAA4B,KACpC,IA8QJ,CAAC"}

package/conversation/useConversationStream/useConversationStream.d.ts

@@ -0,0 +1,145 @@
+import { SendCompletionDtoModeEnum } from '@epam/ai-dial-chat-api-client';
+import { Conversation, MessageCustomContent, StreamChunk } from '@epam/ai-dial-chat-shared';
+import { Dispatch, MutableRefObject, SetStateAction } from 'react';
+/** Options accepted by {@link ConversationStreamTransport.streamCompletion}. */
+export interface StreamCompletionOptions {
+    onChunk: (chunk: StreamChunk) => void;
+    onComplete: () => void | Promise<void>;
+    onError: (error: Error) => void;
+    signal: AbortSignal;
+}
+/**
+ * Host-owned transport for the DIAL Core completion protocol. Implemented at
+ * the app edge — never hardcodes an `/api` path, CSRF handling, or a
+ * `server-api` import; the library only depends on this interface's shape.
+ */
+export interface ConversationStreamTransport {
+    /** Starts a completion; delivers chunks/completion/error through `options`, aborted via `options.signal`. */
+    streamCompletion(path: string, message: string | undefined, model: string, options: StreamCompletionOptions, customContent?: MessageCustomContent, generationId?: string, mode?: SendCompletionDtoModeEnum, messageIndex?: number, clientChannelId?: string): void;
+    /**
+     * Requests the backend stop an active generation. `content` is the answer text shown
+     * so far; the backend saves it for a generation whose text it does not hold.
+     */
+    stopCompletion(params: {
+        generationId: string;
+        path: string;
+        content?: string;
+    }): Promise<void>;
+    /** Opens a stream of resource-update events for `path`, until aborted via `signal`. */
+    watchConversation(path: string, signal: AbortSignal): Promise<ReadableStream<Uint8Array>>;
+    /**
+     * Attaches to an active generation's live replay: a `snapshot` event
+     * carrying the assistant message as assembled so far, then a `chunk` event
+     * per subsequent delta, then exactly one terminal event (`done`/`error`/
+     * `stopped`), until aborted via `signal`. Rejects when no active
+     * generation exists for `path` — including one that already finished —
+     * so the caller can fall back to `watchConversation`.
+     */
+    attachToGeneration(path: string, signal: AbortSignal): Promise<ReadableStream<Uint8Array>>;
+    /** Reloads the persisted conversation by its full (bucket-qualified) id. */
+    getConversation(conversationId: string, signal?: AbortSignal): Promise<Conversation>;
+    /**
+     * Saves `conversation` at the bucket-stripped `path`, resolving with the saved
+     * conversation. Used only for the single recovery save after the backend's
+     * terminal save was rejected with `401`; without it that failure shows the
+     * persistence warning immediately.
+     */
+    saveConversation?(path: string, conversation: Conversation): Promise<Conversation>;
+}
+/** Host-owned generation lifecycle, backing cross-navigation `AbortController` ownership. */
+export interface ConversationGenerationLifecycle {
+    /** Starts (or replaces) tracking for a generation on `path`, returning its `AbortController`. */
+    startGeneration: (path: string, generationId: string) => AbortController;
+    /** Marks the generation identified by `path`/`generationId` complete, if it is still the active one. */
+    completeGeneration: (path: string, generationId: string) => void;
+}
+/** Optional host-owned client-channel connection, used to nudge tool-signin delivery. */
+export interface ConversationStreamChannel {
+    channelId: string | null;
+    ensureConnected: () => void;
+    /** Resolves with a channel id, waiting for an in-flight subscribe if one isn't established yet, so a completion sent immediately after mount can still carry it. */
+    waitForChannel: (timeoutMs?: number) => Promise<string | null>;
+    /** Notifies the host that a generation just ended (completed or errored), so it can consider disconnecting an idle channel. */
+    notifyGenerationSettled?: () => void;
+}
+/** Optional host-owned overlay generation-lifecycle notifications. Each method is independently optional. */
+export interface ConversationStreamOverlayNotifier {
+    notifyGenerationStart?: () => void;
+    notifyGenerationEnd?: () => void;
+    notifyStopGenerating?: () => void;
+}
+/** Shared mutable channel through which the displayed conversation's state is read/written. */
+export interface ConversationStateAccessor {
+    setConversation: Dispatch<SetStateAction<Conversation | null>>;
+    conversationRef: MutableRefObject<Conversation | null>;
+}
+/** Parameters for {@link useConversationStream}. */
+export interface UseConversationStreamParams {
+    conversationId: string | undefined;
+    state: ConversationStateAccessor;
+    transport: ConversationStreamTransport;
+    generation: ConversationGenerationLifecycle;
+    channel?: ConversationStreamChannel;
+    overlay?: ConversationStreamOverlayNotifier;
+    onStopError?: (error: Error) => void;
+    /**
+     * Message shown on the message bubble when the backend rejects a completion
+     * because this conversation is already generating — the case a second
+     * browser tab of the same session hits. Defaults to
+     * {@link DEFAULT_GENERATION_CONFLICT_MESSAGE}.
+     */
+    generationConflictMessage?: string;
+    /** Host-translated warning shown when the received answer could not be saved. */
+    generationPersistenceErrorMessage?: string;
+    /**
+     * Receives the original error of every failed stream. The hook shows only
+     * host-supplied or upstream-supplied text on the message bubble and hides
+     * transport detail (e.g. `Failed to fetch`), so this is where the host can
+     * still log or report the raw error.
+     */
+    onStreamError?: (error: Error) => void;
+    /**
+     * Coalesces the displayed chunk updates into one `setConversation` per
+     * animation frame. Chunks still reach the per-path buffer immediately, and
+     * any pending update is flushed before completion, error, stop, or a
+     * superseding generation. Defaults to `false` (one update per chunk).
+     */
+    batchChunksPerFrame?: boolean;
+}
+/** Per-start options of {@link UseConversationStreamResult.startStream}. */
+export interface StartStreamOptions {
+    /**
+     * Treats a `GenerationConflictError` as "this turn is already being
+     * generated" — e.g. a page reloaded before that generation saved its start
+     * state — and joins the running generation instead of showing the conflict
+     * message, which remains the fallback. Only for a start that sends no new
+     * user text; a send the user typed must keep reporting the conflict.
+     */
+    resumeOnConflict?: boolean;
+}
+/** Return value of {@link useConversationStream}. */
+export interface UseConversationStreamResult {
+    startStream: (conversationId: string, userContent: string, messageIndex: number, model: string, customContent?: MessageCustomContent, generationId?: string, mode?: SendCompletionDtoModeEnum, options?: StartStreamOptions) => void;
+    handleStop: () => void;
+    resumeIfAwaitingGeneration: (currentConversationId: string, conversation: Conversation) => void;
+    /** Restores the accumulated live assistant message when its conversation is loaded again before completion. */
+    restoreBufferedGeneration: (currentConversationId: string, conversation: Conversation) => Conversation;
+    isStreaming: boolean;
+    canStopStreaming: boolean;
+    /** Whether the displayed conversation's terminal read failed. */
+    hasConversationReloadError: boolean;
+    /** Whether a retry of that read is in flight. */
+    isReloadingConversation: boolean;
+    /** Retries the failed read without saving or regenerating the answer. */
+    retryConversationReload: () => Promise<void>;
+}
+/**
+ * Owns completion-streaming state: per-path streaming/stoppable tracking,
+ * stale-chunk rejection, cross-navigation live-message buffering,
+ * reload-after-complete, backend-driven stop, and hard-refresh resume
+ * detection — all driven through the injected
+ * `transport`/`generation`/`channel`/`overlay` capabilities rather than any
+ * app context or `server-api` import.
+ */
+export declare const useConversationStream: ({ conversationId, state: { setConversation, conversationRef }, transport, generation: { startGeneration, completeGeneration }, channel, overlay, onStopError, generationConflictMessage, generationPersistenceErrorMessage, onStreamError, batchChunksPerFrame, }: UseConversationStreamParams) => UseConversationStreamResult;
+//# sourceMappingURL=useConversationStream.d.ts.map

package/conversation/useConversationStream/useConversationStream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useConversationStream.d.ts","sourceRoot":"","sources":["../../../src/conversation/useConversationStream/useConversationStream.ts"],"names":[],"mappings":"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"}