@epam/ai-dial-chat-hooks 1.2.0-dev.6 → 1.2.0-dev.69

package/conversation.d.ts

@@ -15,7 +15,6 @@ import { Message } from '@epam/ai-dial-chat-shared';
 import { MessageCustomContent } from '@epam/ai-dial-chat-shared';
 import { MessageRating } from '@epam/ai-dial-chat-shared';
 import { MutableRefObject } from 'react';
-import { OverlayChatMessage } from '@epam/ai-dial-chat-overlay';
 import { PublishHistoryEntry } from '@epam/ai-dial-publish-panel';
 import { RateApi } from '@epam/ai-dial-chat-api-client';
 import { ReactNode } from 'react';
@@ -24,6 +23,7 @@ import { RequestSkill } from '@epam/ai-dial-chat-shared';
 import { ResponseFormat } from '@epam/ai-dial-chat-shared';
 import { SendCompletionDtoModeEnum } from '@epam/ai-dial-chat-api-client';
 import { SetStateAction } from 'react';
+import { Stage } from '@epam/ai-dial-chat-shared';
 import { StarterOption } from '@epam/ai-dial-chat-shared';
 import { StatusMessage } from '@epam/ai-dial-chat-shared';
 import { StreamChunk } from '@epam/ai-dial-chat-shared';
@@ -58,6 +58,25 @@ export declare interface AnnouncementListItemLink {
     href: string;
 }
 
+/**
+ * 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;
+
 /** State and controls returned by `useAsyncConfirmDialog`. */
 export declare interface AsyncConfirmDialogControls<T> {
     /**
@@ -573,6 +592,29 @@ declare interface LocalModeValues {
     temperature: number;
 }
 
+/**
+ * Returns the normalized stages of a raw stage array or a message-like
+ * payload (reading `custom_content.stages`, falling back to
+ * `customContent.stages`), or `undefined` when there are none.
+ */
+export declare const mapStages: (source: RawStage[] | RawStageSource | null | undefined) => Stage[] | undefined;
+
+/**
+ * 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[];
+
 /** True when `message` is an assistant message carrying at least one stage. */
 export declare const messageHasStages: (message: Message) => boolean;
 
@@ -606,6 +648,63 @@ export declare interface QuickAppConversationStartersSettings {
     isChatMessageInputDisabled: boolean;
 }
 
+/**
+ * One stage as it arrives from the REST API or the SSE stream, before
+ * normalization. Structurally satisfied by the generated `StageDto` and by a
+ * raw stream delta, both of which omit `index`/`name`/`status` on the chunk
+ * that opens a stage.
+ */
+export declare interface RawStage {
+    /** Ordering key. Defaults to `0` when absent. */
+    index?: number | null;
+    /** Stage title. `null` on the chunk that opens the stage. */
+    name?: string | null;
+    /** Terminal state as a raw wire string; anything other than `'completed'`/`'failed'` means still running. */
+    status?: string | null;
+    /** Additional stage text. */
+    content?: string | null;
+    /** Short source/category label shown beside the stage name. */
+    tag?: string | null;
+    /** Files produced or referenced by this stage. */
+    attachments?: RawStageAttachment[] | null;
+}
+
+/**
+ * One stage attachment as it arrives from the REST API or the SSE stream,
+ * before normalization: every field is optional and may be `null`.
+ */
+export declare interface RawStageAttachment {
+    /** Zero-based position in the attachment list. */
+    index?: number | null;
+    /** MIME type of the attachment content. */
+    type?: string | null;
+    /** Display name shown in the UI. */
+    title?: string | null;
+    /** Inline base-64 encoded content. */
+    data?: string | null;
+    /** Remote URL pointing to the attachment content. */
+    url?: string | null;
+    /** MIME type of the referenced resource. */
+    reference_type?: string | null;
+    /** URL of an alternate reference resource. */
+    reference_url?: string | null;
+}
+
+/**
+ * Message-like payload carrying stages under either the wire's snake_case
+ * `custom_content` or a host's camelCased `customContent`.
+ */
+export declare interface RawStageSource {
+    /** Custom content as the DIAL wire format spells it. */
+    custom_content?: {
+        stages?: RawStage[] | null;
+    } | null;
+    /** Custom content as a camelCasing host spells it. */
+    customContent?: {
+        stages?: RawStage[] | null;
+    } | null;
+}
+
 /** State of one resource's recipient-count lookup. */
 declare interface RecipientsCountEntry {
     /** Where the lookup for this resource currently stands. */
@@ -662,8 +761,12 @@ export declare interface StreamCompletionOptions {
     signal: AbortSignal;
 }
 
-/** Maps chat messages to the DIAL Chat Overlay protocol's message shape. */
-export declare const toOverlayMessages: (messages: Message[]) => OverlayChatMessage[];
+/**
+ * Returns a renderable `Stage` for one raw payload: `index` defaults to `0`,
+ * `name` to `''`, an unrecognized `status` to `null` (still running), and
+ * `content`/`tag`/`attachments` are passed through when present.
+ */
+export declare const toStage: (stage: RawStage) => Stage;
 
 /** Request shape the host's selected-deployment recognition call accepts. */
 export declare interface TranscribeWithDeploymentParams {
@@ -728,8 +831,8 @@ export declare const useAttachmentUpload: ({ filesApi, bucket, onNetworkError, d
 
 /** Parameters for {@link useAttachmentUpload}. */
 export declare interface UseAttachmentUploadParams {
-    /** Already-configured generated-client instance used to upload the file. */
-    filesApi: Pick<FilesApi, 'uploadFile'>;
+    /** Already-configured client; optional listing skips stored names after a conflict. */
+    filesApi: Pick<FilesApi, 'uploadFile'> & Partial<Pick<FilesApi, 'listFiles'>>;
     /** DIAL Core bucket the file is uploaded into. */
     bucket: string | undefined;
     /** Called with batched filenames after a burst of network-error upload failures. */

package/conversation.js

@@ -6,26 +6,27 @@ import { getModelIdFromConversationId as d } from "./conversation/get-model-id-f
 import { getTimeOfDayGreeting as f } from "./conversation/greeting.js";
 import { createDeploymentChangedMessage as p } from "./conversation/message-factory.js";
 import { getLastDeploymentId as m, getLastUserMessageToolConfiguration as h, isMessageStreaming as g, messageHasStages as _, normalizeResponseFormat as v } from "./conversation/message-utils.js";
-import { toOverlayMessages as y } from "./conversation/overlay-messages.js";
-import { getQuickAppConversationStarters as b } from "./conversation/quick-app-conversation-starters.js";
-import { getStarterPopulateText as x, getStartersFromSchema as S } from "./conversation/starter-option.js";
-import { deriveConversationRowActionState as C } from "./conversation/deriveConversationRowActionState/deriveConversationRowActionState.js";
-import { useActiveConversationSync as w } from "./conversation/useActiveConversationSync/useActiveConversationSync.js";
-import { useAsyncConfirmDialog as T } from "./conversation/useAsyncConfirmDialog/useAsyncConfirmDialog.js";
-import { useConversationLookupMaps as E } from "./conversation/useConversationLookupMaps/useConversationLookupMaps.js";
-import { getConversationSource as D, useConversationPanelItems as O } from "./conversation/useConversationPanelItems/useConversationPanelItems.js";
-import { useImportFilePicker as k } from "./conversation/useImportFilePicker/useImportFilePicker.js";
-import { useAttachmentUpload as A } from "./conversation/useAttachmentUpload/useAttachmentUpload.js";
-import { AudioTranscriptionError as j, AudioTranscriptionErrorReason as M } from "./conversation/useTranscribeAudio/audio-transcription-error.js";
-import { useTranscribeAudio as N } from "./conversation/useTranscribeAudio/useTranscribeAudio.js";
-import { attachmentToDto as P, attachmentsToDtos as F } from "./conversation/useConversationHandlers/attachment-to-dto.js";
-import { createMessagePair as I } from "./conversation/useConversationHandlers/message-factory.js";
-import { hasActiveToolConfig as L, isAnswerIncomplete as R, isMessageChanged as z, shouldRerunGenerationOnEdit as B } from "./conversation/useConversationHandlers/message-utils.js";
-import { getStarterConversationText as V, getStarterDisplayText as H, getStarterSubmitText as U } from "./conversation/useConversationHandlers/starter-option.js";
-import { getConversationPath as W } from "./conversation/useConversationStream/conversation-path.js";
-import { useConversationHandlers as G } from "./conversation/useConversationHandlers/useConversationHandlers.js";
-import { isAwaitingGenerationResume as K } from "./conversation/useConversationStream/generation-resume.js";
-import { useConversationStream as q } from "./conversation/useConversationStream/useConversationStream.js";
-import { useChatSettingsFormConfig as J } from "./useChatSettingsFormConfig/useChatSettingsFormConfig.js";
-import { useToolsMenu as Y } from "./useToolsMenu/useToolsMenu.js";
-export { j as AudioTranscriptionError, M as AudioTranscriptionErrorReason, a as DEFAULT_GENERATION_CONFLICT_MESSAGE, o as GenerationConflictError, P as attachmentToDto, F as attachmentsToDtos, e as buildAnnouncementSignature, s as createChatStreamApi, p as createDeploymentChangedMessage, I as createMessagePair, C as deriveConversationRowActionState, l as formatAppVersion, W as getConversationPath, D as getConversationSource, m as getLastDeploymentId, h as getLastUserMessageToolConfiguration, d as getModelIdFromConversationId, b as getQuickAppConversationStarters, V as getStarterConversationText, H as getStarterDisplayText, x as getStarterPopulateText, U as getStarterSubmitText, S as getStartersFromSchema, f as getTimeOfDayGreeting, L as hasActiveToolConfig, t as hasAnnouncementContent, n as hasStructuredAnnouncement, R as isAnswerIncomplete, K as isAwaitingGenerationResume, z as isMessageChanged, g as isMessageStreaming, _ as messageHasStages, v as normalizeResponseFormat, r as sanitizeAnnouncementHtml, i as sanitizeAnnouncementMessageHtml, u as sanitizeFooterHtml, B as shouldRerunGenerationOnEdit, c as shouldWatchForDisplayNameUpdate, y as toOverlayMessages, w as useActiveConversationSync, T as useAsyncConfirmDialog, A as useAttachmentUpload, J as useChatSettingsFormConfig, G as useConversationHandlers, E as useConversationLookupMaps, O as useConversationPanelItems, q as useConversationStream, k as useImportFilePicker, Y as useToolsMenu, N as useTranscribeAudio };
+import { getQuickAppConversationStarters as y } from "./conversation/quick-app-conversation-starters.js";
+import { mapStages as b, toStage as x } from "./conversation/stage.js";
+import { getStarterPopulateText as S, getStartersFromSchema as C } from "./conversation/starter-option.js";
+import { deriveConversationRowActionState as w } from "./conversation/deriveConversationRowActionState/deriveConversationRowActionState.js";
+import { useActiveConversationSync as T } from "./conversation/useActiveConversationSync/useActiveConversationSync.js";
+import { useAsyncConfirmDialog as E } from "./conversation/useAsyncConfirmDialog/useAsyncConfirmDialog.js";
+import { useConversationLookupMaps as D } from "./conversation/useConversationLookupMaps/useConversationLookupMaps.js";
+import { getConversationSource as O, useConversationPanelItems as k } from "./conversation/useConversationPanelItems/useConversationPanelItems.js";
+import { useImportFilePicker as A } from "./conversation/useImportFilePicker/useImportFilePicker.js";
+import { useAttachmentUpload as j } from "./conversation/useAttachmentUpload/useAttachmentUpload.js";
+import { AudioTranscriptionError as M, AudioTranscriptionErrorReason as N } from "./conversation/useTranscribeAudio/audio-transcription-error.js";
+import { useTranscribeAudio as P } from "./conversation/useTranscribeAudio/useTranscribeAudio.js";
+import { attachmentToDto as F, attachmentsToDtos as I } from "./conversation/useConversationHandlers/attachment-to-dto.js";
+import { createMessagePair as L } from "./conversation/useConversationHandlers/message-factory.js";
+import { hasActiveToolConfig as R, isAnswerIncomplete as z, isMessageChanged as B, shouldRerunGenerationOnEdit as V } from "./conversation/useConversationHandlers/message-utils.js";
+import { getStarterConversationText as H, getStarterDisplayText as U, getStarterSubmitText as W } from "./conversation/useConversationHandlers/starter-option.js";
+import { getConversationPath as G } from "./conversation/useConversationStream/conversation-path.js";
+import { useConversationHandlers as K } from "./conversation/useConversationHandlers/useConversationHandlers.js";
+import { applyChunkToMessages as q, mergeStages as J } from "./conversation/useConversationStream/apply-chunk.js";
+import { isAwaitingGenerationResume as Y } from "./conversation/useConversationStream/generation-resume.js";
+import { useConversationStream as X } from "./conversation/useConversationStream/useConversationStream.js";
+import { useChatSettingsFormConfig as Z } from "./useChatSettingsFormConfig/useChatSettingsFormConfig.js";
+import { useToolsMenu as Q } from "./useToolsMenu/useToolsMenu.js";
+export { M as AudioTranscriptionError, N as AudioTranscriptionErrorReason, a as DEFAULT_GENERATION_CONFLICT_MESSAGE, o as GenerationConflictError, q as applyChunkToMessages, F as attachmentToDto, I as attachmentsToDtos, e as buildAnnouncementSignature, s as createChatStreamApi, p as createDeploymentChangedMessage, L as createMessagePair, w as deriveConversationRowActionState, l as formatAppVersion, G as getConversationPath, O as getConversationSource, m as getLastDeploymentId, h as getLastUserMessageToolConfiguration, d as getModelIdFromConversationId, y as getQuickAppConversationStarters, H as getStarterConversationText, U as getStarterDisplayText, S as getStarterPopulateText, W as getStarterSubmitText, C as getStartersFromSchema, f as getTimeOfDayGreeting, R as hasActiveToolConfig, t as hasAnnouncementContent, n as hasStructuredAnnouncement, z as isAnswerIncomplete, Y as isAwaitingGenerationResume, B as isMessageChanged, g as isMessageStreaming, b as mapStages, J as mergeStages, _ as messageHasStages, v as normalizeResponseFormat, r as sanitizeAnnouncementHtml, i as sanitizeAnnouncementMessageHtml, u as sanitizeFooterHtml, V as shouldRerunGenerationOnEdit, c as shouldWatchForDisplayNameUpdate, x as toStage, T as useActiveConversationSync, E as useAsyncConfirmDialog, j as useAttachmentUpload, Z as useChatSettingsFormConfig, K as useConversationHandlers, D as useConversationLookupMaps, k as useConversationPanelItems, X as useConversationStream, A as useImportFilePicker, Q as useToolsMenu, P as useTranscribeAudio };

package/file-manager-canvas.d.ts

@@ -0,0 +1,398 @@
+import { Annotation } from '@epam/ai-dial-chat-shared';
+import { AnnotationGroup } from '@epam/ai-dial-quotations';
+import { ApplicationVisualizer } from '@epam/ai-dial-chat-shared';
+import { AttachmentResource } from '@epam/ai-dial-chat-shared';
+import { CustomVisualizer } from '@epam/ai-dial-chat-shared';
+import type { CustomVisualizerDataLayout } from '@epam/ai-dial-chat-shared';
+import { DisplayAttachment } from '@epam/ai-dial-chat-shared';
+import type { GroupedAttachmentItem } from '@epam/ai-dial-chat-shared';
+import type { InputHighlightData } from '@epam/pdf-highlighter-kit';
+
+/**
+ * Builds an `OoxmlCanvasContent` for a DOCX/PPTX/XLSX citation annotation,
+ * including highlights for every annotation sharing the clicked one's source
+ * document. Returns `null` when the annotation has no source attachment,
+ * the source is not a format `@silurus/ooxml` renders as DOCX/XLSX/PPTX (a
+ * CSV source returns `null` — citation highlighting targets Office documents
+ * only), or no URL resolves.
+ */
+export declare const annotationToOoxmlCanvasContent: (annotation: Annotation, annotations: Annotation[], resolvers: AttachmentCanvasUrlResolvers) => OoxmlCanvasContent | null;
+
+/**
+ * Builds a `PdfCanvasContent` for a PDF citation annotation, including highlights
+ * for the clicked annotation's document within its citation group.
+ * Returns `null` if the annotation has no PDF source attachment.
+ */
+export declare const annotationToPdfCanvasContent: (annotation: Annotation, groups: AnnotationGroup[], resolvers: AttachmentCanvasUrlResolvers) => PdfCanvasContent | null;
+
+/**
+ * DIAL-file URL resolution injected by the host into every attachment-canvas
+ * content resolver below. Host-owned — encodes the app's own
+ * file-download endpoint.
+ */
+export declare interface AttachmentCanvasUrlResolvers {
+    /** Resolves a DIAL Core file id to a downloadable URL. */
+    resolveDialFileDownloadUrl: (fileId: string) => string | undefined;
+    /** Resolves the best downloadable DIAL-file URL from an attachment's `url` or `referenceUrl`. */
+    resolveDialUrl: (attachment: DisplayAttachment) => string | undefined;
+    /** Resolves a DIAL Core file id to a fetchable metadata URL (used for cache-freshness validation). */
+    resolveDialFileMetadataUrl: (fileId: string) => string | undefined;
+}
+
+/** The type of content the canvas can display. */
+declare enum AttachmentContentType {
+    PlainText = 'plain_text',
+    Image = 'image',
+    Audio = 'audio',
+    Markdown = 'markdown',
+    MarkdownTable = 'markdown_table',
+    Json = 'json',
+    Pdf = 'pdf',
+    Ooxml = 'ooxml',
+    Code = 'code',
+    Html = 'html',
+    Visualizer = 'visualizer',
+    GroupedVisualizer = 'grouped_visualizer',
+    McpApp = 'mcp_app',
+    Unsupported = 'unsupported',
+    Error = 'error',
+}
+
+/** The kind of failure that produced an `ErrorCanvasContent`. */
+declare enum AttachmentErrorType {
+    /** The file failed to load (network error or a non-`403` non-OK response). */
+    LoadFailed = 'load_failed',
+    /** The file request failed with HTTP `403` — the user lacks permission to access it. */
+    Forbidden = 'forbidden',
+}
+
+/** Clears all cached fetch results. Call this when leaving a conversation. */
+export declare const clearAttachmentCache: () => void;
+
+/** Content payload for syntax-highlighted source-code or text file attachments. */
+declare interface CodeCanvasContent {
+    /** Discriminates the content type to select the correct renderer. */
+    type: AttachmentContentType.Code;
+    /** The raw source text to display. */
+    text: string;
+    /** `react-syntax-highlighter` language identifier (e.g. `'typescript'`). `undefined` renders plain monospace. */
+    language?: string;
+}
+
+/** Content payload for attachments whose file failed to load or that the user cannot access. */
+declare interface ErrorCanvasContent {
+    /** Discriminates the content type to select the correct renderer. */
+    type: AttachmentContentType.Error;
+    /** The kind of failure that occurred. */
+    errorType: AttachmentErrorType;
+    /** Remote URL of the file, if known. Ignored for download purposes when `errorType` is `Forbidden`. */
+    url?: string;
+    /** Overrides the default `loadErrorLabel`/`forbiddenErrorLabel` message, for callers whose failed content isn't a generic "file" (e.g. an MCP App). */
+    label?: string;
+}
+
+/** Content payload for an application-scoped grouped visualizer: every attachment a message's visualizer claims, rendered together inside one sandboxed iframe. */
+declare interface GroupedVisualizerCanvasContent {
+    /** Discriminates the content type to select the correct renderer. */
+    type: AttachmentContentType.GroupedVisualizer;
+    /** Iframe `src`, resolved from the matching registry entry's `url`. */
+    url: string;
+    /** One item per claimed attachment, in the message's attachment order. Each `url` is absolute, resolved by the host. */
+    attachments: GroupedAttachmentItem[];
+    /** Presentation layout hints (`themeId`, `width`, `height`, `mobileHeight`) shared by every item. */
+    layout: CustomVisualizerDataLayout;
+    /** postMessage protocol namespace — MUST equal the registry entry's `title`, or the iframe never receives data. */
+    visualizerName: string;
+    /** Milliseconds to wait for a `send()` request's response before rejecting. From the registry entry; does NOT bound the handshake. */
+    requestTimeout?: number;
+}
+
+/** Outcome of building a grouped visualizer payload. */
+export declare interface GroupedVisualizerResolution {
+    /** The grouped payload, or `null` when no claimed attachment resolved to a URL. */
+    content: GroupedVisualizerCanvasContent | null;
+    /** The claimed attachments that reached `content.attachments`, in the input's order. The caller returns the rest to the ordinary attachment tray. */
+    resolved: DisplayAttachment[];
+}
+
+/**
+ * Whether the attachment carries text `resolveAttachmentText` can resolve —
+ * inline data, a DIAL download URL, or a locally-picked file. Mirrors that
+ * function's source list, so a `null` resolver result can be read as "the text
+ * was fetched and rejected" rather than "there was no text to fetch".
+ */
+export declare const hasAttachmentTextSource: (attachment: DisplayAttachment, resolvers: AttachmentCanvasUrlResolvers) => boolean;
+
+/** Content payload for HTML file attachments or external HTML URL sources. */
+declare interface HtmlCanvasContent {
+    /** Discriminates the content type to select the correct renderer. */
+    type: AttachmentContentType.Html;
+    /** Full HTML text rendered via `srcdoc` in a sandboxed iframe. Used for file attachments. */
+    srcdoc?: string;
+    /** External URL rendered via `src` in a sandboxed iframe. Used for external link sources. */
+    url?: string;
+}
+
+/** Content payload for image attachments. */
+declare interface ImageCanvasContent {
+    /** Discriminates the content type to select the correct renderer. */
+    type: AttachmentContentType.Image;
+    /** URL of the image to display (object URL or resolved download URL). */
+    url: string;
+}
+
+/** Content payload for JSON file attachments. */
+declare interface JsonCanvasContent {
+    /** Discriminates the content type to select the correct renderer. */
+    type: AttachmentContentType.Json;
+    /** Already-parsed JSON value. The lib never calls JSON.parse. */
+    value: unknown;
+}
+
+/** Content payload for Markdown file attachments. */
+declare interface MarkdownCanvasContent {
+    /** Discriminates the content type to select the correct renderer. */
+    type: AttachmentContentType.Markdown;
+    /** Raw Markdown string to render. */
+    text: string;
+}
+
+/** Content payload for OOXML document and CSV spreadsheet attachments. */
+declare interface OoxmlCanvasContent {
+    /** Discriminates the content type to select the correct renderer. */
+    type: AttachmentContentType.Ooxml;
+    /** Resolved download URL or object URL for the source file. */
+    url: string;
+    /** The document format used to select and configure the format-specific renderer. */
+    format: OoxmlFileType;
+    /** Cited locations to draw over the document. Omitted, never `[]`, when there is nothing to highlight. */
+    highlights?: OoxmlHighlight[];
+    /** Id of the highlight to navigate to and emphasise. Omitted when the clicked citation resolved to no location. */
+    selectedHighlightId?: string;
+}
+
+/** A 1-based cell address, matching `@silurus/ooxml`'s own `CellAddress`. */
+declare interface OoxmlCellAddress {
+    /** 1-based row number. */
+    row: number;
+    /** 1-based column number. */
+    col: number;
+}
+
+/** A cited character range inside a DOCX story, addressed by story name and source-tree path. */
+declare interface OoxmlDocxHighlightLocation {
+    /** Discriminates this location within `OoxmlHighlightLocation`. */
+    kind: OoxmlHighlightKind.DocxTextRange;
+    /** Name of the DOCX story the range lives in, as an opaque string (only `'body'` is confirmed upstream). */
+    story: string;
+    /** Source-tree element indices identifying the paragraph, matched element-wise. */
+    path: number[];
+    /** Inclusive start character offset within the story's matched text. */
+    start: number;
+    /** Exclusive end character offset, already converted from the wire's inclusive `end`. */
+    endExclusive: number;
+    /** The cited text, compared against the text resolved over `[start, endExclusive)`. */
+    text: string;
+}
+
+/** A complete table row in the DOCX body, matched by cell text. */
+declare interface OoxmlDocxTableRowLocation {
+    /** Location kind. */
+    kind: OoxmlHighlightKind.DocxTableRow;
+    /** Plain text of each cell, in column order. */
+    cells: string[];
+    /** 1-based matching row in document order. */
+    occurrence: number;
+}
+
+/** Supported document formats rendered by the installed `@silurus/ooxml` runtime. */
+declare enum OoxmlFileType {
+    Docx = 'docx',
+    Xlsx = 'xlsx',
+    Pptx = 'pptx',
+    Csv = 'csv',
+}
+
+/** One citation's highlight: the locations it resolved to, under a stable id. */
+declare interface OoxmlHighlight {
+    /** Stable id, used to mark exactly one highlight selected. */
+    id: string;
+    /** One or more locations — a single citation may carry several selectors. */
+    locations: OoxmlHighlightLocation[];
+}
+
+/** Discriminates the Office highlight location descriptors an `OoxmlCanvasContent` can carry. */
+declare enum OoxmlHighlightKind {
+    /** A character range inside a DOCX story, addressed by story name and source-tree path. */
+    DocxTextRange = 'docxTextRange',
+    /** A character range inside a single PPTX shape on one slide. */
+    PptxTextRange = 'pptxTextRange',
+    /** A complete DOCX table row identified by its cell text. */
+    DocxTableRow = 'docxTableRow',
+    /** A complete PPTX table row identified by its cell text on one slide. */
+    PptxTableRow = 'pptxTableRow',
+    /** One cell, or a contiguous same-row cell range, on a named XLSX sheet. */
+    XlsxCellRange = 'xlsxCellRange',
+}
+
+/** A cited location inside an Office document, in document coordinates. */
+declare type OoxmlHighlightLocation =
+| OoxmlDocxHighlightLocation
+| OoxmlPptxHighlightLocation
+| OoxmlDocxTableRowLocation
+| OoxmlPptxTableRowLocation
+| OoxmlXlsxHighlightLocation;
+
+/** A cited character range inside a single shape on one PPTX slide. */
+declare interface OoxmlPptxHighlightLocation {
+    /** Discriminates this location within `OoxmlHighlightLocation`. */
+    kind: OoxmlHighlightKind.PptxTextRange;
+    /** 1-based slide number. */
+    slide: number;
+    /** Shape identifier, compared as a string against the run's own `shapeId`. */
+    shapeId: string;
+    /** Inclusive start character offset within the shape's matched text. */
+    start: number;
+    /** Exclusive end character offset, already converted from the wire's inclusive `end`. */
+    endExclusive: number;
+    /** The cited text, compared against the text resolved over `[start, endExclusive)`. */
+    text: string;
+}
+
+/** A complete table row on one PPTX slide, matched by cell text. */
+declare interface OoxmlPptxTableRowLocation {
+    /** Location kind. */
+    kind: OoxmlHighlightKind.PptxTableRow;
+    /** Plain text of each cell, in column order. */
+    cells: string[];
+    /** 1-based matching row on the specified slide. */
+    occurrence: number;
+    /** 1-based slide number. */
+    slide: number;
+}
+
+/** A cited cell, or contiguous same-row cell range, on a named XLSX sheet. */
+declare interface OoxmlXlsxHighlightLocation {
+    /** Discriminates this location within `OoxmlHighlightLocation`. */
+    kind: OoxmlHighlightKind.XlsxCellRange;
+    /** Sheet name, matched exactly against the workbook's own sheet names. */
+    sheet: string;
+    /** First cell of the range. 1-based, passed to the viewer unconverted. */
+    start: OoxmlCellAddress;
+    /** Last cell of the range, on the same row as `start`. Omitted for a single cell. */
+    end?: OoxmlCellAddress;
+}
+
+/** Content payload for PDF file attachments. */
+declare interface PdfCanvasContent {
+    /** Discriminates the content type to select the correct renderer. */
+    type: AttachmentContentType.Pdf;
+    /** Resolved download URL or object URL for the PDF file. */
+    url: string;
+    /** Highlight regions to render over the PDF pages. */
+    highlights?: InputHighlightData[];
+    /** ID of the highlight to scroll to and select on initial load. */
+    selectedHighlightId?: string;
+    /** 1-based page to navigate to on initial load, independent of highlight geometry. */
+    page?: number;
+}
+
+/** Content payload for plain-text attachments. */
+declare interface PlainTextCanvasContent {
+    /** Discriminates the content type to select the correct renderer. */
+    type: AttachmentContentType.PlainText;
+    /** The raw text to display. */
+    text: string;
+}
+
+/**
+ * Builds a `PdfCanvasContent` for a reference-only attachment whose
+ * `reference_url` points at a PDF file (optionally with a `#page=N`
+ * fragment), so it can be opened in the canvas and scrolled to the
+ * referenced page the same way a regular PDF citation is. Returns `null`
+ * when the attachment's `url` does not target a PDF.
+ */
+export declare const referenceAttachmentToPdfCanvasContent: (attachment: AttachmentResource, resolvers: AttachmentCanvasUrlResolvers) => PdfCanvasContent | null;
+
+/** Resolves a syntax-highlighted code canvas content payload from a DisplayAttachment, or `null` if unavailable. */
+export declare const resolveCodeCanvasContent: (attachment: DisplayAttachment, resolvers: AttachmentCanvasUrlResolvers, language?: string) => Promise<CodeCanvasContent | ErrorCanvasContent | null>;
+
+/**
+ * Builds the grouped payload for an application-scoped visualizer from the
+ * attachments its entry claims, reporting which of them `resolveAbsoluteUrl`
+ * could produce a URL for. Unlike the single-attachment resolver this fetches
+ * nothing: the grouped protocol hands the visualizer URLs and lets it read
+ * them itself, so the URLs must be absolute — a host-relative path would
+ * resolve against the iframe's own origin. Producing one is host knowledge,
+ * which is why it arrives as a callback rather than being built here.
+ */
+export declare const resolveGroupedVisualizerCanvasContent: (attachments: DisplayAttachment[], resolveAbsoluteUrl: (attachment: DisplayAttachment) => string | undefined, entry: ApplicationVisualizer, themeId: string) => GroupedVisualizerResolution;
+
+/**
+ * Resolves an HTML canvas content payload from a DisplayAttachment.
+ * Fetches and inlines the HTML as `srcdoc` when the attachment has a download URL or inline data.
+ * Returns `null` if no source is available, or an `ErrorCanvasContent` on fetch failure.
+ * Rejects `srcdoc` payloads larger than 1 MiB to prevent browser truncation.
+ */
+export declare const resolveHtmlCanvasContent: (attachment: DisplayAttachment, resolvers: AttachmentCanvasUrlResolvers) => Promise<HtmlCanvasContent | ErrorCanvasContent | null>;
+
+/**
+ * Resolves an image canvas content payload from a DisplayAttachment without
+ * fetching — returns a local blob URL or the BFF download URL directly so the
+ * browser cache can be shared with the conversation view's `<img>` element.
+ * A local `File` with bytes takes precedence over the DIAL download URL; a
+ * 0-byte `File` (the file-manager placeholder) does not. Error detection is
+ * delegated to `<img onError>` in the canvas renderer. Returns `null` if no
+ * URL source is available.
+ */
+export declare const resolveImageCanvasContent: (attachment: DisplayAttachment, resolvers: AttachmentCanvasUrlResolvers) => ImageCanvasContent | null;
+
+/**
+ * Resolves a JSON canvas content payload from a DisplayAttachment, or `null` if unavailable.
+ * Falls back to `PlainTextCanvasContent` when the fetched text is not valid JSON.
+ */
+export declare const resolveJsonCanvasContent: (attachment: DisplayAttachment, resolvers: AttachmentCanvasUrlResolvers) => Promise<JsonCanvasContent | PlainTextCanvasContent | ErrorCanvasContent | null>;
+
+/** Resolves a Markdown canvas content payload from a DisplayAttachment, or `null` if unavailable. */
+export declare const resolveMarkdownCanvasContent: (attachment: DisplayAttachment, resolvers: AttachmentCanvasUrlResolvers) => Promise<MarkdownCanvasContent | ErrorCanvasContent | null>;
+
+/** Resolves an OOXML or CSV renderer payload from a DisplayAttachment, or `null` if unavailable. */
+export declare const resolveOoxmlCanvasContent: (attachment: DisplayAttachment, resolvers: AttachmentCanvasUrlResolvers, format: OoxmlFileType) => Promise<OoxmlCanvasContent | ErrorCanvasContent | null>;
+
+/** Resolves a PDF canvas content payload from a DisplayAttachment, or `null` if unavailable. */
+export declare const resolvePdfCanvasContent: (attachment: DisplayAttachment, resolvers: AttachmentCanvasUrlResolvers) => Promise<PdfCanvasContent | ErrorCanvasContent | null>;
+
+/** Resolves a plain-text canvas content payload from a DisplayAttachment, or `null` if unavailable. */
+export declare const resolveTextCanvasContent: (attachment: DisplayAttachment, resolvers: AttachmentCanvasUrlResolvers) => Promise<PlainTextCanvasContent | ErrorCanvasContent | null>;
+
+/**
+ * Fetches the attachment payload and builds a `VisualizerCanvasContent` for the
+ * given registry entry and theme. Returns `null` when the payload cannot be
+ * fetched (caller should fall through to default content-type handling).
+ *
+ * Only JSON payloads are parsed into `data`. Non-JSON payloads (plain text,
+ * CSV, binary, …) resolve with `data: {}` — the visualizer still receives
+ * `mimeType` and `layout`, just no payload body. This is intentional: only
+ * JSON attachment content is forwarded to visualizers in this version.
+ */
+export declare const resolveVisualizerCanvasContent: (attachment: DisplayAttachment, resolvers: AttachmentCanvasUrlResolvers, entry: CustomVisualizer, themeId: string) => Promise<VisualizerCanvasContent | null>;
+
+/** Content payload for a custom-visualizer attachment rendered inside a sandboxed iframe. */
+declare interface VisualizerCanvasContent {
+    /** Discriminates the content type to select the correct renderer. */
+    type: AttachmentContentType.Visualizer;
+    /** Iframe `src`, resolved from the matching registry entry's `url`. */
+    url: string;
+    /** The attachment's own MIME type (not the registry entry's raw, possibly comma-separated, `contentType`). */
+    mimeType: string;
+    /** Opaque attachment payload consumed by the visualizer. */
+    data: unknown;
+    /** Presentation layout hints (`themeId`, `width`, `height`, `mobileHeight`). */
+    layout: CustomVisualizerDataLayout;
+    /** postMessage protocol namespace — MUST equal the registry entry's `title`, or the iframe never receives data. */
+    visualizerName: string;
+    /** Milliseconds to wait for a `send()` request's response before rejecting. From the registry entry; does NOT bound the handshake. */
+    requestTimeout?: number;
+}
+
+export { }

package/file-manager-canvas.js

@@ -0,0 +1,2 @@
+import { annotationToOoxmlCanvasContent as e, annotationToPdfCanvasContent as t, clearAttachmentCache as n, hasAttachmentTextSource as r, referenceAttachmentToPdfCanvasContent as i, resolveCodeCanvasContent as a, resolveGroupedVisualizerCanvasContent as o, resolveHtmlCanvasContent as s, resolveImageCanvasContent as c, resolveJsonCanvasContent as l, resolveMarkdownCanvasContent as u, resolveOoxmlCanvasContent as d, resolvePdfCanvasContent as f, resolveTextCanvasContent as p, resolveVisualizerCanvasContent as m } from "./files/attachment-canvas.js";
+export { e as annotationToOoxmlCanvasContent, t as annotationToPdfCanvasContent, n as clearAttachmentCache, r as hasAttachmentTextSource, i as referenceAttachmentToPdfCanvasContent, a as resolveCodeCanvasContent, o as resolveGroupedVisualizerCanvasContent, s as resolveHtmlCanvasContent, c as resolveImageCanvasContent, l as resolveJsonCanvasContent, u as resolveMarkdownCanvasContent, d as resolveOoxmlCanvasContent, f as resolvePdfCanvasContent, p as resolveTextCanvasContent, m as resolveVisualizerCanvasContent };