@cueplusplus/ui 0.13.0

package/dist/chat/composer.js

@@ -0,0 +1,144 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { bareControlClasses, controlGroupFocusClasses, controlSurface } from "../forms/_chassis.js";
+import { Button } from "../primitives/button.js";
+import { useIsomorphicLayoutEffect } from "../system/use-isomorphic-layout-effect.js";
+import * as React from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/chat/composer.tsx
+/** How tall the box may grow before it starts scrolling instead. */
+const DEFAULT_MAX_ROWS = 8;
+/**
+* The thing you type into: an auto-growing textarea, a send affordance, and
+* slots for everything a host wants to hang off them.
+*
+* Three decisions worth stating:
+*
+* - **It grows, it does not scroll.** A one-line box that hides the second half
+*   of what you wrote is the most-complained-about part of every chat UI. The
+*   box starts at the tall control rung and grows to `maxRows` before it gives
+*   up and scrolls.
+* - **The submit gesture is a setting.** Enter-to-send is right for a chat lane
+*   and wrong for a prompt editor where every draft is three paragraphs, so
+*   both are first-class and the *other* key always inserts a newline.
+* - **Stop is never disabled.** While a run is in flight the composer is
+*   `disabled`, but the button that ends the run cannot inherit that — a stop
+*   you cannot press is not a stop.
+*
+* The ref lands on the textarea rather than the form: focusing the composer is
+* the thing hosts actually reach for.
+*
+* @example
+* <Composer onSend={send} />
+* @example
+* <Composer submitKey="mod+enter" busy={running} onStop={abort} onSend={send} />
+*/
+const Composer = React.forwardRef(function Composer({ className, onSend, value: valueProp, defaultValue = "", onValueChange, placeholder = "Message", disabled = false, busy = false, onStop, submitKey = "enter", maxRows = DEFAULT_MAX_ROWS, sendLabel = "Send", stopLabel = "Stop", attachments, toolbar, hint, "aria-label": ariaLabel = "Message", ...elementProps }, ref) {
+	const isControlled = valueProp !== void 0;
+	const [uncontrolled, setUncontrolled] = React.useState(defaultValue);
+	const value = isControlled ? valueProp : uncontrolled;
+	const inputRef = React.useRef(null);
+	const setInputRef = React.useCallback((element) => {
+		inputRef.current = element;
+		if (typeof ref === "function") ref(element);
+		else if (ref !== null) ref.current = element;
+	}, [ref]);
+	useIsomorphicLayoutEffect(() => {
+		const element = inputRef.current;
+		if (element === null) return;
+		element.style.height = "auto";
+		const line = Number.parseFloat(getComputedStyle(element).lineHeight);
+		const cap = Number.isFinite(line) && line > 0 ? line * maxRows : Number.POSITIVE_INFINITY;
+		const content = element.scrollHeight;
+		if (content > 0) element.style.height = `${Math.min(content, cap)}px`;
+		else element.style.removeProperty("height");
+		element.style.overflowY = content > cap ? "auto" : "hidden";
+	}, [maxRows, value]);
+	const setValue = React.useCallback((next) => {
+		if (!isControlled) setUncontrolled(next);
+		onValueChange?.(next);
+	}, [isControlled, onValueChange]);
+	const ready = value.trim().length > 0;
+	const submit = React.useCallback(() => {
+		if (disabled || !ready) return;
+		onSend(value.trim());
+		if (!isControlled) setUncontrolled("");
+	}, [
+		disabled,
+		isControlled,
+		onSend,
+		ready,
+		value
+	]);
+	const onKeyDown = (event) => {
+		if (event.key !== "Enter" || event.nativeEvent.isComposing) return;
+		const withMod = event.metaKey || event.ctrlKey;
+		if (!(submitKey === "enter" ? !event.shiftKey && !withMod : withMod)) return;
+		event.preventDefault();
+		submit();
+	};
+	return /* @__PURE__ */ jsxs("form", {
+		"data-slot": "composer",
+		"data-busy": busy ? "" : void 0,
+		className: cn("flex min-w-0 flex-col gap-(--cue-space-2)", className),
+		onSubmit: (event) => {
+			event.preventDefault();
+			submit();
+		},
+		...elementProps,
+		children: [
+			attachments === void 0 ? null : /* @__PURE__ */ jsx("div", {
+				"data-slot": "composer-attachments",
+				className: "flex min-w-0 flex-wrap items-center gap-(--cue-space-2)",
+				children: attachments
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				"data-slot": "composer-field",
+				className: cn(controlSurface, controlGroupFocusClasses, "flex items-end gap-(--cue-space-3) p-(--cue-space-3)"),
+				children: [
+					/* @__PURE__ */ jsx("textarea", {
+						ref: setInputRef,
+						rows: 1,
+						"data-slot": "composer-input",
+						"aria-label": ariaLabel,
+						placeholder,
+						disabled,
+						value,
+						className: cn(bareControlClasses, "min-h-control-lg resize-none self-stretch py-(--cue-space-2) text-(length:--cue-text-body) leading-(--cue-leading-ui)"),
+						onChange: (event) => setValue(event.target.value),
+						onKeyDown
+					}),
+					toolbar === void 0 ? null : /* @__PURE__ */ jsx("div", {
+						"data-slot": "composer-toolbar",
+						className: "flex shrink-0 items-center gap-(--cue-space-2)",
+						children: toolbar
+					}),
+					busy && onStop !== void 0 ? /* @__PURE__ */ jsx(Button, {
+						type: "button",
+						variant: "outline",
+						size: "sm",
+						"data-slot": "composer-stop",
+						className: "shrink-0",
+						onClick: onStop,
+						children: stopLabel
+					}) : /* @__PURE__ */ jsx(Button, {
+						type: "submit",
+						variant: "primary",
+						size: "sm",
+						"data-slot": "composer-send",
+						className: "shrink-0",
+						disabled: disabled || !ready,
+						children: sendLabel
+					})
+				]
+			}),
+			hint === void 0 ? null : /* @__PURE__ */ jsx("div", {
+				"data-slot": "composer-hint",
+				className: "flex min-w-0 items-center justify-between gap-(--cue-space-3) font-mono text-(length:--cue-text-micro) text-fg-subtle",
+				children: hint
+			})
+		]
+	});
+});
+//#endregion
+export { Composer };

package/dist/chat/delegation-card.d.ts

@@ -0,0 +1,60 @@
+import * as React from "react";
+//#region src/chat/delegation-card.d.ts
+/** Which way the delegation runs relative to the lane you are reading. */
+type DelegationDirection = "outbound" | "inbound";
+/** Where the delegated work has got to. */
+type DelegationStatus = "working" | "done" | "failed" | "idle";
+interface DelegationCardProps extends Omit<React.ComponentPropsWithoutRef<"div">, "title" | "onToggle"> {
+  /** Slug of the agent on the other end of the delegation. */
+  agent: string;
+  /** Slug of the orchestrator, so its lane takes the theme accent. */
+  rootAgent?: string;
+  /** `outbound` (we asked them) or `inbound` (they asked us). Defaults to `"outbound"`. */
+  direction?: DelegationDirection;
+  /** What the delegate was asked to do — one line, already summarised. */
+  task?: React.ReactNode;
+  /** Where the work has got to. Omit to draw no status line at all. */
+  status?: DelegationStatus;
+  /** What the delegate is doing right now. Shown beside the spinner while `working`. */
+  activity?: React.ReactNode;
+  /** Open state when controlled. Pass with `onOpenChange`. */
+  open?: boolean;
+  /** Initial open state. Defaults to open for an inbound card, shut for an outbound one. */
+  defaultOpen?: boolean;
+  /** Called with the state the card is asking to move to. */
+  onOpenChange?: (open: boolean) => void;
+  /** What a finished delegation says. Defaults to `"Completed"`. */
+  doneLabel?: React.ReactNode;
+  /** What a failed delegation says. Defaults to `"Failed"`. */
+  failedLabel?: React.ReactNode;
+  /** The nested transcript. */
+  children?: React.ReactNode;
+}
+/**
+ * One delegation, folded into a card.
+ *
+ * A multi-agent run is a tree, and rendering it flat is what turns a transcript
+ * into noise: the reader loses which turns belong to which sub-agent and how
+ * deep they are. This is the fold — a one-line header naming who was asked and
+ * what for, a live status line under it, and the sub-agent's own transcript
+ * behind a disclosure, railed in that agent's colour so nesting is legible at a
+ * glance.
+ *
+ * The body is mounted and unmounted rather than height-animated. A delegation's
+ * transcript grows while it is open, and animating the height of something that
+ * changes size on its own is how a panel ends up permanently mid-transition.
+ *
+ * Direction matters to the sentence. From the caller's lane the card reads
+ * "asked researcher — …"; in the delegate's own lane it reads "chief asked
+ * — …", which is the same fact from the other side.
+ *
+ * @example
+ * <DelegationCard agent="researcher" task="find three references" status="working">
+ *   {turns}
+ * </DelegationCard>
+ * @example
+ * <DelegationCard agent="chief" direction="inbound" task="draft the brief">{turns}</DelegationCard>
+ */
+declare const DelegationCard: React.ForwardRefExoticComponent<DelegationCardProps & React.RefAttributes<HTMLDivElement>>;
+//#endregion
+export { DelegationCard, DelegationCardProps, DelegationDirection, DelegationStatus };

package/dist/chat/delegation-card.js

@@ -0,0 +1,129 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { agentColor } from "./agent-color.js";
+import { CheckGlyph } from "./_glyphs.js";
+import { Spinner } from "../primitives/spinner.js";
+import * as React from "react";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+//#region src/chat/delegation-card.tsx
+/**
+* One delegation, folded into a card.
+*
+* A multi-agent run is a tree, and rendering it flat is what turns a transcript
+* into noise: the reader loses which turns belong to which sub-agent and how
+* deep they are. This is the fold — a one-line header naming who was asked and
+* what for, a live status line under it, and the sub-agent's own transcript
+* behind a disclosure, railed in that agent's colour so nesting is legible at a
+* glance.
+*
+* The body is mounted and unmounted rather than height-animated. A delegation's
+* transcript grows while it is open, and animating the height of something that
+* changes size on its own is how a panel ends up permanently mid-transition.
+*
+* Direction matters to the sentence. From the caller's lane the card reads
+* "asked researcher — …"; in the delegate's own lane it reads "chief asked
+* — …", which is the same fact from the other side.
+*
+* @example
+* <DelegationCard agent="researcher" task="find three references" status="working">
+*   {turns}
+* </DelegationCard>
+* @example
+* <DelegationCard agent="chief" direction="inbound" task="draft the brief">{turns}</DelegationCard>
+*/
+const DelegationCard = React.forwardRef(function DelegationCard({ className, agent, rootAgent, direction = "outbound", task, status, activity, open: openProp, defaultOpen, onOpenChange, doneLabel = "Completed", failedLabel = "Failed", children, style, ...elementProps }, ref) {
+	const bodyId = React.useId();
+	const isControlled = openProp !== void 0;
+	const [uncontrolled, setUncontrolled] = React.useState(defaultOpen ?? direction === "inbound");
+	const open = isControlled ? openProp : uncontrolled;
+	const toggle = () => {
+		const next = !open;
+		if (!isControlled) setUncontrolled(next);
+		onOpenChange?.(next);
+	};
+	const color = agentColor(agent, { root: rootAgent });
+	const name = /* @__PURE__ */ jsx("span", {
+		className: "text-(--agent-color)",
+		children: agent
+	});
+	return /* @__PURE__ */ jsxs("div", {
+		ref,
+		"data-slot": "delegation-card",
+		"data-direction": direction,
+		"data-state": open ? "open" : "closed",
+		"data-status": status,
+		className: cn("flex min-w-0 flex-col gap-(--cue-space-2) rounded-(--radius-control) border border-border px-(--cue-space-3) py-(--cue-space-2)", className),
+		style: {
+			"--agent-color": color,
+			...style
+		},
+		...elementProps,
+		children: [
+			/* @__PURE__ */ jsxs("button", {
+				type: "button",
+				"data-slot": "delegation-card-trigger",
+				"aria-expanded": open,
+				"aria-controls": open ? bodyId : void 0,
+				className: "flex min-w-0 cursor-pointer items-center gap-(--cue-space-2) border-0 bg-transparent p-0 text-start font-mono text-(length:--cue-text-ui) text-fg-muted outline-none focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-offset-2 focus-visible:outline-accent",
+				onClick: toggle,
+				children: [
+					/* @__PURE__ */ jsx("span", {
+						"aria-hidden": "true",
+						"data-slot": "delegation-card-caret",
+						className: "shrink-0 text-(length:--cue-text-micro) leading-none select-none",
+						children: open ? "▾" : "▸"
+					}),
+					/* @__PURE__ */ jsx("span", {
+						"aria-hidden": "true",
+						className: "shrink-0 text-(--agent-color)",
+						children: "●"
+					}),
+					/* @__PURE__ */ jsxs("span", {
+						"data-slot": "delegation-card-title",
+						className: "min-w-0 truncate",
+						children: [direction === "inbound" ? /* @__PURE__ */ jsxs(Fragment, { children: [name, " asked"] }) : /* @__PURE__ */ jsxs(Fragment, { children: ["asked ", name] }), task === void 0 ? null : /* @__PURE__ */ jsxs("span", {
+							className: "text-fg-subtle",
+							children: [" — ", task]
+						})]
+					})
+				]
+			}),
+			status === void 0 ? null : /* @__PURE__ */ jsxs("div", {
+				"data-slot": "delegation-card-status",
+				"data-status": status,
+				className: cn("flex min-w-0 items-center gap-(--cue-space-2) ps-(--cue-space-5) font-mono text-(length:--cue-text-micro)", status === "failed" ? "text-danger" : "text-fg-subtle"),
+				children: [
+					status === "working" ? /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx(Spinner, {
+						size: "sm",
+						label: "working",
+						"data-slot": "delegation-card-spinner",
+						className: "text-(--agent-color)"
+					}), /* @__PURE__ */ jsx("span", {
+						className: "min-w-0 truncate",
+						children: activity ?? "working…"
+					})] }) : null,
+					status === "done" ? /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx(CheckGlyph, { className: "size-icon-sm shrink-0 text-ok" }), /* @__PURE__ */ jsx("span", {
+						className: "min-w-0 truncate",
+						children: doneLabel
+					})] }) : null,
+					status === "failed" ? /* @__PURE__ */ jsx("span", {
+						className: "min-w-0 truncate",
+						children: failedLabel
+					}) : null,
+					status === "idle" ? /* @__PURE__ */ jsx("span", {
+						className: "min-w-0 truncate",
+						children: activity ?? "waiting"
+					}) : null
+				]
+			}),
+			open ? /* @__PURE__ */ jsx("div", {
+				id: bodyId,
+				"data-slot": "delegation-card-body",
+				className: "ms-(--cue-space-3) flex min-w-0 flex-col gap-(--cue-space-2) border-s-2 [border-inline-start-color:var(--agent-color)] ps-(--cue-space-4)",
+				children
+			}) : null
+		]
+	});
+});
+//#endregion
+export { DelegationCard };

package/dist/chat/index.d.ts

@@ -0,0 +1,8 @@
+import { AskAnswer, AskBox, AskBoxProps, AskDanger, AskKind, AskOption } from "./ask-box.js";
+import { Message, MessageProps, MessageRole } from "./message.js";
+import { AGENT_COLOR_PROPERTY, AGENT_HUES, AGENT_ROOT_COLOR, AgentColorOptions, agentColor, agentColorStyle } from "./agent-color.js";
+import { AgentPile, AgentPileEntry, AgentPileProps, AgentPileSize } from "./agent-pile.js";
+import { Composer, ComposerProps, ComposerSubmitKey } from "./composer.js";
+import { DelegationCard, DelegationCardProps, DelegationDirection, DelegationStatus } from "./delegation-card.js";
+import { MessageList, MessageListProps } from "./message-list.js";
+export { AGENT_COLOR_PROPERTY, AGENT_HUES, AGENT_ROOT_COLOR, type AgentColorOptions, AgentPile, type AgentPileEntry, type AgentPileProps, type AgentPileSize, type AskAnswer, AskBox, type AskBoxProps, type AskDanger, type AskKind, type AskOption, Composer, type ComposerProps, type ComposerSubmitKey, DelegationCard, type DelegationCardProps, type DelegationDirection, type DelegationStatus, Message, MessageList, type MessageListProps, type MessageProps, type MessageRole, agentColor, agentColorStyle };

package/dist/chat/index.js

@@ -0,0 +1,8 @@
+import { AGENT_COLOR_PROPERTY, AGENT_HUES, AGENT_ROOT_COLOR, agentColor, agentColorStyle } from "./agent-color.js";
+import { AgentPile } from "./agent-pile.js";
+import { AskBox } from "./ask-box.js";
+import { Composer } from "./composer.js";
+import { DelegationCard } from "./delegation-card.js";
+import { Message } from "./message.js";
+import { MessageList } from "./message-list.js";
+export { AGENT_COLOR_PROPERTY, AGENT_HUES, AGENT_ROOT_COLOR, AgentPile, AskBox, Composer, DelegationCard, Message, MessageList, agentColor, agentColorStyle };

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

@@ -0,0 +1,45 @@
+import * as React from "react";
+//#region src/chat/message-list.d.ts
+interface MessageListProps extends Omit<React.ComponentPropsWithoutRef<"div">, "onScroll"> {
+  /** The turns, oldest first — normally {@link Message}s. */
+  children?: React.ReactNode;
+  /** Stick to the bottom as turns arrive. Defaults to `true`. */
+  follow?: boolean;
+  /** Fixed height in px at the 16px root, emitted as rem. Omit to fill the parent. */
+  height?: number;
+  /** Label on the catch-up pill. Defaults to `"Jump to latest"`. */
+  jumpLabel?: React.ReactNode;
+  /** What to say before the first turn. Defaults to `"No messages yet"`. */
+  emptyLabel?: React.ReactNode;
+  /** Accessible name for the transcript. Required in practice — name the thread. */
+  "aria-label"?: string;
+}
+/**
+ * The transcript scroller: sticks to the bottom, and stops fighting you the
+ * moment you scroll up.
+ *
+ * Following is a *mode*, not a scroll position. While pinned to the bottom the
+ * view follows new turns; scroll up to read something and it lets go and offers
+ * a "jump to latest" pill instead — because a stream that yanks the viewport
+ * mid-sentence is the single most common reason people stop reading a chat
+ * pane. Coming back to the bottom re-arms it.
+ *
+ * It follows a turn that is still growing, too — the items container is watched
+ * for growth, so a streaming bubble keeps the bottom in view without the host
+ * adding anything, while something merely collapsing leaves the view alone. And
+ * when you have scrolled up, a turn that grows offers the pill instead of
+ * pulling you down.
+ *
+ * Deliberately **not** virtualised. A virtualiser needs a measurable row height
+ * and chat turns are variable-height by nature; the cost of getting that wrong
+ * (jumping scrollbars) is worse than the cost of a few hundred DOM nodes. When
+ * a thread really is unbounded, page it — do not virtualise it.
+ *
+ * @example
+ * <MessageList aria-label="Thread" height={480}>
+ *   {turns.map((t) => <Message key={t.id} agent={t.agent}>{t.text}</Message>)}
+ * </MessageList>
+ */
+declare const MessageList: React.ForwardRefExoticComponent<MessageListProps & React.RefAttributes<HTMLDivElement>>;
+//#endregion
+export { MessageList, MessageListProps };

package/dist/chat/message-list.js

@@ -0,0 +1,141 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { ChevronDownGlyph } from "./_glyphs.js";
+import { useIsomorphicLayoutEffect } from "../system/use-isomorphic-layout-effect.js";
+import * as React from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/chat/message-list.tsx
+/** Slack, in px, for "close enough to the bottom to count as pinned". */
+const BOTTOM_TOLERANCE = 8;
+/** The reference root font size a `height` prop is quoted against. */
+const ROOT_PX = 16;
+/**
+* The transcript scroller: sticks to the bottom, and stops fighting you the
+* moment you scroll up.
+*
+* Following is a *mode*, not a scroll position. While pinned to the bottom the
+* view follows new turns; scroll up to read something and it lets go and offers
+* a "jump to latest" pill instead — because a stream that yanks the viewport
+* mid-sentence is the single most common reason people stop reading a chat
+* pane. Coming back to the bottom re-arms it.
+*
+* It follows a turn that is still growing, too — the items container is watched
+* for growth, so a streaming bubble keeps the bottom in view without the host
+* adding anything, while something merely collapsing leaves the view alone. And
+* when you have scrolled up, a turn that grows offers the pill instead of
+* pulling you down.
+*
+* Deliberately **not** virtualised. A virtualiser needs a measurable row height
+* and chat turns are variable-height by nature; the cost of getting that wrong
+* (jumping scrollbars) is worse than the cost of a few hundred DOM nodes. When
+* a thread really is unbounded, page it — do not virtualise it.
+*
+* @example
+* <MessageList aria-label="Thread" height={480}>
+*   {turns.map((t) => <Message key={t.id} agent={t.agent}>{t.text}</Message>)}
+* </MessageList>
+*/
+const MessageList = React.forwardRef(function MessageList({ className, children, follow = true, height, jumpLabel = "Jump to latest", emptyLabel = "No messages yet", "aria-label": ariaLabel, style, ...elementProps }, ref) {
+	const scrollerRef = React.useRef(null);
+	const itemsRef = React.useRef(null);
+	const [pinned, setPinned] = React.useState(true);
+	const [behind, setBehind] = React.useState(false);
+	const lastHeightRef = React.useRef(0);
+	const count = React.Children.count(children);
+	const isEmpty = count === 0;
+	const previousCountRef = React.useRef(count);
+	const jumpToLatest = React.useCallback(() => {
+		const element = scrollerRef.current;
+		if (element === null) return;
+		element.scrollTop = element.scrollHeight;
+		setPinned(true);
+		setBehind(false);
+	}, []);
+	useIsomorphicLayoutEffect(() => {
+		const element = scrollerRef.current;
+		const added = count - previousCountRef.current;
+		previousCountRef.current = count;
+		if (element === null) return;
+		if (follow && pinned) {
+			element.scrollTop = element.scrollHeight;
+			setBehind(false);
+			return;
+		}
+		if (added > 0) setBehind(true);
+	}, [
+		count,
+		follow,
+		pinned
+	]);
+	React.useEffect(() => {
+		const element = scrollerRef.current;
+		const items = itemsRef.current;
+		if (items === null) lastHeightRef.current = 0;
+		if (element === null || items === null || typeof ResizeObserver === "undefined") return;
+		const observer = new ResizeObserver((entries) => {
+			const entry = entries[0];
+			if (entry === void 0) return;
+			const height = entry.contentRect?.height ?? entry.target.getBoundingClientRect().height;
+			const grew = height > lastHeightRef.current;
+			lastHeightRef.current = height;
+			if (!grew) return;
+			if (follow && pinned) {
+				element.scrollTop = element.scrollHeight;
+				setBehind(false);
+				return;
+			}
+			setBehind(true);
+		});
+		observer.observe(items);
+		return () => observer.disconnect();
+	}, [
+		follow,
+		pinned,
+		isEmpty
+	]);
+	const onScroll = React.useCallback(() => {
+		const element = scrollerRef.current;
+		if (element === null) return;
+		const atBottom = element.scrollHeight - element.scrollTop - element.clientHeight <= BOTTOM_TOLERANCE;
+		setPinned(atBottom);
+		if (atBottom) setBehind(false);
+	}, []);
+	return /* @__PURE__ */ jsxs("div", {
+		ref,
+		"data-slot": "message-list",
+		"data-pinned": String(pinned),
+		className: cn("relative flex min-h-0 min-w-0 flex-col overflow-hidden", className),
+		style: height === void 0 ? style : {
+			height: `${height / ROOT_PX}rem`,
+			...style
+		},
+		...elementProps,
+		children: [/* @__PURE__ */ jsx("div", {
+			ref: scrollerRef,
+			role: "log",
+			"aria-label": ariaLabel,
+			tabIndex: 0,
+			"data-slot": "message-list-scroller",
+			className: "min-h-0 flex-1 overflow-y-auto outline-none focus-visible:outline-2 focus-visible:outline-solid focus-visible:-outline-offset-2 focus-visible:outline-accent",
+			onScroll,
+			children: count === 0 ? /* @__PURE__ */ jsx("div", {
+				"data-slot": "message-list-empty",
+				className: "flex h-full items-center justify-center p-(--cue-space-6) font-mono text-(length:--cue-text-ui) text-fg-subtle",
+				children: emptyLabel
+			}) : /* @__PURE__ */ jsx("div", {
+				ref: itemsRef,
+				"data-slot": "message-list-items",
+				className: "flex min-w-0 flex-col items-stretch gap-(--cue-space-4) p-(--cue-space-4)",
+				children
+			})
+		}), behind ? /* @__PURE__ */ jsxs("button", {
+			type: "button",
+			"data-slot": "message-list-jump",
+			className: "absolute bottom-(--cue-space-4) left-1/2 flex -translate-x-1/2 cursor-pointer items-center gap-(--cue-space-2) rounded-(--radius-control) border border-border-overlay bg-surface-2 px-(--cue-space-4) py-(--cue-space-2) font-mono text-(length:--cue-text-label) text-fg shadow-[0_8px_24px_rgba(0,0,0,0.4)] outline-none hover:border-accent hover:text-accent focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-offset-1 focus-visible:outline-accent",
+			onClick: jumpToLatest,
+			children: [/* @__PURE__ */ jsx(ChevronDownGlyph, { className: "size-icon-sm" }), jumpLabel]
+		}) : null]
+	});
+});
+//#endregion
+export { MessageList };

package/dist/chat/message.d.ts

@@ -0,0 +1,47 @@
+import * as React from "react";
+//#region src/chat/message.d.ts
+/** Who is speaking. Drives the fill, the alignment and which corner the tail is on. */
+type MessageRole = "user" | "agent" | "system";
+interface MessageProps extends Omit<React.ComponentPropsWithoutRef<"div">, "role"> {
+  /** Who is speaking. Defaults to `"agent"`. */
+  role?: MessageRole;
+  /**
+   * The speaking agent's slug. Names the turn and inks the author line and the
+   * `--agent-color` custom property, which anything nested reads.
+   */
+  agent?: string;
+  /** Slug of the orchestrator, so its turns take the theme accent. */
+  rootAgent?: string;
+  /** Author line override. Defaults to `"You"` for the user and to `agent` otherwise. */
+  author?: React.ReactNode;
+  /** Rendered opposite the author — pass a formatted time, not a `Date`. */
+  timestamp?: React.ReactNode;
+  /** The turn is still streaming: shows a caret and announces it. */
+  pending?: boolean;
+  /** Slot under the body — attachments, warnings, retry actions. */
+  footer?: React.ReactNode;
+  /** The turn itself. */
+  children?: React.ReactNode;
+}
+/**
+ * One turn in a conversation.
+ *
+ * Content is rendered as React nodes, verbatim: there is no markdown or HTML
+ * path here on purpose. Model output is untrusted text, and a component that
+ * quietly parsed it would make every consumer of this library one prompt away
+ * from an injection. Callers that want rich text pass their own renderer as
+ * children and own that decision.
+ *
+ * The author line is mono micro and inked in the agent's own colour, so a
+ * multi-agent thread is scannable by hue before it is readable by name.
+ *
+ * Static markup — no `"use client"`; a transcript renders on the server.
+ *
+ * @example
+ * <Message agent="researcher" timestamp="14:02">Found three references.</Message>
+ * @example
+ * <Message role="user">Patch universe 3.</Message>
+ */
+declare const Message: React.ForwardRefExoticComponent<MessageProps & React.RefAttributes<HTMLDivElement>>;
+//#endregion
+export { Message, MessageProps, MessageRole };