@mgamadeus/ddd-agents 0.0.0-stage → 0.1.0-alpha.21

package/dist/types/chat/ConversationScrollToLatestMessageButton/ConversationScrollToLatestMessageButton.d.ts

@@ -0,0 +1,6 @@
+type ConversationScrollToLatestMessageButtonProps = {
+    visible: boolean;
+    onClick: () => void;
+};
+export declare const ConversationScrollToLatestMessageButton: (props: ConversationScrollToLatestMessageButtonProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/types/chat/ConversationSuggestionCard/ConversationSuggestionCard.d.ts

@@ -0,0 +1,7 @@
+import type { ChatAssistantOpening } from "../chat-assistant-identity";
+export interface ConversationSuggestionCardProps {
+    suggestion: ChatAssistantOpening;
+    onClick?: () => void;
+    testId?: string;
+}
+export declare const ConversationSuggestionCard: (props: ConversationSuggestionCardProps) => import("react/jsx-runtime").JSX.Element;

package/dist/types/chat/ConversationView.d.ts

@@ -0,0 +1,216 @@
+import type { ChatAssistantCategory, ChatAssistantIdentity, ChatAssistantOpening } from "./chat-assistant-identity";
+import React from "react";
+import { ConversationErrorType } from "./store/conversation-error-type";
+import type { ChatMessage } from "./chat-message";
+import { ConversationMessageUserTheme } from "./ConversationMessage/ConversationMessageUser/ConversationMessageUser";
+import { ConversationMessageInputHandle } from "./ConversationMessageInput/ConversationMessageInput";
+import type { ConversationAttachmentReference } from "../contract/conversation";
+import { SendMessageHandler } from "./conversation-send-message";
+export interface ConversationViewProps {
+    currentCategory?: ChatAssistantCategory;
+    aiPromptExtension?: ChatAssistantIdentity;
+    suggestions?: ChatAssistantOpening[];
+    messages: ChatMessage[] | null;
+    aiThinking: boolean;
+    error: ConversationErrorType | null;
+    /** Retry-After seconds of a 429 quota rejection — forwarded to the error card for the "try again in …" wording. */
+    rateLimitRetryAfterSeconds?: number | null;
+    /**
+     * Host-bound retry of a FAILED run: re-drives the persisted, unanswered customer message
+     * server-side. Each host binds it to ITS chat slice; forwarded through the body to the message list / error card.
+     */
+    onRetryFailedRun?: () => Promise<void>;
+    /**
+     * True when the host (the agent) is minimized to the compact side-panel; forwarded to ConversationViewBody.
+     */
+    isCompact?: boolean;
+    isDebugMode: boolean;
+    categoriesLoaded: boolean;
+    conversationId?: number;
+    startingNewConversation?: boolean;
+    /**
+     * Show the message list even when no conversation exists yet. Used by a host,
+     * whose fresh (not-yet-created) chat renders its empty message list.
+     */
+    showMessagesWithoutConversation?: boolean;
+    /**
+     * Follow the conversation bottom (scroll-on-mount + resize follow). Default true.
+     * A host disables it for a fresh chat that has no messages yet.
+     */
+    autoScroll?: boolean;
+    /**
+     * Custom node mounted at the tail of the message list instead of the default
+     * (thinking-only) ConversationMessageThinking. Rendered permanently — used by
+     * A host to show the animated agent face, which idles between turns.
+     */
+    thinkingIndicator?: React.ReactNode;
+    /**
+     * Hide the assistant header (icon + name + "Assistant") and the copy button
+     * on assistant messages. Used by a host, which renders bare messages.
+     */
+    hideAssistantMeta?: boolean;
+    /**
+     * Theme for user-message bubbles, passed through to ConversationViewBody →
+     * ConversationMessageList. A host forces "dark"; omitted elsewhere.
+     */
+    userMessageTheme?: ConversationMessageUserTheme;
+    /**
+     * Custom background slot passed through to ConversationViewBody. When provided, the
+     * default chat gradient and AI-Extensions illustrations are suppressed.
+     */
+    background?: React.ReactNode;
+    /**
+     * Opt-in: the host paints the chat's background itself, OUTSIDE this component — passed through to ConversationViewBody,
+     * which keeps the same `customBg` visual mode (transparent pane) `background` would give it, minus
+     * a background node of its own to render (see ConversationViewBody's `backgroundPaintedByHost`).
+     */
+    backgroundPaintedByHost?: boolean;
+    /**
+     * Optional ref forwarded to ConversationViewBody's scrollable content wrapper.
+     * Callers use this to drive scroll-linked effects on top of the chat — e.g.
+     * `useShaderScrollMorph` for the animated background.
+     */
+    scrollRef?: React.Ref<HTMLDivElement>;
+    /** Bump to force a scroll to the newest message — forwarded to ConversationViewBody (see its `scrollToBottomNonce`). */
+    scrollToBottomNonce?: number;
+    /**
+     * Optional external bottom-follow flag, forwarded to ConversationViewBody (see its `followBottomRef`). A host sets it `false`
+     * for a programmatic jump away from the bottom (e.g. the search-result jump) so the follow effects stop yanking the
+     * view back. Left undefined, ConversationViewBody uses its own internal flag.
+     */
+    followBottomRef?: React.MutableRefObject<boolean>;
+    /**
+     * Optional "a programmatic jump is in flight" gate, forwarded to ConversationViewBody (see its `scrollJumpActiveRef`). While
+     * true, ConversationViewBody neither re-enables bottom-follow on scroll nor auto-scrolls to the bottom on resize, so the
+     * host's jump isn't fought by the near-bottom onScroll handler or the resize-follow. Left undefined → no gating.
+     */
+    scrollJumpActiveRef?: React.MutableRefObject<boolean>;
+    /**
+     * Render the chat body alone, without the two-pane ModalSplitView. The split view's
+     * second pane is sized for a full-width modal, so in a narrow side panel (e.g. an
+     * app's editor drawer) it overlays whatever sits beside the panel — and those hosts
+     * don't use widget content-drawers anyway.
+     */
+    disableSplitView?: boolean;
+    /**
+     * Opt-in: show the round divider FAB that toggles the canvas (open → close, closed → re-open the last canvas).
+     * Off by default — ConversationView is shared (generic AI-extensions chat, a host, agent); only hosts that want the
+     * divider toggle (agent) enable it.
+     */
+    enableCanvasToggle?: boolean;
+    /**
+     * Opt-in (agent): render the side-split canvas as a rounded surface card (border-radius + surface background)
+     * so it sits neatly alongside the left side of the host's floating top bar, instead of a flush full-height pane.
+     * Only the card surface is gated here and only while the canvas is a side-split (viewport ≥ 850px); the small
+     * inset that keeps the canvas clear of the pane edge applies to every canvas (see CanvasPane `.root`),
+     * including the narrow full-screen overlay below 850px (where the host hides its top bar, AW-57).
+     */
+    boxCanvasBelowTopBar?: boolean;
+    /**
+     * Opt-in (agent host only): confine the customBg top blur band to the chat pane (position: sticky, sized to
+     * the pane) instead of the whole viewport (position: fixed, the default for a custom `background` in full-screen
+     * mode). Turn on only while a sibling side panel is docked beside the chat (sideCard mode) — otherwise the band
+     * would stay full-viewport-width and bleed over the panel instead of compressing together with the chat. Forwarded
+     * straight through to ConversationViewBody, which owns the actual CSS (see its `.confineTopBlurBandToChatPane`).
+     */
+    confineTopBlurBandToChatPane?: boolean;
+    /**
+     * The setup progress stepper (today's only consumer: the agent chat), forwarded straight through to
+     * ConversationViewBody, which mounts it as a direct child of its positioned pane root — the node brings its own
+     * positioning. It lands INSIDE this view's split, so an open canvas contracts it along with the chat; that pane
+     * boundary is why the host cannot place the strip itself.
+     */
+    progressStepperSlot?: React.ReactNode;
+    /**
+     * Scroll-up older-message pagination (opt-in — forwarded to ConversationViewBody). When `onLoadOlder` is provided, a top
+     * sentinel prefetches the next older page and the viewport is anchored across the prepend. Default off.
+     */
+    hasMoreOlder?: boolean;
+    loadingOlder?: boolean;
+    onLoadOlder?: () => void;
+    /**
+     * Extra action controls rendered inside the chat input's action row, left of the send button —
+     * spread through to ConversationViewBody → ConversationMessageInput (e.g. the agent model picker pill).
+     */
+    inputActionsSlot?: React.ReactNode;
+    /**
+     * Action controls pinned to the LEFT edge of the chat input's action row (`inputActionsSlot`
+     * stays right) — spread through to ConversationViewBody → ConversationMessageInput (e.g. the agent "+" attachments menu).
+     */
+    inputActionsSlotStart?: React.ReactNode;
+    /**
+     * Host-owned content rendered inside the chat input above its editable text area — attachment
+     * preview cards, validation error boxes. Spread through to ConversationViewBody → ConversationMessageInput's `topSlot`.
+     */
+    inputTopSlot?: React.ReactNode;
+    /**
+     * Hard send gate for the chat input: blocks the send button AND Enter while true, but keeps the
+     * text editable. The host sets it e.g. while attachment uploads run.
+     */
+    inputSendDisabled?: boolean;
+    /**
+     * Host-owned content rendered IN PLACE of the chat input — the closed-conversation bar of a completed
+     * setup conversation (no further input possible). When set, ConversationViewBody renders it instead of ConversationMessageInput.
+     */
+    inputReplacementSlot?: React.ReactNode;
+    /**
+     * Host-owned band right above the chat input, the input overlapping its lower edge — e.g. the running voice chat
+     * with its controls. Not rendered while `inputReplacementSlot` replaces the input.
+     */
+    inputBandSlot?: React.ReactNode;
+    /** The chat input's placeholder; the input's own default otherwise. */
+    inputPlaceholder?: string;
+    /** Forwarded to ConversationMessageInput's `sendReplacementWhenEmpty`. */
+    inputSendReplacementWhenEmpty?: React.ReactNode;
+    /** Forwarded to ConversationMessageInput's `glowUnderlay`. */
+    inputGlowUnderlay?: React.ReactNode;
+    /**
+     * Host-owned layer over the message column, the same size — e.g. the voice chat's focus mode. The message column
+     * stays mounted under it (scroll position and widget state kept); `isContentOverlayShown` switches between them.
+     */
+    contentOverlaySlot?: React.ReactNode;
+    isContentOverlayShown?: boolean;
+    /**
+     * Uploaded media-library images that ride along in `onSendMessage`'s options object (`attachments`) on the next
+     * send. Owned and cleared by the host; ConversationView/ConversationMessageInput only forward them.
+     */
+    outgoingAttachmentImages?: ConversationAttachmentReference[];
+    /**
+     * Imperative handle on the chat input (insertTextIntoInput) so host-owned controls — e.g. the
+     * "+" menu's "Generate image" entry — can put text into it.
+     */
+    conversationMessageInputApiRef?: React.Ref<ConversationMessageInputHandle>;
+    /**
+     * Keep the chat input editable and sendable while `aiThinking` is true (default false — the input locks for the
+     * whole turn); only the first post of a new conversation still locks it, while no conversation id exists yet. Opt
+     * in ONLY for a host whose post call stores the message and returns at once, and whose agent checks for unanswered
+     * messages when its turn ends, so a message sent mid-turn is answered in the next turn. A host whose post call
+     * generates the reply synchronously within the request has no such guard and must leave it off.
+     */
+    allowSendWhileAiThinking?: boolean;
+    /**
+     * Opt-in long-answer reading flow (AW-107), default false — spread through to ConversationViewBody. When enabled:
+     * (1) on send, the question is pinned to the top with room reserved below it; (2) a scroll-to-latest-message
+     * button floats above the input while the bottom is out of view; (3) a fresh static reply's markdown blocks
+     * fade in staggered. AI Extensions stays off; the agent chat opts in.
+     */
+    enablePinQuestionAndRevealAnswer?: boolean;
+    /** Forwarded to ConversationViewBody's `isQuestionPinSuspended`. */
+    isQuestionPinSuspended?: boolean;
+    /**
+     * Id of the ONE user message ConversationMessageList renders as a collapsed task-instruction disclosure instead of an
+     * owner bubble — the machine-composed seed instruction of a SCHEDULE-spawned run (UX overhaul W4 item 19).
+     * Forwarded through ConversationViewBody. Undefined (every host except the agent chat) changes nothing.
+     */
+    taskInstructionMessageId?: number;
+    /**
+     * Host content rendered right after one message of the thread — the agent chat's activity card under the message that
+     * started each turn. Forwarded through ConversationViewBody to ConversationMessageList. Undefined changes nothing.
+     */
+    renderAfterMessage?: (message: ChatMessage) => React.ReactNode;
+    /** Forwarded through ConversationViewBody to ConversationMessageList: a closed conversation renders no widget controls. */
+    isConversationClosed?: boolean;
+    onSuggestionClick: (text: string) => void;
+    onSendMessage: SendMessageHandler;
+}
+export declare const ConversationView: (props: ConversationViewProps) => import("react/jsx-runtime").JSX.Element;

package/dist/types/chat/ConversationViewBody/ConversationViewBody.d.ts

@@ -0,0 +1,214 @@
+import type { ChatAssistantCategory, ChatAssistantIdentity, ChatAssistantOpening } from "../chat-assistant-identity";
+import React from "react";
+import { ConversationMessageInputHandle } from "../ConversationMessageInput/ConversationMessageInput";
+import type { ConversationAttachmentReference } from "../../contract/conversation";
+import { SendMessageHandler } from "../conversation-send-message";
+import { ConversationErrorType } from "../store/conversation-error-type";
+import type { ChatMessage } from "../chat-message";
+import { ConversationMessageUserTheme } from "../ConversationMessage/ConversationMessageUser/ConversationMessageUser";
+export interface ConversationViewProps {
+    currentCategory?: ChatAssistantCategory;
+    aiPromptExtension?: ChatAssistantIdentity;
+    suggestions?: ChatAssistantOpening[];
+    messages: ChatMessage[] | null;
+    aiThinking: boolean;
+    error: ConversationErrorType | null;
+    /** Retry-After seconds of a 429 quota rejection — forwarded to the error card for the "try again in …" wording. */
+    rateLimitRetryAfterSeconds?: number | null;
+    /** Host-bound retry of a FAILED run — forwarded to the message list / error card. */
+    onRetryFailedRun?: () => Promise<void>;
+    isDebugMode: boolean;
+    categoriesLoaded: boolean;
+    conversationId?: number;
+    startingNewConversation?: boolean;
+    /**
+     * Show the message list even when no conversation exists yet. Used by a host,
+     * whose fresh (not-yet-created) chat renders its empty message list.
+     */
+    showMessagesWithoutConversation?: boolean;
+    /**
+     * Follow the conversation bottom (scroll-on-mount + resize follow). Default true.
+     * A host disables it for a fresh chat that has no messages yet, so the view stays
+     * anchored at the top.
+     */
+    autoScroll?: boolean;
+    /**
+     * Custom node mounted at the tail of the message list instead of the default
+     * (thinking-only) ConversationMessageThinking. Rendered permanently — used by
+     * A host to show the animated agent face, which idles between turns.
+     */
+    thinkingIndicator?: React.ReactNode;
+    /**
+     * Custom background slot rendered absolutely behind the chat content. When
+     * provided, the default chat gradient and the AI-Extensions category
+     * illustrations are suppressed so the caller owns the entire background
+     * (e.g. A host's shader). Pair with a parent that supplies a solid base color
+     * if the slot doesn't paint the full canvas itself.
+     */
+    background?: React.ReactNode;
+    /**
+     * Opt-in: the host paints the chat's background itself OUTSIDE this component (e.g. the agent's root shader).
+     * Keeps the `customBg` visual mode (top blur band) that passing `background` would give, but with
+     * no background node here and a transparent pane fill so the host's layer shows through.
+     */
+    backgroundPaintedByHost?: boolean;
+    /**
+     * The setup progress stepper (today's only consumer: the agent chat), mounted as a DIRECT CHILD of this
+     * view's pane root — a `position: relative` box the size of the chat pane — and outside the scroll container,
+     * so it stays put while messages scroll under it. Mounted here rather than in the host's floating top bar for
+     * the same reason the top blur band is (see `.contentWrapper::before`): it has to track the chat content
+     * column, so it follows the pane when a canvas or a side panel contracts it, which a viewport-positioned
+     * overlay cannot — and that pane boundary exists only inside this view's split.
+     *
+     * The node brings its OWN positioning, stacking and query container (see the stepper's `.progressStepperRow`);
+     * this view contributes nothing but the positioned pane root it is mounted in.
+     */
+    progressStepperSlot?: React.ReactNode;
+    /**
+     * Optional external ref to the scrollable content wrapper. Forwarded so
+     * callers can drive scroll-linked effects (e.g. an animated background
+     * that morphs with scroll position) without having to query the DOM.
+     */
+    scrollRef?: React.Ref<HTMLDivElement>;
+    /**
+     * Bump to force a scroll to the newest message (via {@link scrollToLatestMessage}, so it clears any pinned turn and
+     * re-enables bottom-follow). Each distinct value triggers one scroll; the initial `0`/`undefined` is ignored. Used by
+     * the agent to follow the turn a widget/CTA-click signal starts (which posts no visible message of its own).
+     */
+    scrollToBottomNonce?: number;
+    /**
+     * Optional external override of the internal bottom-follow flag. Provide it when the host runs its own programmatic
+     * scroll away from the bottom (e.g. the agent's search-result jump, which pages older messages in and scrolls to
+     * a message far above the bottom): the host sets it `false` for the jump so the resize/message-follow effects stop
+     * re-anchoring to the bottom and yanking the view back mid-jump. Left undefined, ConversationViewBody uses its own ref and
+     * behaves exactly as before. Shared with the AW-107 pin machinery, so both agree on one flag.
+     */
+    followBottomRef?: React.MutableRefObject<boolean>;
+    /**
+     * Optional "a programmatic jump is in flight" gate. Set by the host (the agent's search-result jump) for the duration of a
+     * jump. While true, the near-bottom onScroll handler does NOT re-enable bottom-follow and the resize ResizeObserver
+     * does NOT auto-scroll to the bottom — otherwise, right after the jump the container is still near the bottom, so
+     * onScroll would flip follow back on and the follow-up content-resize would yank the view back down. Left undefined,
+     * nothing is gated. Distinct from `followBottomRef`: that flag alone is clobbered by onScroll; this gate stops it.
+     */
+    scrollJumpActiveRef?: React.MutableRefObject<boolean>;
+    /**
+     * Hide the assistant header (icon + name + "Assistant") and the copy button
+     * on assistant messages. Used by a host, which renders bare messages.
+     */
+    hideAssistantMeta?: boolean;
+    /**
+     * Theme for user-message bubbles, forwarded to ConversationMessageList. A host forces
+     * "dark"; when omitted the list falls back to its legacy light/default logic.
+     */
+    userMessageTheme?: ConversationMessageUserTheme;
+    /**
+     * True when the host (the agent) is minimized to the compact side-panel; forwarded to ConversationViewBody.
+     */
+    isCompact?: boolean;
+    /**
+     * Opt-in (agent host only): confine the customBg top blur band to the chat pane instead of the whole viewport —
+     * active only while a sibling side panel is docked beside the chat, so the band compresses together with it instead
+     * of bleeding across the panel. See `.confineTopBlurBandToChatPane` below.
+     */
+    confineTopBlurBandToChatPane?: boolean;
+    /**
+     * Scroll-up older-message pagination (opt-in — mirrors the admin inspector). When `onLoadOlder` is provided, a top
+     * sentinel + IntersectionObserver (root = the scroll container) prefetches the next older page ~300px before the
+     * top, and the viewport is anchored across the prepend so it doesn't jump. `hasMoreOlder` gates the sentinel;
+     * `loadingOlder` shows a small loading row. Left undefined (the default) → no pagination, behaviour unchanged.
+     */
+    hasMoreOlder?: boolean;
+    loadingOlder?: boolean;
+    onLoadOlder?: () => void;
+    /**
+     * Extra action controls rendered inside the chat input's action row, left of the send button —
+     * forwarded to ConversationMessageInput (e.g. the agent model picker pill).
+     */
+    inputActionsSlot?: React.ReactNode;
+    /**
+     * Action controls pinned to the LEFT edge of the chat input's action row (`inputActionsSlot`
+     * stays right) — forwarded to ConversationMessageInput's `actionsSlotStart` (e.g. the agent "+" attachments menu).
+     */
+    inputActionsSlotStart?: React.ReactNode;
+    /**
+     * Host-owned content rendered inside the chat input above its editable text area — attachment
+     * preview cards, validation error boxes. Forwarded to ConversationMessageInput's `topSlot`.
+     */
+    inputTopSlot?: React.ReactNode;
+    /**
+     * Hard send gate for the chat input: blocks the send button AND Enter while true, but keeps the
+     * text editable. The host sets it e.g. while attachment uploads run.
+     */
+    inputSendDisabled?: boolean;
+    /**
+     * Host-owned content rendered IN PLACE of the chat input — the closed-conversation bar of a completed
+     * setup conversation (no further input possible). When set, the body renders it instead of ConversationMessageInput,
+     * in a wrapper carrying the input's own width, bottom gap and stacking rule — so the node needs no layout of its
+     * own, and the background layer cannot paint over it.
+     */
+    inputReplacementSlot?: React.ReactNode;
+    /**
+     * Host-owned band right above the chat input, the input overlapping its lower edge — e.g. the running voice chat
+     * with its controls. Not rendered while `inputReplacementSlot` replaces the input.
+     */
+    inputBandSlot?: React.ReactNode;
+    /** The chat input's placeholder; the input's own default otherwise. */
+    inputPlaceholder?: string;
+    /** Forwarded to ConversationMessageInput's `sendReplacementWhenEmpty`. */
+    inputSendReplacementWhenEmpty?: React.ReactNode;
+    /** Forwarded to ConversationMessageInput's `glowUnderlay`. */
+    inputGlowUnderlay?: React.ReactNode;
+    /**
+     * Host-owned layer over the message column, the same size — e.g. the voice chat's focus mode. The message column
+     * stays mounted under it (scroll position and widget state kept); `isContentOverlayShown` switches between them.
+     */
+    contentOverlaySlot?: React.ReactNode;
+    isContentOverlayShown?: boolean;
+    /**
+     * Uploaded media-library images that ride along in `onSendMessage`'s options object (`attachments`) on the next
+     * send. Owned and cleared by the host; forwarded to ConversationMessageInput.
+     */
+    outgoingAttachmentImages?: ConversationAttachmentReference[];
+    /**
+     * Imperative handle on the chat input (insertTextIntoInput) so host-owned controls — e.g. the
+     * "+" menu's "Generate image" entry — can put text into it. Forwarded to ConversationMessageInput's `apiRef`.
+     */
+    conversationMessageInputApiRef?: React.Ref<ConversationMessageInputHandle>;
+    /**
+     * Keep the chat input editable and sendable while `aiThinking` is true (default false — the input locks for the
+     * whole turn); only the first post of a new conversation still locks it, while no conversation id exists yet. Opt
+     * in ONLY for a host whose post call stores the message and returns at once, and whose agent checks for unanswered
+     * messages when its turn ends, so a message sent mid-turn is answered in the next turn. A host whose post call
+     * generates the reply synchronously within the request has no such guard and must leave it off.
+     */
+    allowSendWhileAiThinking?: boolean;
+    /**
+     * Opt-in long-answer reading flow (AW-107), default false. When enabled:
+     * (1) on send, the question is pinned to the top with room reserved below it so the reply
+     *     reveals from its beginning instead of chasing the bottom;
+     * (2) a scroll-to-latest-message button floats above the input while the bottom is out of view;
+     * (3) a fresh static reply's markdown blocks fade in staggered (useFreshMessageBlockReveal).
+     * Left off, the chat keeps the classic bottom-follow behavior — AI Extensions stays off;
+     * the agent chat opts in.
+     */
+    enablePinQuestionAndRevealAnswer?: boolean;
+    /** New user messages are not sends (a voice chat saves the owner's spoken sentences): keep bottom-follow, no pin. */
+    isQuestionPinSuspended?: boolean;
+    /**
+     * Id of the ONE user message ConversationMessageList renders as a collapsed task-instruction disclosure instead of an
+     * owner bubble — the machine-composed seed instruction of a SCHEDULE-spawned run (UX overhaul W4 item 19).
+     * Undefined (every host except the agent chat) changes nothing.
+     */
+    taskInstructionMessageId?: number;
+    /**
+     * Host content rendered right after one message of the thread, forwarded to ConversationMessageList (the agent chat's
+     * activity card under the message that started each turn). Undefined changes nothing.
+     */
+    renderAfterMessage?: (message: ChatMessage) => React.ReactNode;
+    /** Forwarded to ConversationMessageList: a closed conversation renders no widget controls. */
+    isConversationClosed?: boolean;
+    onSuggestionClick: (text: string) => void;
+    onSendMessage: SendMessageHandler;
+}
+export declare const ConversationViewBody: (props: ConversationViewProps) => import("react/jsx-runtime").JSX.Element;

package/dist/types/chat/ConversationViewBody/hooks/useIsMessagesBottomOutOfView.d.ts

@@ -0,0 +1,2 @@
+import { RefObject } from "react";
+export declare const useIsMessagesBottomOutOfView: (scrollContainer: HTMLDivElement | null, messagesList: HTMLDivElement | null, messagesBottomRef: RefObject<HTMLDivElement | null>) => boolean;

package/dist/types/chat/ConversationViewBody/hooks/usePinQuestionOnSend.d.ts

@@ -0,0 +1,24 @@
+import { MutableRefObject, RefObject } from "react";
+/**
+ * The pin-question-on-send machinery of the AW-107 long-answer reading flow, extracted out of ConversationViewBody
+ * so the addon lives in its own file (mirrors hooks/useIsMessagesBottomOutOfView.ts). On send, the user's
+ * question is pinned to the top with empty room reserved below it and bottom-follow is suspended for the turn,
+ * so the reply reveals from its beginning instead of chasing the bottom.
+ *
+ * Every method no-ops when `enabled` is false, so the disabled state can never leak a layout write
+ * (padding-bottom) or a scroll call even if a caller forgets a gate.
+ */
+export declare const usePinQuestionOnSend: (options: {
+    enabled: boolean;
+    scrollContainer: HTMLDivElement | null;
+    getMessagesListEl: () => HTMLElement | null;
+    messagesBottomRef: RefObject<HTMLDivElement | null>;
+    /** ConversationViewBody's followBottom ref — pinning suspends bottom-follow for the turn. */
+    followBottomRef: MutableRefObject<boolean>;
+}) => {
+    pinLatestQuestionToTop: (behavior: ScrollBehavior) => boolean;
+    reserveRoomBelowPinnedQuestion: () => void;
+    isQuestionPinnedThisTurn: () => boolean;
+    endPinnedTurn: () => void;
+    userMessageRowCount: () => number;
+};

package/dist/types/chat/assistant-message-has-renderable-markdown.d.ts

@@ -0,0 +1,13 @@
+/**
+ * True when an assistant message's stored content yields markdown that actually renders something.
+ *
+ * Not every ASSISTANT row carries text. An agentic run persists one ASSISTANT/TEXT turn per step, and a step
+ * that only called a tool stores `message: ""` (13 such turns in a 30-message run); a payload whose parts are
+ * all blank text likewise normalizes to "". Such a row would render an empty markdown container that still
+ * consumed a full `$x3` gap in the message list, so ConversationMessageList drops it instead — the per-turn agentic
+ * trace those rows carry is the admin console's job (AgentConversationInspector), not the customer chat's.
+ *
+ * The null/blank short-circuit also keeps normalizeServerMessageToMarkdown's "unrecognized message shape"
+ * console warning from firing on every one of those rows.
+ */
+export declare const assistantMessageHasRenderableMarkdown: (message: unknown) => boolean;

package/dist/types/chat/chat-assistant-identity.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The named assistant a chat can show (the assistant identity the host hands in) — the host application's older
+ * AI-Extensions chat passes a prompt extension here; the agent chat passes none. Only the fields the view reads.
+ */
+export interface ChatAssistantIdentity {
+    id?: number | null;
+    name?: string | null;
+    description?: string | null;
+    /** The name of the assistant's icon in the app's icon set. */
+    iconClass?: string | null;
+}
+/** The group the named assistant belongs to; its alias picks the chat's colour theme. */
+export interface ChatAssistantCategory {
+    alias?: string | null;
+    name?: string | null;
+}
+/** An opening the named assistant suggests on its intro card. */
+export interface ChatAssistantOpening {
+    name?: string | null;
+    description?: string | null;
+    iconClass?: string | null;
+    /** The text the opening sends when picked. */
+    openingText?: string | null;
+}

package/dist/types/chat/chat-message.d.ts

@@ -0,0 +1,11 @@
+import type { AgentsConversationMessage } from "../contract/conversation";
+/**
+ * A message as the chat holds and renders it: a stored message of the conversation contract, or the owner's optimistic
+ * message before the server stored it (no id, no index yet), plus the chat store's `fresh` tag — the message arrived
+ * live, so its one-shot widgets may fire. Every contract field is optional here because the optimistic message carries
+ * only its text and role.
+ */
+export type ChatMessage = Partial<AgentsConversationMessage> & {
+    /** The message arrived live (not on open, not on a scroll-up page); its widgets are `justDelivered`. */
+    fresh?: boolean;
+};

package/dist/types/chat/controller/AgentChatController.d.ts

@@ -0,0 +1,97 @@
+import { type ComponentType, type ReactNode, type RefObject } from "react";
+import type { AgentsConversationClient } from "../../client/AgentsConversationClient";
+import { type ConversationAttachmentReference } from "../../contract/conversation";
+import type { AgentsChatStore } from "../store/create-agents-chat-store";
+import type { ChatScrollTarget } from "./chat-scroll-target";
+import { type ActivityTicker, type ActivityTickerTurn } from "./use-activity-ticker";
+/** What the host's activity components get: the turn's state and the paced lines of the activity ticker. */
+export interface AgentChatActivityProps {
+    /** A turn is in flight (derived from the messages and the run status). */
+    active: boolean;
+    /** The chat shows an error card. */
+    failed: boolean;
+    activityTicker: ActivityTicker;
+    /** The agent works on a task: a turn is in flight or the ticker still shows its lines. */
+    isAgentWorkingOnTask: boolean;
+    /** The key of the agent space the chat is open on. */
+    agentSpaceKey: number;
+}
+/** What the host's activity history under a message gets: the finished turn that message started, if any. */
+export interface AgentChatActivityHistoryProps {
+    turn: ActivityTickerTurn | null;
+}
+/** Where the model of the next send comes from — read at send time (an admin's pick can change between renders). */
+export interface AgentChatSendModelSource {
+    readModelForNextSend: () => string | undefined;
+}
+export interface AgentChatControllerProps {
+    /** The state handle of this chat instance (created and released by the app). */
+    chatStore: AgentsChatStore;
+    /** The conversation client this chat reads and sends through. */
+    client: AgentsConversationClient;
+    /** The key of the agent space new conversations start in. */
+    agentSpaceKey: number;
+    /** When set, load + resume this existing conversation. Absent = empty chat, lazy-starts on first send. */
+    conversationId?: number;
+    onNewConversation?: (conversationId: number) => void;
+    /** The conversation could not be loaded (missing, deleted, not readable): the host drops to the empty chat. */
+    onConversationNotFound?: () => void;
+    /** Switch the active conversation — the ConversationSearchResults widget's open-arrow target. */
+    onOpenConversation?: (conversationId: number, messageId?: number) => void;
+    /** Switch this chat to another conversation of the same agent space in place (a widget linking to related work). */
+    onSwitchConversation?: (conversationId: number) => void;
+    /** Text inserted into the composer once on mount — never sent automatically. */
+    initialComposerPrompt?: string;
+    /** A request to scroll a message into view and flash it; re-applied whenever its `nonce` changes. */
+    scrollTarget?: ChatScrollTarget;
+    /** Each finished turn's activity lines stay in the thread above its answer (rendered by `ActivityHistory`). */
+    keepActivityHistoryAfterAnswer?: boolean;
+    /** The host shows one conversation the owner may not leave: no starting ideas (the agent speaks first). */
+    isPinnedToSingleConversation?: boolean;
+    /** App extension of the widget context: the chat is the app's guided first-run setup. */
+    isOnboardingSetupConversation?: boolean;
+    /** The model of the next send; without it the conversation's own model drives. */
+    sendModelSource?: AgentChatSendModelSource;
+    /** Called after a send that carried attachments, so the host clears them from the composer. */
+    onAttachmentsSent?: () => void;
+    /** The empty state of a new chat: a synthetic first assistant message (client state only), as markdown. */
+    startingIdeasMarkdown?: string;
+    /** While true the chat follows the bottom; a rising edge jumps to the newest message (a voice chat). */
+    followBottom?: boolean;
+    /** The chat's scroll container (the host may own it, e.g. for a scroll-linked background). */
+    chatScrollRef: RefObject<HTMLDivElement | null>;
+    isCompact?: boolean;
+    confineTopBlurBandToChatPane?: boolean;
+    /** Class names of the two wrappers around the conversation view (the host's layout). */
+    chatAreaClassName?: string;
+    chatWrapClassName?: string;
+    /** Slots of the conversation view. */
+    progressStepperSlot?: ReactNode;
+    inputActionsSlot?: ReactNode;
+    inputTopSlot?: ReactNode;
+    inputSendDisabled?: boolean;
+    inputReplacementSlot?: ReactNode;
+    inputBandSlot?: ReactNode;
+    inputPlaceholder?: string;
+    inputSendReplacementWhenEmpty?: ReactNode;
+    inputGlowUnderlay?: ReactNode;
+    isContentOverlayShown?: boolean;
+    isQuestionPinSuspended?: boolean;
+    /** The attachments that ride along on the next send. */
+    outgoingAttachments?: ConversationAttachmentReference[];
+    /** The agent's activity at the tail of the thread (the agent avatar slot). */
+    ThinkingIndicator: ComponentType<AgentChatActivityProps>;
+    /** A layer over the message column (a voice chat's focus mode); shown while `isContentOverlayShown`. */
+    ContentOverlay?: ComponentType<AgentChatActivityProps>;
+    /** The kept activity lines under the message that started a turn (with `keepActivityHistoryAfterAnswer`). */
+    ActivityHistory?: ComponentType<AgentChatActivityHistoryProps>;
+    /** Rendered inside the chat's widget provider (the host's canvas syncs). */
+    children?: ReactNode;
+}
+/**
+ * The agent chat: the controller over the conversation client port and the chat store — open, pages,
+ * live updates, sends, signals, the error card and retry, the opening request, the deep-linked widget, the scroll jump
+ * and the activity — rendering the conversation view with the host's slots. The drive is async: a reply never comes
+ * in the start/post answer, it arrives through the live updates.
+ */
+export declare const AgentChatController: (props: AgentChatControllerProps) => import("react/jsx-runtime").JSX.Element;