@particle-academy/react-fancy 5.70.0 → 5.71.0

package/CHANGELOG.md

@@ -11,6 +11,55 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [5.71.0] - 2026-10-27
+
+### Added
+
+- **`ChatThread` and `ChatMessage`**: a controlled message list for agent and
+  support conversations, built for charlotte-ui's side panel and
+  fancy-support's admin chat and ticket thread. Messages are JSON
+  (`ChatMessageData`: `id`, `role`, `author`, markdown `content`, `createdAt`,
+  `status`, `visibility`, `attachments`, `proposal`, `meta`). Content renders
+  through `ContentRenderer`, always sanitised (there is no `unsafe` prop), and a
+  `streaming` message uses its `streaming` / `"progressive"` mode and is
+  `aria-busy`. The log follows new messages only while the reader is at the
+  bottom; a reader who scrolled up stays put and gets an "N new messages" jump
+  control, and prepended history keeps their place. Only the log's own
+  `scrollTop` is set and focus uses `preventScroll`, so nothing outside the log
+  scrolls. `visibility: "internal"` is labelled and styled, never filtered: the
+  host passes only what the viewer may see. A message with a `proposal` is an
+  approval card (`data-chat-proposal`) with accept / reject callbacks; it never
+  acts on its own, and a returned Promise disables both decisions until it
+  settles. Also: `onLoadEarlier`, day separators, consecutive grouping, a
+  per-message actions slot, a composer slot (for `Composer` / `PromptInput`;
+  no new input), `onActivity` for every interaction, `role="log"` with polite
+  updates, and a `ref` handle with `scrollToLatest` / `scrollToMessage`. New
+  subpath `@particle-academy/react-fancy/chat-thread`. Nothing to do on upgrade.
+
+## [5.70.1] - 2026-10-27
+
+### Fixed
+
+- **An acknowledged send no longer clears a newer draft that happens to read
+  the same** (`Composer`, `PromptInput`, from 5.70.0). When an async `onSubmit`
+  resolved, the draft was cleared if its text and the ids of its pills and
+  attachments still matched what was sent. A newer draft that compared equal was
+  therefore thrown away: an edit typed and then deleted during the send, a host
+  `setDraft` that restored the same draft, or a pill's text or an attachment
+  changed under the same id. The clear is now tied to the draft revision that
+  was sent. Anything that changes the draft after the send (the person, the
+  host's `setDraft`, a controlled `draft` / `value` / `heldPastes` /
+  `heldImages` that now says something different) makes it newer, and a newer
+  draft is kept whole. A `ref` arriving from `persistAttachment` mid-send is not
+  a change, so it does not block the clear. A controlled host that echoes a
+  copy of each draft is still cleared, because an echo that says the same thing
+  is not a new revision. Nothing to do on upgrade.
+- **Only the newest send can acknowledge.** Both components refuse a second
+  send while one is pending, and nothing turns that off. If two ever overlapped,
+  the older one settling would have cleared the draft and ended the newer one's
+  `submitting` state. It is now ignored, except that its failure still reaches
+  `onSubmitError`.
+
 ## [5.70.0] - 2026-10-27
 
 ### Added

package/README.md

@@ -161,6 +161,7 @@ npx vite build                      # Build demo app (verifies imports work)
 | Component | Description | Docs |
 |-----------|-------------|------|
 | Composer | Chat-style message input composing textarea + actions | [docs](docs/Composer.md) |
+| ChatThread | Controlled message list for agent and support chat: sanitised markdown, streaming, internal notes, approval cards, stick-to-bottom without yanking | [docs](docs/ChatThread.md) |
 | Chart | SVG-based Bar, Line, Area, Pie, Donut, and Sparkline charts | [docs](docs/Chart.md) |
 | Editor | Toolbar chrome wrapper for contentEditable, with a Source toggle to edit raw HTML/Markdown | [docs](docs/Editor.md) |
 | CodeView | Lightweight syntax-highlighted source view (HTML highlighted; fills height) | [docs](docs/CodeView.md) |

package/dist/autocomplete.cjs

@@ -1,9 +1,9 @@
 'use strict';
 
-var chunkFHRVSYJU_cjs = require('./chunk-FHRVSYJU.cjs');
+var chunkMP55W37V_cjs = require('./chunk-MP55W37V.cjs');
+require('./chunk-J2DI6RMR.cjs');
 require('./chunk-KJ22KE56.cjs');
 require('./chunk-L3V3BYVS.cjs');
-require('./chunk-J2DI6RMR.cjs');
 require('./chunk-6V44RRSB.cjs');
 require('./chunk-MKHYENKR.cjs');
 require('./chunk-TI7D4QDM.cjs');
@@ -16,7 +16,7 @@ require('./chunk-ZU5Q77OT.cjs');
 
 Object.defineProperty(exports, "Autocomplete", {
   enumerable: true,
-  get: function () { return chunkFHRVSYJU_cjs.Autocomplete; }
+  get: function () { return chunkMP55W37V_cjs.Autocomplete; }
 });
 //# sourceMappingURL=autocomplete.cjs.map
 //# sourceMappingURL=autocomplete.cjs.map

package/dist/autocomplete.js

@@ -1,7 +1,7 @@
-export { Autocomplete } from './chunk-TCMOD3WW.js';
+export { Autocomplete } from './chunk-A6NYZ3F5.js';
+import './chunk-MQ6VGG62.js';
 import './chunk-OL53XYHF.js';
 import './chunk-NRXK42LO.js';
-import './chunk-MQ6VGG62.js';
 import './chunk-S42OGG43.js';
 import './chunk-5VMILVWD.js';
 import './chunk-RBCMKPBX.js';

package/dist/chat-thread.cjs

@@ -0,0 +1,27 @@
+'use strict';
+
+var chunk5IE65DIH_cjs = require('./chunk-5IE65DIH.cjs');
+require('./chunk-S3TRSECD.cjs');
+require('./chunk-R3EJNGJV.cjs');
+require('./chunk-2C64OVOZ.cjs');
+require('./chunk-BJL3VDRK.cjs');
+require('./chunk-VBWRH4UW.cjs');
+require('./chunk-MOU6O324.cjs');
+require('./chunk-M5MUGSON.cjs');
+require('./chunk-3U7PUZLI.cjs');
+require('./chunk-XCZZVRBY.cjs');
+require('./chunk-MXWR3T3N.cjs');
+require('./chunk-ZU5Q77OT.cjs');
+
+
+
+Object.defineProperty(exports, "ChatMessage", {
+  enumerable: true,
+  get: function () { return chunk5IE65DIH_cjs.ChatMessage; }
+});
+Object.defineProperty(exports, "ChatThread", {
+  enumerable: true,
+  get: function () { return chunk5IE65DIH_cjs.ChatThread; }
+});
+//# sourceMappingURL=chat-thread.cjs.map
+//# sourceMappingURL=chat-thread.cjs.map

package/dist/chat-thread.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"chat-thread.cjs"}

package/dist/chat-thread.d.cts

@@ -0,0 +1,260 @@
+import * as react from 'react';
+import { ReactNode, HTMLAttributes, Ref } from 'react';
+import { d as ContentRendererProps } from './ContentRenderer.types-RO_l7_6N.cjs';
+
+/**
+ * Who a message is from. The named roles get default labels and styling; any
+ * other string is carried verbatim (`data-chat-role`) and rendered neutrally.
+ */
+type ChatRole = "user" | "assistant" | "system" | "agent" | "staff" | "customer" | (string & {});
+type ChatMessageStatus = "pending" | "streaming" | "sent" | "failed";
+/**
+ * `internal` is a staff-only note. The component LABELS it; it never decides
+ * who sees it. Pass only the messages the viewer is allowed to see.
+ */
+type ChatMessageVisibility = "public" | "internal";
+interface ChatAuthor {
+    name: string;
+    /** Image URL for the avatar. Without it, initials are shown. */
+    avatar?: string;
+}
+/** A file on a message. Rendered as a link, never auto-loaded inline. */
+interface ChatAttachment {
+    id: string;
+    name: string;
+    /** Unsafe schemes (`javascript:`, `data:`, ...) render the name without a link. */
+    url?: string;
+    mimeType?: string;
+    /** Bytes. */
+    size?: number;
+}
+/**
+ * An agent's suggested action awaiting a human: an approval card. The message
+ * `content` is the draft (a reply, a field change, a page edit). The state is
+ * the HOST's: the component shows decision buttons only while `pending`, and
+ * never changes the state itself.
+ */
+interface ChatProposal {
+    /** Stable id, rendered as `data-chat-proposal`. Usually the card id. */
+    id: string;
+    title?: string;
+    /** @default "pending" */
+    state?: "pending" | "accepted" | "rejected" | "withdrawn";
+    /** Overrides the thread's accept / reject labels for this card. */
+    acceptLabel?: string;
+    rejectLabel?: string;
+}
+/** One message. Plain JSON: an agent can emit it, a server can send it. */
+interface ChatMessageData {
+    /** Stable id, rendered as `data-chat-message`. */
+    id: string;
+    role: ChatRole;
+    author?: ChatAuthor;
+    /** Markdown by default; see `format`. Always sanitised. */
+    content: string;
+    /** `"text"` renders the content literally (no markdown, no HTML). @default "markdown" */
+    format?: "markdown" | "text";
+    /** ISO 8601 string or epoch milliseconds. */
+    createdAt: string | number;
+    /** @default "sent" */
+    status?: ChatMessageStatus;
+    /** @default "public" */
+    visibility?: ChatMessageVisibility;
+    attachments?: ChatAttachment[];
+    /** Makes this message an approval card. */
+    proposal?: ChatProposal;
+    /**
+     * Align as the viewer's own message. Defaults to `ownRoles` containing
+     * `role`.
+     */
+    own?: boolean;
+    /** Anything the host wants carried along (card version, ticket ref, ...). Not rendered. */
+    meta?: Record<string, unknown>;
+}
+/**
+ * Every human interaction the thread hands to a callback, as one event stream
+ * for presence, undo and coaching layers. Map it onto fancy-auto-common's
+ * `AutoActivityEvent` (or anything else) in the host.
+ */
+type ChatThreadActivity = {
+    type: "load-earlier";
+} | {
+    type: "proposal-accept";
+    messageId: string;
+    proposalId: string;
+} | {
+    type: "proposal-reject";
+    messageId: string;
+    proposalId: string;
+} | {
+    type: "jump-to-latest";
+    unseen: number;
+};
+/** What `onActionError` is told about: the action whose Promise rejected. */
+type ChatThreadActionContext = Exclude<ChatThreadActivity, {
+    type: "jump-to-latest";
+}>;
+/** A callback that may be acknowledged: return a Promise to disable the control until it settles. */
+type ChatAction<A extends unknown[] = []> = (...args: A) => void | Promise<unknown>;
+/** Every visible string, for translation. */
+interface ChatThreadLabels {
+    /** The log's `aria-label` when there is no `heading`. */
+    log: string;
+    loadEarlier: string;
+    loadingEarlier: string;
+    /** The jump control's text. */
+    newMessages: (count: number) => string;
+    internal: string;
+    pending: string;
+    failed: string;
+    proposal: string;
+    accept: string;
+    reject: string;
+    accepted: string;
+    rejected: string;
+    withdrawn: string;
+    attachments: string;
+    /** Role names shown when a message has no `author`. */
+    roles: Record<string, string>;
+}
+/** Content options passed to every message's `ContentRenderer`. `unsafe` is deliberately absent. */
+type ChatContentOptions = Pick<ContentRendererProps, "extensions" | "copyButtons" | "onCopy" | "clipboardWriter" | "lineSpacing">;
+interface ChatMessageClassNames {
+    message?: string;
+    bubble?: string;
+    header?: string;
+    actions?: string;
+    proposal?: string;
+}
+/** Display options shared by `ChatThread` and a standalone `ChatMessage`. */
+interface ChatMessageDisplayProps {
+    /** Roles aligned as the viewer's own. @default ["user"] */
+    ownRoles?: string[];
+    /**
+     * How a message with `status: "streaming"` renders its unfinished tail
+     * (`ContentRenderer`'s `streaming`). `true` holds back an open fence or tag;
+     * `"progressive"` shows it as it fills. @default true
+     */
+    streaming?: true | "progressive";
+    contentOptions?: ChatContentOptions;
+    labels?: Partial<ChatThreadLabels>;
+    /** Formats a message time. Default: locale time, hours and minutes. */
+    formatTime?: (date: Date) => string;
+    /** Replace how one attachment renders (it is still wrapped in `[data-chat-attachment]`). */
+    renderAttachment?: (attachment: ChatAttachment, message: ChatMessageData) => ReactNode;
+    onProposalAccept?: ChatAction<[message: ChatMessageData]>;
+    onProposalReject?: ChatAction<[message: ChatMessageData]>;
+    onActivity?: (event: ChatThreadActivity) => void;
+    /**
+     * Called when a Promise returned by `onLoadEarlier`, `onProposalAccept` or
+     * `onProposalReject` rejects. Without it the rejection is left unhandled,
+     * so it still reaches the console rather than vanishing.
+     */
+    onActionError?: (error: unknown, action: ChatThreadActionContext) => void;
+    classNames?: ChatMessageClassNames;
+}
+interface ChatMessageProps extends ChatMessageDisplayProps {
+    message: ChatMessageData;
+    /** The per-message actions slot (copy, edit, retry, ...). */
+    actions?: ReactNode;
+    /** A continuation of the previous message's group: the header is omitted. */
+    grouped?: boolean;
+    className?: string;
+}
+interface ChatThreadClassNames extends ChatMessageClassNames {
+    root?: string;
+    heading?: string;
+    log?: string;
+    composer?: string;
+    separator?: string;
+    jump?: string;
+}
+/** Imperative handle, for a host or an agent bridge pointing at a message. */
+interface ChatThreadHandle {
+    /** Scroll the log (only the log) to the newest message. */
+    scrollToLatest(): void;
+    /** Scroll the log (only the log) to a message. `false` if no such message is rendered. */
+    scrollToMessage(id: string): boolean;
+    /** The log element. */
+    readonly element: HTMLDivElement | null;
+}
+interface ChatThreadProps extends ChatMessageDisplayProps, Omit<HTMLAttributes<HTMLDivElement>, "children" | "onChange"> {
+    ref?: Ref<ChatThreadHandle>;
+    /** The messages, oldest first. Controlled: the thread renders exactly these. */
+    messages: ChatMessageData[];
+    /** Visible title; the log is labelled by it. Without it the log gets `labels.log`. */
+    heading?: ReactNode;
+    /** @default 2 */
+    headingLevel?: 2 | 3 | 4 | 5 | 6;
+    /** Shows a "Load earlier messages" control. Return a Promise to disable it until it settles. */
+    onLoadEarlier?: ChatAction;
+    /** Whether there is anything earlier to load. @default true when `onLoadEarlier` is set */
+    hasEarlier?: boolean;
+    /** Host-controlled loading state for the load-earlier control. */
+    loadingEarlier?: boolean;
+    /** Follow new messages while the reader is at the bottom. @default true */
+    stickToBottom?: boolean;
+    /** How close to the bottom (px) still counts as "at the bottom". @default 48 */
+    bottomThreshold?: number;
+    /** Called when the reader arrives at or leaves the bottom. */
+    onAtBottomChange?: (atBottom: boolean) => void;
+    /** `"day"` inserts a separator at each calendar-day change (local time). @default "none" */
+    separators?: "none" | "day";
+    /** Formats a day separator. Default: locale date, medium style. */
+    formatDay?: (date: Date) => string;
+    /**
+     * Merge consecutive messages from the same author: `true` within 5 minutes,
+     * or a window in milliseconds. Internal and public messages never merge.
+     * @default false
+     */
+    groupConsecutive?: boolean | number;
+    /** The per-message actions slot. Return `null` for none. */
+    renderActions?: (message: ChatMessageData) => ReactNode;
+    /** Rendered below the log: put a `Composer` or `PromptInput` here. */
+    composer?: ReactNode;
+    /** Shown in the log when there are no messages. */
+    empty?: ReactNode;
+    classNames?: ChatThreadClassNames;
+}
+
+/**
+ * ChatThread — a controlled message list for agent and support conversations.
+ *
+ * - **Controlled.** It renders exactly `messages`, oldest first. Loading
+ *   earlier history and deciding a proposal go through callbacks; nothing is
+ *   held internally that an agent would need to read or write.
+ * - **Stick to the bottom without yanking.** New messages are followed only
+ *   while the reader is at the bottom. A reader who scrolled up stays put and
+ *   gets an "N new messages" jump control. Prepended history keeps the
+ *   reader's place. Only the log's own `scrollTop` is ever set, and focus moves
+ *   with `preventScroll`, so no ancestor (or the page) scrolls (the 5.69 rule).
+ * - **Visibility is the host's.** `visibility: "internal"` is labelled and
+ *   styled, never filtered: pass only what the viewer may see.
+ * - **Handles:** `data-react-fancy-chat-thread`, `data-chat-message="<id>"`,
+ *   `data-chat-role`, `data-chat-status`, `data-chat-visibility`,
+ *   `data-chat-proposal="<id>"`, `data-chat-proposal-action`.
+ * - **Observable:** `onActivity` reports every interaction as one stream.
+ *
+ * Pair it with `Composer` or `PromptInput` in the `composer` slot (both have
+ * acknowledged send). It does not ship an input of its own.
+ */
+declare function ChatThread({ ref, messages, heading, headingLevel, onLoadEarlier, hasEarlier, loadingEarlier, stickToBottom, bottomThreshold, onAtBottomChange, separators, formatDay, groupConsecutive, renderActions, composer, empty, classNames, className, ownRoles, streaming, contentOptions, labels: labelsProp, formatTime, renderAttachment, onProposalAccept, onProposalReject, onActivity, onActionError, onScroll: onScrollProp, ...rest }: ChatThreadProps): react.JSX.Element;
+declare namespace ChatThread {
+    var displayName: string;
+}
+
+/**
+ * ChatMessage — one message of a `ChatThread`, usable on its own.
+ *
+ * Content is markdown through `ContentRenderer`, always sanitised (there is no
+ * `unsafe` here on purpose: message bodies are text the host did not author).
+ * `format: "text"` renders it literally. A message with a `proposal` is an
+ * approval card: the host owns its state and decides it through
+ * `onProposalAccept` / `onProposalReject`; the card never acts on its own.
+ */
+declare function ChatMessage({ message, actions, grouped, className, ownRoles, streaming, contentOptions, labels: labelsProp, formatTime, renderAttachment, onProposalAccept, onProposalReject, onActivity, onActionError, classNames, }: ChatMessageProps): react.JSX.Element;
+declare namespace ChatMessage {
+    var displayName: string;
+}
+
+export { type ChatAction, type ChatAttachment, type ChatAuthor, type ChatContentOptions, ChatMessage, type ChatMessageClassNames, type ChatMessageData, type ChatMessageDisplayProps, type ChatMessageProps, type ChatMessageStatus, type ChatMessageVisibility, type ChatProposal, type ChatRole, ChatThread, type ChatThreadActionContext, type ChatThreadActivity, type ChatThreadClassNames, type ChatThreadHandle, type ChatThreadLabels, type ChatThreadProps };

package/dist/chat-thread.d.ts

@@ -0,0 +1,260 @@
+import * as react from 'react';
+import { ReactNode, HTMLAttributes, Ref } from 'react';
+import { d as ContentRendererProps } from './ContentRenderer.types-RO_l7_6N.js';
+
+/**
+ * Who a message is from. The named roles get default labels and styling; any
+ * other string is carried verbatim (`data-chat-role`) and rendered neutrally.
+ */
+type ChatRole = "user" | "assistant" | "system" | "agent" | "staff" | "customer" | (string & {});
+type ChatMessageStatus = "pending" | "streaming" | "sent" | "failed";
+/**
+ * `internal` is a staff-only note. The component LABELS it; it never decides
+ * who sees it. Pass only the messages the viewer is allowed to see.
+ */
+type ChatMessageVisibility = "public" | "internal";
+interface ChatAuthor {
+    name: string;
+    /** Image URL for the avatar. Without it, initials are shown. */
+    avatar?: string;
+}
+/** A file on a message. Rendered as a link, never auto-loaded inline. */
+interface ChatAttachment {
+    id: string;
+    name: string;
+    /** Unsafe schemes (`javascript:`, `data:`, ...) render the name without a link. */
+    url?: string;
+    mimeType?: string;
+    /** Bytes. */
+    size?: number;
+}
+/**
+ * An agent's suggested action awaiting a human: an approval card. The message
+ * `content` is the draft (a reply, a field change, a page edit). The state is
+ * the HOST's: the component shows decision buttons only while `pending`, and
+ * never changes the state itself.
+ */
+interface ChatProposal {
+    /** Stable id, rendered as `data-chat-proposal`. Usually the card id. */
+    id: string;
+    title?: string;
+    /** @default "pending" */
+    state?: "pending" | "accepted" | "rejected" | "withdrawn";
+    /** Overrides the thread's accept / reject labels for this card. */
+    acceptLabel?: string;
+    rejectLabel?: string;
+}
+/** One message. Plain JSON: an agent can emit it, a server can send it. */
+interface ChatMessageData {
+    /** Stable id, rendered as `data-chat-message`. */
+    id: string;
+    role: ChatRole;
+    author?: ChatAuthor;
+    /** Markdown by default; see `format`. Always sanitised. */
+    content: string;
+    /** `"text"` renders the content literally (no markdown, no HTML). @default "markdown" */
+    format?: "markdown" | "text";
+    /** ISO 8601 string or epoch milliseconds. */
+    createdAt: string | number;
+    /** @default "sent" */
+    status?: ChatMessageStatus;
+    /** @default "public" */
+    visibility?: ChatMessageVisibility;
+    attachments?: ChatAttachment[];
+    /** Makes this message an approval card. */
+    proposal?: ChatProposal;
+    /**
+     * Align as the viewer's own message. Defaults to `ownRoles` containing
+     * `role`.
+     */
+    own?: boolean;
+    /** Anything the host wants carried along (card version, ticket ref, ...). Not rendered. */
+    meta?: Record<string, unknown>;
+}
+/**
+ * Every human interaction the thread hands to a callback, as one event stream
+ * for presence, undo and coaching layers. Map it onto fancy-auto-common's
+ * `AutoActivityEvent` (or anything else) in the host.
+ */
+type ChatThreadActivity = {
+    type: "load-earlier";
+} | {
+    type: "proposal-accept";
+    messageId: string;
+    proposalId: string;
+} | {
+    type: "proposal-reject";
+    messageId: string;
+    proposalId: string;
+} | {
+    type: "jump-to-latest";
+    unseen: number;
+};
+/** What `onActionError` is told about: the action whose Promise rejected. */
+type ChatThreadActionContext = Exclude<ChatThreadActivity, {
+    type: "jump-to-latest";
+}>;
+/** A callback that may be acknowledged: return a Promise to disable the control until it settles. */
+type ChatAction<A extends unknown[] = []> = (...args: A) => void | Promise<unknown>;
+/** Every visible string, for translation. */
+interface ChatThreadLabels {
+    /** The log's `aria-label` when there is no `heading`. */
+    log: string;
+    loadEarlier: string;
+    loadingEarlier: string;
+    /** The jump control's text. */
+    newMessages: (count: number) => string;
+    internal: string;
+    pending: string;
+    failed: string;
+    proposal: string;
+    accept: string;
+    reject: string;
+    accepted: string;
+    rejected: string;
+    withdrawn: string;
+    attachments: string;
+    /** Role names shown when a message has no `author`. */
+    roles: Record<string, string>;
+}
+/** Content options passed to every message's `ContentRenderer`. `unsafe` is deliberately absent. */
+type ChatContentOptions = Pick<ContentRendererProps, "extensions" | "copyButtons" | "onCopy" | "clipboardWriter" | "lineSpacing">;
+interface ChatMessageClassNames {
+    message?: string;
+    bubble?: string;
+    header?: string;
+    actions?: string;
+    proposal?: string;
+}
+/** Display options shared by `ChatThread` and a standalone `ChatMessage`. */
+interface ChatMessageDisplayProps {
+    /** Roles aligned as the viewer's own. @default ["user"] */
+    ownRoles?: string[];
+    /**
+     * How a message with `status: "streaming"` renders its unfinished tail
+     * (`ContentRenderer`'s `streaming`). `true` holds back an open fence or tag;
+     * `"progressive"` shows it as it fills. @default true
+     */
+    streaming?: true | "progressive";
+    contentOptions?: ChatContentOptions;
+    labels?: Partial<ChatThreadLabels>;
+    /** Formats a message time. Default: locale time, hours and minutes. */
+    formatTime?: (date: Date) => string;
+    /** Replace how one attachment renders (it is still wrapped in `[data-chat-attachment]`). */
+    renderAttachment?: (attachment: ChatAttachment, message: ChatMessageData) => ReactNode;
+    onProposalAccept?: ChatAction<[message: ChatMessageData]>;
+    onProposalReject?: ChatAction<[message: ChatMessageData]>;
+    onActivity?: (event: ChatThreadActivity) => void;
+    /**
+     * Called when a Promise returned by `onLoadEarlier`, `onProposalAccept` or
+     * `onProposalReject` rejects. Without it the rejection is left unhandled,
+     * so it still reaches the console rather than vanishing.
+     */
+    onActionError?: (error: unknown, action: ChatThreadActionContext) => void;
+    classNames?: ChatMessageClassNames;
+}
+interface ChatMessageProps extends ChatMessageDisplayProps {
+    message: ChatMessageData;
+    /** The per-message actions slot (copy, edit, retry, ...). */
+    actions?: ReactNode;
+    /** A continuation of the previous message's group: the header is omitted. */
+    grouped?: boolean;
+    className?: string;
+}
+interface ChatThreadClassNames extends ChatMessageClassNames {
+    root?: string;
+    heading?: string;
+    log?: string;
+    composer?: string;
+    separator?: string;
+    jump?: string;
+}
+/** Imperative handle, for a host or an agent bridge pointing at a message. */
+interface ChatThreadHandle {
+    /** Scroll the log (only the log) to the newest message. */
+    scrollToLatest(): void;
+    /** Scroll the log (only the log) to a message. `false` if no such message is rendered. */
+    scrollToMessage(id: string): boolean;
+    /** The log element. */
+    readonly element: HTMLDivElement | null;
+}
+interface ChatThreadProps extends ChatMessageDisplayProps, Omit<HTMLAttributes<HTMLDivElement>, "children" | "onChange"> {
+    ref?: Ref<ChatThreadHandle>;
+    /** The messages, oldest first. Controlled: the thread renders exactly these. */
+    messages: ChatMessageData[];
+    /** Visible title; the log is labelled by it. Without it the log gets `labels.log`. */
+    heading?: ReactNode;
+    /** @default 2 */
+    headingLevel?: 2 | 3 | 4 | 5 | 6;
+    /** Shows a "Load earlier messages" control. Return a Promise to disable it until it settles. */
+    onLoadEarlier?: ChatAction;
+    /** Whether there is anything earlier to load. @default true when `onLoadEarlier` is set */
+    hasEarlier?: boolean;
+    /** Host-controlled loading state for the load-earlier control. */
+    loadingEarlier?: boolean;
+    /** Follow new messages while the reader is at the bottom. @default true */
+    stickToBottom?: boolean;
+    /** How close to the bottom (px) still counts as "at the bottom". @default 48 */
+    bottomThreshold?: number;
+    /** Called when the reader arrives at or leaves the bottom. */
+    onAtBottomChange?: (atBottom: boolean) => void;
+    /** `"day"` inserts a separator at each calendar-day change (local time). @default "none" */
+    separators?: "none" | "day";
+    /** Formats a day separator. Default: locale date, medium style. */
+    formatDay?: (date: Date) => string;
+    /**
+     * Merge consecutive messages from the same author: `true` within 5 minutes,
+     * or a window in milliseconds. Internal and public messages never merge.
+     * @default false
+     */
+    groupConsecutive?: boolean | number;
+    /** The per-message actions slot. Return `null` for none. */
+    renderActions?: (message: ChatMessageData) => ReactNode;
+    /** Rendered below the log: put a `Composer` or `PromptInput` here. */
+    composer?: ReactNode;
+    /** Shown in the log when there are no messages. */
+    empty?: ReactNode;
+    classNames?: ChatThreadClassNames;
+}
+
+/**
+ * ChatThread — a controlled message list for agent and support conversations.
+ *
+ * - **Controlled.** It renders exactly `messages`, oldest first. Loading
+ *   earlier history and deciding a proposal go through callbacks; nothing is
+ *   held internally that an agent would need to read or write.
+ * - **Stick to the bottom without yanking.** New messages are followed only
+ *   while the reader is at the bottom. A reader who scrolled up stays put and
+ *   gets an "N new messages" jump control. Prepended history keeps the
+ *   reader's place. Only the log's own `scrollTop` is ever set, and focus moves
+ *   with `preventScroll`, so no ancestor (or the page) scrolls (the 5.69 rule).
+ * - **Visibility is the host's.** `visibility: "internal"` is labelled and
+ *   styled, never filtered: pass only what the viewer may see.
+ * - **Handles:** `data-react-fancy-chat-thread`, `data-chat-message="<id>"`,
+ *   `data-chat-role`, `data-chat-status`, `data-chat-visibility`,
+ *   `data-chat-proposal="<id>"`, `data-chat-proposal-action`.
+ * - **Observable:** `onActivity` reports every interaction as one stream.
+ *
+ * Pair it with `Composer` or `PromptInput` in the `composer` slot (both have
+ * acknowledged send). It does not ship an input of its own.
+ */
+declare function ChatThread({ ref, messages, heading, headingLevel, onLoadEarlier, hasEarlier, loadingEarlier, stickToBottom, bottomThreshold, onAtBottomChange, separators, formatDay, groupConsecutive, renderActions, composer, empty, classNames, className, ownRoles, streaming, contentOptions, labels: labelsProp, formatTime, renderAttachment, onProposalAccept, onProposalReject, onActivity, onActionError, onScroll: onScrollProp, ...rest }: ChatThreadProps): react.JSX.Element;
+declare namespace ChatThread {
+    var displayName: string;
+}
+
+/**
+ * ChatMessage — one message of a `ChatThread`, usable on its own.
+ *
+ * Content is markdown through `ContentRenderer`, always sanitised (there is no
+ * `unsafe` here on purpose: message bodies are text the host did not author).
+ * `format: "text"` renders it literally. A message with a `proposal` is an
+ * approval card: the host owns its state and decides it through
+ * `onProposalAccept` / `onProposalReject`; the card never acts on its own.
+ */
+declare function ChatMessage({ message, actions, grouped, className, ownRoles, streaming, contentOptions, labels: labelsProp, formatTime, renderAttachment, onProposalAccept, onProposalReject, onActivity, onActionError, classNames, }: ChatMessageProps): react.JSX.Element;
+declare namespace ChatMessage {
+    var displayName: string;
+}
+
+export { type ChatAction, type ChatAttachment, type ChatAuthor, type ChatContentOptions, ChatMessage, type ChatMessageClassNames, type ChatMessageData, type ChatMessageDisplayProps, type ChatMessageProps, type ChatMessageStatus, type ChatMessageVisibility, type ChatProposal, type ChatRole, ChatThread, type ChatThreadActionContext, type ChatThreadActivity, type ChatThreadClassNames, type ChatThreadHandle, type ChatThreadLabels, type ChatThreadProps };

package/dist/chat-thread.js

@@ -0,0 +1,14 @@
+export { ChatMessage, ChatThread } from './chunk-UWYSJARZ.js';
+import './chunk-AUTW5O4W.js';
+import './chunk-NAYXNVNU.js';
+import './chunk-I3LAFKJU.js';
+import './chunk-UZCR7DK5.js';
+import './chunk-IQ4KQJAO.js';
+import './chunk-6FCQD2KQ.js';
+import './chunk-LQ4ICCN2.js';
+import './chunk-OXERDFFF.js';
+import './chunk-45BBNJQD.js';
+import './chunk-J3A4Z2P7.js';
+import './chunk-MMW2JGKZ.js';
+//# sourceMappingURL=chat-thread.js.map
+//# sourceMappingURL=chat-thread.js.map

package/dist/chat-thread.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"chat-thread.js"}