@djangocfg/widget-chat 0.1.1

package/src/ui/chat-reply-chip.tsx

@@ -0,0 +1,42 @@
+import { X } from "lucide-react";
+
+import { messageCopyText } from "./message-actions";
+import { useChatCopy } from "../i18n";
+import { useComposer } from "../composer/context";
+import { useMessage } from "../store";
+
+/**
+ * What this draft answers, above the field, with a way out.
+ *
+ * Self-gating like the starter rows beside it: absent target, or a target the
+ * transcript no longer holds, renders nothing. A chip naming a message the
+ * reader cannot see would describe a quote that will not appear.
+ *
+ * The quote is resolved from the STORE, not from a capability: the transcript
+ * is already in this package, and asking the host to resolve an id it gave us
+ * would be a second index that can disagree with the first.
+ */
+export function ChatReplyChip() {
+  const copy = useChatCopy().composer;
+  const { draft, setReplyTo } = useComposer();
+  const target = useMessage(draft.replyTo ?? "");
+
+  if (draft.replyTo === undefined || target === undefined) return null;
+
+  return (
+    <div className="chat-reply-chip flex w-full items-center gap-2 text-xs">
+      <span className="bg-primary/60 h-4 w-0.5 shrink-0 rounded-full" aria-hidden />
+      <span className="text-muted-foreground min-w-0 flex-1 truncate">
+        {messageCopyText(target)}
+      </span>
+      <button
+        type="button"
+        onClick={() => setReplyTo(undefined)}
+        aria-label={copy.replyClear}
+        className="hover:bg-muted shrink-0 rounded p-0.5"
+      >
+        <X className="h-3 w-3" aria-hidden />
+      </button>
+    </div>
+  );
+}

package/src/ui/chat-suggestions.tsx

@@ -0,0 +1,87 @@
+import type { ReactNode } from "react";
+
+import { useChatCopy } from "../i18n";
+import { Suggestions } from "../primitives/suggestions";
+
+export interface ChatSuggestionsProps {
+  /**
+   * Icon KEY → glyph. Absent, or an unmapped key, draws no glyph — a row still
+   * works without its picture.
+   *
+   * A function rather than a map so the host owns the lookup: the catalogue
+   * names glyphs as data, and this package ships no icon library. That is the
+   * same contract the composer's slash menu takes.
+   */
+  readonly icon?: (key: string) => ReactNode;
+}
+
+/*
+  Full width with the text left-aligned: the titles differ in length, and
+  centred rows of different widths give the eye no shared edge to scan down.
+
+  `text-left` is not redundant with the flex alignment — a button centres its
+  text by default, and that survives `items-center`.
+*/
+const ROW =
+  "group flex w-full items-center gap-2.5 rounded-lg px-3 py-2 text-left " +
+  "text-[length:var(--chat-text)] transition-colors hover:bg-foreground/5 " +
+  "focus-visible:bg-foreground/5 focus-visible:outline-none";
+
+const TITLE = "min-w-0 truncate text-muted-foreground group-hover:text-foreground";
+
+/*
+  No gap between rows: they are one column of targets, and a pointer moving down
+  it must not cross dead space between them. The rows' own padding is the
+  spacing.
+
+  `pb-3` is the air between the last row and the field, so the group reads as an
+  offer above the input rather than part of it.
+
+  `-ms-3` cancels the row's `px-3` so the glyphs line up with the field's text.
+  The LOGICAL property, not `-ml-3`: the row mirrors under `dir="rtl"` on its
+  own, and a physical margin would pull it the wrong way.
+*/
+const LIST = "-ms-3 flex flex-col pb-3";
+
+/**
+ * The starter rows, styled.
+ *
+ * ONE assembly, for the reason `ChatTranscript` is one: a host composing the
+ * primitive by hand ships whichever part it forgot, and nothing fails — the
+ * feature is simply absent.
+ *
+ * Mounted in the composer's `above` slot rather than in the transcript. Both
+ * are defensible; the composer wins because that is where the user already
+ * looks when deciding what to type, and because these rows are an INPUT
+ * affordance — sitting where the answer appears made them read as content the
+ * room already had.
+ *
+ * WHEN they show is the primitive's decision, not this slot's: `<Suggestions>`
+ * renders nothing unless the room is genuinely empty, so a host passes it
+ * unconditionally the way it passes `<AskSurface>`.
+ *
+ * A vertical list, not the horizontal pills the vendored Vercel primitive uses.
+ * The chat pane is often narrow on a wide screen, and pills either wrap into a
+ * ragged block or scroll sideways, which hides rows behind a gesture nobody
+ * makes on a first visit. Vercel's own docs widget — the shape this was modelled
+ * on — is vertical for the same reason.
+ */
+export function ChatSuggestions({ icon }: ChatSuggestionsProps) {
+  const copy = useChatCopy().transcript;
+
+  return (
+    <Suggestions className={LIST} label={copy.suggestionsLabel}>
+      {({ suggestion, onSelect }) => {
+        // An absent glyph collapses rather than reserving a gap: a list where
+        // only some rows have icons should not indent the rest to match.
+        const glyph = icon?.(suggestion.icon ?? "");
+        return (
+          <button type="button" onClick={onSelect} className={ROW}>
+            {glyph}
+            <span className={TITLE}>{suggestion.title}</span>
+          </button>
+        );
+      }}
+    </Suggestions>
+  );
+}

package/src/ui/chat-transcript.tsx

@@ -0,0 +1,157 @@
+import { ArrowDown } from "lucide-react";
+import type { ReactNode } from "react";
+
+import type { ChatMessage } from "../core";
+import { fill, useChatCopy } from "../i18n";
+import { Transcript, useHasSuggestions } from "../primitives";
+import { JumpToLatest } from "./jump-to-latest";
+import { ChatMessageView } from "./message";
+import { PendingIndicator } from "./pending";
+import { TurnMark } from "./turn-mark";
+
+export interface ChatTranscriptProps {
+  /**
+   * Rendered under each message's parts — the action row.
+   *
+   * WHICH actions exist is the host's inventory, so this stays a slot rather
+   * than a labels entry.
+   */
+  readonly footer?: (message: ChatMessage) => ReactNode;
+  /**
+   * Rendered above each message, outside its frame — the speaker's name line.
+   *
+   * Passed through to the row, which places it: only a ROOM has several
+   * speakers to tell apart, and a host with one correspondent passes nothing.
+   */
+  readonly header?: (message: ChatMessage) => ReactNode;
+  /**
+   * Replaces the default empty-room line, for a host that has something truer
+   * to say about THIS room than "no messages yet".
+   *
+   * A slot rather than a labels entry: the host renders a node, not a string,
+   * and only the host knows the facts its room carries. The primitive still
+   * owns WHEN an empty state may paint — a pending fetch and an in-flight first
+   * turn both suppress it — so a host node cannot claim a room is empty while
+   * history is still loading.
+   */
+  readonly empty?: ReactNode;
+  readonly className?: string;
+}
+
+/**
+ * The transcript, assembled.
+ *
+ * ONE assembly, for the reason `ChatComposer` is one: the pending indicator and
+ * the jump-to-latest control are render props on the primitive, so a host that
+ * composes it by hand ships a transcript missing whichever it forgot — and
+ * nothing fails, the feature is simply absent. That is not hypothetical:
+ * `jumpToLatest` existed on the primitive with no consumer at all until this
+ * assembly filled it.
+ *
+ * A host needing a different shape still drops to `<Transcript>` and keeps
+ * every behaviour; this is the default, not the only door.
+ */
+export function ChatTranscript({
+  footer,
+  header,
+  empty: hostEmpty,
+  className,
+}: ChatTranscriptProps) {
+  const copy = useChatCopy().transcript;
+  const hasSuggestions = useHasSuggestions();
+  // A FALLBACK, not a caption. Starter rows above the composer already say the
+  // room is empty and name what to do, so the line only earns its place when
+  // there are none — a room with no suggestion capability, or one whose filters
+  // excluded everything. `null` rather than an empty node: the primitive falls
+  // back to rendering the transcript, not a blank box.
+  //
+  // A host node wins over both. It is checked for `undefined` rather than
+  // truthiness because a host that HAS the facts and finds nothing to say
+  // returns null, and that must fall through to the default line rather than
+  // paint a blank pane.
+  //
+  // Centred in the pane rather than set at the top-left. A single muted line
+  // pinned to a corner of an otherwise empty window reads as a layout that
+  // failed, not as an answer; the sentence is all this state has, so it stands
+  // where the eye already is. `min-h-full` and not `h-full`: the box must be
+  // free to grow with a translation that wraps.
+  const fallback = hasSuggestions ? null : (
+    <div className="flex min-h-full items-center justify-center p-8">
+      <p className="text-muted-foreground text-center text-sm text-balance">{copy.empty}</p>
+    </div>
+  );
+  const empty = hostEmpty === undefined ? fallback : hostEmpty;
+
+  // The announcer takes a fixed pair. Built here rather than inline in JSX so
+  // the object identity is stable per render pass, matching rule 5.
+  const announce = { streaming: copy.announceStreaming, complete: copy.announceComplete };
+
+  return (
+    <Transcript
+      /*
+        The SCROLLER spans the pane; the reading column caps its CONTENTS.
+        Capping the scroller itself would pull the scrollbar into the middle of
+        the window, away from the edge where a pointer expects it.
+
+        `chat-surface` carries the type scale. The width is `chat-column`, and
+        it belongs on the CONTENT wrapper inside — the primitive puts it there,
+        because the rule caps direct children and the rows are that element's
+        children. Here it would cap the wrapper alone and cost nothing.
+
+        `pb-10`: without it the last line ends a few pixels above the composer
+        and the two read as one surface. On the SCROLLER, not the last row — a
+        margin there is eaten by the sticky-bottom write.
+      */
+      className={`chat-surface min-h-0 ${className ?? ""}`}
+      empty={empty}
+      label={copy.log}
+      announce={announce}
+      // Shown only while scrolled away — the transcript owns that gate, so this
+      // never decides its own visibility.
+      jumpToLatest={({ onClick, missed }) => (
+        <JumpToLatest
+          onClick={onClick}
+          missed={missed}
+          label={copy.jumpToLatest}
+          icon={<ArrowDown className="size-4" aria-hidden />}
+        />
+      )}
+      // The answer will land here, so the promise of one belongs here too — not
+      // on the Stop button in the far corner, which is otherwise the only
+      // evidence a sent turn produced.
+      //
+      // It spans the WHOLE turn. While `waiting` it carries the label and the
+      // elapsed counter, because nothing else is on screen to explain the pause;
+      // once text is `working` the answer speaks for itself, so the row drops to
+      // the mark alone and trails the reply instead of captioning it.
+      pending={(activity) =>
+        activity === "waiting" ? (
+          <PendingIndicator
+            // Body size, not `text-sm`. This line stands exactly where the reply
+            // will appear, so a smaller one announces the answer in a different
+            // voice from the answer — and Tailwind's fixed 14px ignores the chat
+            // scale entirely, so it drifted further the moment the body grew.
+            className="text-muted-foreground flex items-center gap-2 py-3 text-[length:var(--chat-text)]"
+            label={copy.thinking}
+            elapsed={(seconds) => fill(copy.thinkingElapsed, { seconds })}
+          />
+        ) : (
+          <div className="text-muted-foreground py-1">
+            <TurnMark state="working" />
+          </div>
+        )
+      }
+    >
+      {/*
+        The styled row, not the headless `<Message>`: it carries the bubble
+        decision — user turns get one, replies stay open text — and declares the
+        role once so descendants read it through `group-[.is-user]:` instead of
+        taking a `from` prop each.
+      */}
+      {/* No vertical padding: the transcript's own `gap` is the one rhythm
+          between messages. Padding here would add to it unevenly, since a row's
+          height already varies with the optional speaker line. */}
+      {(id) => <ChatMessageView id={id} footer={footer} header={header} />}
+    </Transcript>
+  );
+}

package/src/ui/chat.tsx

@@ -0,0 +1,197 @@
+import { useEffect, useRef, type ReactNode } from "react";
+
+import type { ChatAdapter } from "../core/adapter";
+import type { ChatCapabilities } from "../core/capabilities";
+import type { ChatMessage } from "../core/parts";
+import { ChatProvider, useChatStore } from "../store";
+import { PartRegistryProvider, type PartRegistry } from "../primitives";
+import { ChatComposer } from "./chat-composer";
+import { ChatTranscript } from "./chat-transcript";
+
+/**
+ * The packaged chat.
+ *
+ * SEVEN props, and that number is the whole design. The predecessor reached 83,
+ * each documented "omit ⇒ feature off", which produced a configuration space no
+ * one could enumerate and bugs that lived in untested combinations. Here a
+ * feature arrives as a capability, a part renderer, or a slot — never as a
+ * prop, so the count does not move as the product grows
+ * (`@rules/architecture.md`).
+ *
+ * `<Chat>` is a convenience, not the API. A host that needs a different layout
+ * drops to `<ChatProvider>` plus primitives and keeps every behaviour; that
+ * escape hatch is what keeps this component from accreting props for layouts it
+ * was never meant to cover.
+ */
+interface ChatBase {
+  readonly adapter: ChatAdapter;
+  /** Present ⇒ the feature exists. There is no boolean to contradict it. */
+  readonly capabilities?: ChatCapabilities;
+  /** `part.type` → renderer. Absent types render nothing rather than crashing. */
+  readonly renderers?: PartRegistry;
+  /** Which conversation this is, and the turns it opens with. */
+  readonly conversation?: ChatConversation;
+  /** Named insertion points: `header`, `toolbarEnd`, `footer`, `messageFooter`. */
+  readonly slots?: ChatSlots;
+  readonly className?: string;
+}
+
+/**
+ * Seven props, counted honestly — the budget test reads this file.
+ *
+ * `body` stays ONE prop rather than a `children` beside a boolean: the packaged
+ * layout and a host's own composition are mutually exclusive, so they were
+ * never two decisions. One prop, one union, both mistakes unrepresentable.
+ */
+export interface ChatProps extends ChatBase {
+  readonly body: ChatBody;
+}
+
+/**
+ * The conversation on screen: which room, and the turns it opens with.
+ *
+ * ONE prop rather than `history` beside a `room`, because they are one
+ * decision. A host never changes the room without changing the turns, and the
+ * two arriving separately is what made "the conversation changed" a thing the
+ * store had to INFER from a new array identity — an inference that covered the
+ * transcript and silently missed the rest of the room's state.
+ *
+ * `id` is what the store compares. Omit it and the seam behaves exactly as the
+ * bare history array did: a new array reseeds the transcript and nothing else.
+ * Supply it and a room change also clears what belongs to the room it left.
+ */
+export interface ChatConversation {
+  /**
+   * Stable identity of the room. Any spelling the host likes, as long as two
+   * different rooms never share one — it is compared, never parsed.
+   */
+  readonly id?: string;
+  /** Prior turns to seed. `undefined` = not loaded yet, `[]` = empty room. */
+  readonly history?: readonly ChatMessage[];
+}
+
+export interface ChatSlots {
+  readonly header?: ReactNode;
+  readonly toolbarEnd?: ReactNode;
+  readonly footer?: ReactNode;
+  /**
+   * The per-message action row. A slot, not a label: WHICH actions exist is the
+   * host's inventory, and a flag per action could never express one the package
+   * has not heard of.
+   */
+  readonly messageFooter?: (message: ChatMessage) => ReactNode;
+}
+
+const noRenderers: PartRegistry = {};
+
+export function Chat({
+  adapter,
+  capabilities,
+  renderers = noRenderers,
+  conversation,
+  slots,
+  className,
+  body,
+}: ChatProps) {
+  return (
+    <ChatProvider adapter={adapter} capabilities={capabilities}>
+      <PartRegistryProvider renderers={renderers}>
+        <ChatLayout
+          conversation={conversation}
+          slots={slots}
+          className={className}
+          {...body}
+        />
+      </PartRegistryProvider>
+    </ChatProvider>
+  );
+}
+
+/**
+ * What fills the chat: the packaged layout, or the host's own composition.
+ *
+ * `packaged` needs no payload — the copy comes from the package's own
+ * dictionary, so there is nothing left for a host to supply.
+ */
+export type ChatBody =
+  | { readonly kind: "packaged" }
+  | { readonly kind: "custom"; readonly children: ReactNode };
+
+type ChatLayoutProps = {
+  readonly conversation?: ChatConversation;
+  readonly slots?: ChatSlots;
+  readonly className?: string;
+} & ChatBody;
+
+/**
+ * Inside the provider, because seeding needs the store.
+ *
+ * A custom body REPLACES the default rather than adding to it: a host passing
+ * its own composition wants exactly that, and merging the two would make every
+ * custom layout start by hiding parts of the default one.
+ */
+function ChatLayout({ conversation, slots, className, ...body }: ChatLayoutProps) {
+  useConversation(conversation);
+
+  return (
+    // `relative` is stated here rather than left to the host's `className`: the
+    // surfaces that position against this pane are this component's own
+    // children, so a host that forgot it would have them resolve against the
+    // viewport and cover the whole page.
+    <div className={`relative ${className ?? ""}`}>
+      {slots?.header}
+      {body.kind === "custom" ? (
+        body.children
+      ) : (
+        <>
+          <ChatTranscript footer={slots?.messageFooter} />
+          <ChatComposer toolbarEnd={slots?.toolbarEnd} />
+        </>
+      )}
+      {slots?.footer}
+    </div>
+  );
+}
+
+/**
+ * Seed the transcript, and leave the previous room behind when the room changes.
+ *
+ * Seeding is keyed on array identity, not contents: `load` replaces the
+ * transcript wholesale, so running it on every render would discard a live turn.
+ * A host that appends to its history array gets one reload, which is the
+ * intended behaviour.
+ *
+ * The ROOM change is a separate signal and does more, because `load` only ever
+ * replaced the transcript. A room also owns its queued prompts and its in-flight
+ * turn, and both used to survive on the host's mount — which is why hosts
+ * destroyed the whole chat on every switch. Without this reset, dropping that
+ * remount would carry one room's "thinking" indicator and another room's queued
+ * text into the conversation the user just opened.
+ *
+ * Ordering is load-bearing: the reset runs BEFORE the seed, in one effect rather
+ * than two. Two effects would fire in declaration order on the first render of a
+ * new room and blank the transcript the seed had just placed.
+ */
+function useConversation(conversation: ChatConversation | undefined): void {
+  const store = useChatStore();
+  const history = conversation?.history;
+  const roomId = conversation?.id;
+  // The room this store is currently showing. A ref, not state: nothing renders
+  // from it, and it must be readable and writable inside the same effect pass.
+  const shownRoom = useRef(roomId);
+
+  useEffect(() => {
+    if (shownRoom.current !== roomId) {
+      shownRoom.current = roomId;
+      // Aborts an in-flight turn and drops the queue. A turn belongs to the room
+      // it was sent to; abandoning it silently is what already happened when the
+      // host remounted, so this preserves the behaviour rather than changing it.
+      store.leaveRoom();
+    }
+    // `undefined` is "not loaded yet", and the store must be told: a transcript
+    // that only knows "no messages" shows the empty state during the fetch, so
+    // a room with 90 replies opened on an empty state for ~100ms.
+    store.setHistoryLoaded(history !== undefined);
+    if (history !== undefined) store.load(history);
+  }, [history, roomId, store]);
+}

package/src/ui/collapsible-body.tsx

@@ -0,0 +1,180 @@
+import { useCallback, useId, useRef, useState, type ReactNode } from "react";
+
+import { cn } from "@djangocfg/ui-core/lib";
+
+import { useChatCopy } from "../i18n";
+import { useOverflows } from "../primitives/use-overflows";
+
+/**
+ * Rows of body text a turn may occupy before it is offered a collapse.
+ *
+ * ROWS, because the question is how much SCREEN a turn costs — and that is a
+ * height, not a character count. `useOverflows` measures the rendered element
+ * (`scrollHeight > clientHeight`), so an image, a table or a code fence is
+ * counted by what it actually occupies rather than by how much text it carries.
+ *
+ * 10 is measured, not guessed. Against a real 100-turn transcript: the median
+ * turn is ONE row, the 90th percentile is 9, and the tallest is 186. At the
+ * original 18 exactly one turn in a hundred was ever offered a collapse, which
+ * reads as the feature being broken rather than as messages being short. At 10,
+ * eight are — every genuinely long answer, and no ordinary reply.
+ *
+ * Below 8 the numbers stop moving (8 and 6 both collapse 11), so there is a gap
+ * in real message lengths and nothing to buy by going lower.
+ */
+const DEFAULT_MAX_ROWS = 10;
+
+export interface CollapseState {
+  /** Is the height budget being enforced right now? */
+  readonly clamped: boolean;
+  /** Is there a control to open or close the turn? */
+  readonly showTrigger: boolean;
+}
+
+/**
+ * The clamp/trigger policy, as a pure function.
+ *
+ * Split out because this package's tests run without a DOM — `scrollHeight` is
+ * not merely absent, it is meaningless here — so the DOM READ is verified in a
+ * browser and the DECISION is verified as data. The same split the transcript's
+ * select-all rule already uses, for the same reason.
+ */
+export function collapseState(
+  streaming: boolean,
+  expanded: boolean,
+  overflows: boolean,
+  mayCollapse = true,
+): CollapseState {
+  // Ineligible wins over everything: the newest turn is shown whole, with no
+  // control, however tall it is. Inside the function rather than `&&`-ed onto
+  // its result so the rule is one decision in one place — and so a mutation
+  // that drops it fails a test instead of surviving in a caller.
+  if (!mayCollapse) return { clamped: false, showTrigger: false };
+  // Streaming wins over the rest. A reply must not fold while it is still
+  // arriving, and its height changes on every chunk, so a measurement taken
+  // mid-stream would flip the control on and off as the answer grows.
+  if (streaming) return { clamped: false, showTrigger: false };
+  return { clamped: !expanded, showTrigger: overflows };
+}
+
+
+/** A turn's collapse, owned by the row so a body and a toolbar can share it. */
+export interface Collapse extends CollapseState {
+  readonly bodyRef: React.RefObject<HTMLDivElement | null>;
+  readonly bodyId: string;
+  readonly expanded: boolean;
+  readonly toggle: () => void;
+  readonly label: string;
+}
+
+/**
+ * Own one turn's collapse.
+ *
+ * The state lives HERE, in the row, rather than inside the body — because the
+ * body and the toolbar are siblings inside the frame, and a control cannot be
+ * handed upward from one to the other. The row is their nearest common owner.
+ *
+ * That placement is also the fix for where the control sits. Rendered under the
+ * body it lands ON the clipped line: the reader sees a half-cut row of text
+ * with a label overlapping it. In the toolbar it joins the actions that already
+ * belong to the turn.
+ *
+ * `collapsible` is FROZEN at mount, which is what makes a positional rule safe.
+ * The newest reply is left open — nothing below it to scroll past, and folding
+ * the one thing the reader is waiting for is the opposite of the point. But a
+ * POSITION changes: send another message and the previously-last turn is no
+ * longer last. Read live, that would collapse the answer someone is mid-way
+ * through. `useState`'s initialiser runs once, so a turn keeps what it was born
+ * with — a later `true` never folds it, a later `false` never opens it.
+ */
+export function useCollapse(
+  streaming: boolean,
+  revision: unknown,
+  collapsible = true,
+): Collapse {
+  const copy = useChatCopy().message;
+  const bodyRef = useRef<HTMLDivElement>(null);
+  const [expanded, setExpanded] = useState(false);
+  const [mayCollapse] = useState(collapsible);
+  const bodyId = useId();
+
+  const overflows = useOverflows(bodyRef, expanded, revision);
+  const toggle = useCallback(() => {
+    setExpanded((open) => !open);
+  }, []);
+
+  const state = collapseState(streaming, expanded, overflows, mayCollapse);
+  return {
+    bodyRef,
+    bodyId,
+    expanded,
+    toggle,
+    ...state,
+    label: expanded ? copy.showLess : copy.showMore,
+  };
+}
+
+/**
+ * Bound a long turn to a readable height.
+ *
+ * Two properties are load-bearing and easy to lose in a refactor.
+ *
+ * Collapsed content is CLIPPED, never unmounted. The transcript deliberately
+ * runs without virtualization partly to keep find-in-page and select-all whole,
+ * and removing text from the DOM to save height breaks both in exactly the way
+ * that decision avoids.
+ *
+ * The trigger appears only when the content genuinely overflows — the height
+ * budget is a fact about this turn, not a decoration, and "show more" under a
+ * short message teases a disclosure that reveals nothing.
+ */
+export function CollapsibleBody({
+  collapse,
+  maxRows = DEFAULT_MAX_ROWS,
+  className,
+  children,
+}: {
+  readonly collapse: Collapse;
+  readonly maxRows?: number;
+  readonly className?: string;
+  readonly children: ReactNode;
+}) {
+  return (
+    <div
+      id={collapse.bodyId}
+      ref={collapse.bodyRef}
+      className={cn("min-w-0", collapse.clamped && "overflow-hidden", className)}
+      // The budget is a HEIGHT in rows, because rows are what the reader
+      // experiences. Same two tokens the composer sizes its controls from, so a
+      // host that scales the chat scales this with it.
+      //
+      // No gradient fade over the cut: a fade must know the colour behind it,
+      // and there are two — the user's bubble on `bg-secondary`, the reply on
+      // the page — in both themes. A wrong one reads as a seam across the last
+      // visible line, and the label already says the turn continues.
+      style={
+        collapse.clamped
+          ? { maxHeight: `calc(${maxRows} * var(--chat-text, 1rem) * var(--chat-leading, 1.65))` }
+          : undefined
+      }
+    >
+      {children}
+    </div>
+  );
+}
+
+/** The control. Placed by the row, in the toolbar beside the turn's actions. */
+export function CollapseTrigger({ collapse }: { readonly collapse: Collapse }) {
+  if (!collapse.showTrigger) return null;
+  return (
+    <button
+      type="button"
+      onClick={collapse.toggle}
+      aria-expanded={collapse.expanded}
+      aria-controls={collapse.bodyId}
+      className="text-muted-foreground hover:text-foreground cursor-pointer text-[length:var(--chat-text-small)] underline-offset-4 hover:underline"
+    >
+      {collapse.label}
+    </button>
+  );
+}