@gemboss/ui 0.21.0 → 0.30.2

package/src/assistant/chat.tsx

@@ -0,0 +1,871 @@
+"use client";
+
+/**
+ * The assistant's CHAT BODY as components — @gemboss/ui 0.29.0 (Chris 08/10/2026: "đồng bộ hết giao diện của AI
+ * assistant… mọi service có panel này đồng bộ style + code dùng gemboss ui").
+ *
+ * Until 0.29.0 the package drew the FRAME (AssistantHost), the conversation list (SessionRail) and the engine picker, and
+ * shipped the body's CSS (chat.css, chat-composer.css), but no component drew the body: every surface wrote the bubbles,
+ * the steps, the starters and the composer by hand on those classes, and each wrote a markdown renderer of its own. Five
+ * surfaces, five composers (a form or a div, rows 1 or 2, "↑" or "Send", with or without an IME guard), three ways to
+ * show a step running. These are the pieces, taken from the two that had them right (see README "The chat body"):
+ *
+ *   from the admin (apps/admin GemChat): the composer (one bordered shell, one action slot that is send or stop, the text
+ *     box that grows to 84px, the toolbar that says less as it narrows: `data-density`), the markdown, the step rows
+ *     that print and stop (one heartbeat moves, not one spinner per row), the working heartbeat with its clock;
+ *   from partner-radar: the composer as a DIV (the engine popup lives inside it and has a form of its own), the IME guard
+ *     on Enter, starters that wrap, the line under an answer (Copy · engine · seconds · cost), the error that says how to
+ *     fix it (a sentence, the command, Copy, the original error folded).
+ *
+ * The surface hands in data and actions (messages, send, stop, the engine picker element) and keeps its behaviour:
+ * streaming, the bridge, sessions. `AssistantChat` puts the pieces together; each piece is exported for a surface that
+ * needs its own arrangement (a proposal card under an answer, a picker of its own beside the composer).
+ */
+import "../chat.css";
+import "../chat-composer.css";
+import "../assistant-chat.css";
+import "../assistant-engine.css"; // BridgeNotice and the engine chip's density rules (engine.tsx brings it too)
+import React, {
+  createContext, Fragment, useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState,
+  type ClipboardEventHandler, type KeyboardEventHandler, type ReactNode, type Ref, type RefObject,
+} from "react";
+import { BridgeNotice, copyText } from "./engine";
+import { EngineMark } from "./engine-mark";
+import { isEngineMarkId } from "./engine-mark-art";
+import { CODE_FOLD_LINES, parseBlocks, parseInline, type Block, type ImageHost } from "./chat-markdown";
+
+const cx = (...p: Array<string | false | null | undefined>) => p.filter(Boolean).join(" ");
+const useBeforePaint = typeof window === "undefined" ? useEffect : useLayoutEffect;
+
+/** Every word the chat says. English, like every surface's chrome (Chris 03/10/2026). */
+export interface ChatLabels {
+  thread: string; message: string; send: string; stop: string; attach: string;
+  copy: string; copied: string; copyCommand: string; originalError: string; stopped: string;
+  steps: string; thought: string; thinking: string; working: string; showLess: string; showAll: string; openImage: string;
+}
+export const CHAT_EN: ChatLabels = {
+  thread: "Conversation", message: "Message", send: "Send", stop: "Stop", attach: "Attach a file",
+  copy: "Copy", copied: "Copied", copyCommand: "Copy command", originalError: "Original error", stopped: "Stopped",
+  steps: "What it is doing", thought: "Thought", thinking: "Thinking", working: "Working", showLess: "Show less", showAll: "Show all {n} lines",
+  openImage: "Open image",
+};
+const LabelsContext = createContext<ChatLabels>(CHAT_EN);
+const useLabels = () => useContext(LabelsContext);
+
+// ── The thread ─────────────────────────────────────────────────────────────────────────────────────────────────────────
+
+/**
+ * The message list: `.gemboss-ec-scroll`, a `role="log"`, and it FOLLOWS the end while the reader is at the end (within
+ * 24px). Scrolled up to read, it stays put while the answer streams below. `aria-busy` while a turn runs, so a screen
+ * reader reads the answer once it is whole instead of token by token.
+ */
+export function ChatThread({ children, busy, label, className, scrollRef, follow = true, pinKey }: {
+  children?: ReactNode;
+  busy?: boolean;
+  label?: string;
+  className?: string;
+  scrollRef?: Ref<HTMLDivElement>;
+  /** Keep the end in view while the reader is at the end (default). */
+  follow?: boolean;
+  /** Change it to go back to the end and follow again (the user sent a message; another conversation was opened). */
+  pinKey?: unknown;
+}) {
+  const L = useLabels();
+  const own = useRef<HTMLDivElement | null>(null);
+  const pinned = useRef(true);
+  const toEndRef = useRef<() => void>(() => {});
+  const setRef = useCallback((el: HTMLDivElement | null) => {
+    own.current = el;
+    if (typeof scrollRef === "function") scrollRef(el);
+    else if (scrollRef) (scrollRef as { current: HTMLDivElement | null }).current = el;
+  }, [scrollRef]);
+  useEffect(() => {
+    const el = own.current;
+    if (!el || !follow) return undefined;
+    let frame = 0;
+    let writtenTop: number | null = null;
+    const writeEnd = () => { el.scrollTop = el.scrollHeight; writtenTop = el.scrollTop; };
+    // The reader's own move up (wheel, finger, keys) unpins AT ONCE: a 2px trackpad step is still "at the end" by distance,
+    // and the next streamed token would pull it back (review #3910). Scrolling back to the end pins again.
+    let upAt = 0, goingUp = false;
+    const up = () => { upAt = performance.now(); goingUp = true; pinned.current = false; };
+    const down = () => { goingUp = false; };
+    const dist = () => el.scrollHeight - el.clientHeight - el.scrollTop;
+    const toEnd = () => {
+      if (!pinned.current || frame) return;
+      frame = requestAnimationFrame(() => { frame = 0; if (pinned.current) writeEnd(); });
+    };
+    toEndRef.current = () => { pinned.current = true; writeEnd(); };
+    const onScroll = () => {
+      const d = dist();
+      // A scroll from our own write can arrive after new content grows the gap. It is not a reader moving up.
+      const ownWrite = writtenTop !== null && el.scrollTop === writtenTop;
+      writtenTop = null;
+      if (d > 24 && !ownWrite) pinned.current = false;
+      // Back at the end pins again, at once when the reader was moving down; after a move UP, only once it has settled
+      // (the scroll that a 2px step up produces is itself within 4px of the end).
+      else if (d <= 4 && (!goingUp || performance.now() - upAt > 400)) pinned.current = true;
+    };
+    const onWheel = (e: WheelEvent) => { if (e.deltaY < 0) up(); else if (e.deltaY > 0) down(); };
+    let touchY = 0;
+    const onTouchStart = (e: TouchEvent) => { touchY = e.touches[0]?.clientY ?? 0; };
+    const onTouchMove = (e: TouchEvent) => { const y = e.touches[0]?.clientY ?? 0; if (y > touchY + 2) up(); else if (y < touchY - 2) down(); };
+    const onKey = (e: KeyboardEvent) => { if (["ArrowUp", "PageUp", "Home"].includes(e.key)) up(); else if (["ArrowDown", "PageDown", "End"].includes(e.key)) down(); };
+    el.addEventListener("scroll", onScroll, { passive: true });
+    el.addEventListener("wheel", onWheel, { passive: true });
+    el.addEventListener("touchstart", onTouchStart, { passive: true });
+    el.addEventListener("touchmove", onTouchMove, { passive: true });
+    el.addEventListener("keydown", onKey);
+    // New content, streamed text, a picture that finished loading (it grows the list without a mutation), a resize.
+    const mo = new MutationObserver(toEnd);
+    mo.observe(el, { childList: true, subtree: true, characterData: true });
+    el.addEventListener("load", toEnd, true);
+    const ro = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(toEnd);
+    ro?.observe(el);
+    writeEnd();
+    return () => {
+      cancelAnimationFrame(frame);
+      el.removeEventListener("scroll", onScroll);
+      el.removeEventListener("wheel", onWheel);
+      el.removeEventListener("touchstart", onTouchStart);
+      el.removeEventListener("touchmove", onTouchMove);
+      el.removeEventListener("keydown", onKey);
+      el.removeEventListener("load", toEnd, true);
+      mo.disconnect();
+      ro?.disconnect();
+    };
+  }, [follow]);
+  // Back to the end when the surface says so (a send, another conversation), whatever the reader did before.
+  const first = useRef(true);
+  useEffect(() => {
+    if (first.current) { first.current = false; return; }
+    toEndRef.current();
+  }, [pinKey]);
+  return (
+    <div ref={setRef} className={cx("gemboss-ec-scroll", className)} role="log" aria-label={label ?? L.thread} aria-busy={busy || undefined}>
+      {children}
+    </div>
+  );
+}
+
+/** One message: the user's (right, filled) or the assistant's (left, outlined), and everything under it. */
+export function ChatMessage({ role, children, className, lang }: { role: "user" | "assistant"; children?: ReactNode; className?: string; lang?: string }) {
+  return <div className={cx("gemboss-ec-msg", role, className)} lang={lang}>{children}</div>;
+}
+
+/** The bubble. Text keeps its line breaks (`pre-wrap`); markdown goes in through `ChatMarkdown`. */
+export function ChatBubble({ children, streaming, className, lang }: { children?: ReactNode; streaming?: boolean; className?: string; lang?: string }) {
+  return (
+    <div className={cx("gemboss-ec-bubble", className)} lang={lang}>
+      {children}
+      {streaming ? <span className="gemboss-ec-cursor" aria-hidden="true" /> : null}
+    </div>
+  );
+}
+
+// ── Markdown ───────────────────────────────────────────────────────────────────────────────────────────────────────────
+
+export interface ChatMarkdownProps {
+  text: string;
+  /** An in-app link (`/partners/12`): called instead of a page load. */
+  onNavigate?: (href: string) => void;
+  /** More hosts whose pictures may be drawn (added to the fleet's). */
+  imageHosts?: readonly ImageHost[];
+  /** A link scheme of the surface's own (`customer:12`): `ownLink` says which, `renderLink` draws it. */
+  ownLink?: (href: string) => boolean;
+  renderLink?: (href: string, label: string) => ReactNode;
+}
+
+function Inline({ text, p }: { text: string; p: ChatMarkdownProps }) {
+  const L = useLabels();
+  const toks = parseInline(text, { imageHosts: p.imageHosts, ownLink: p.ownLink });
+  return (
+    <>
+      {toks.map((tok, key) => {
+        switch (tok.t) {
+          case "text": return <Fragment key={key}>{tok.text}</Fragment>;
+          case "code": return <code key={key} className="gemboss-md-code">{tok.text}</code>;
+          case "bold": return <strong key={key}>{tok.text}</strong>;
+          case "italic": return <em key={key}>{tok.text}</em>;
+          case "link": {
+            if (p.ownLink?.(tok.href) && p.renderLink) return <Fragment key={key}>{p.renderLink(tok.href, tok.label)}</Fragment>;
+            const { href, internal, label } = tok;
+            return (
+              <a key={key} className="gemboss-ec-md-link" href={href}
+                target={internal ? undefined : "_blank"} rel={internal ? undefined : "noopener noreferrer"}
+                onClick={(e) => { if (internal && p.onNavigate && !e.metaKey && !e.ctrlKey && !e.shiftKey) { e.preventDefault(); p.onNavigate(href); } }}>
+                {label}
+              </a>
+            );
+          }
+          case "image":
+            return (
+              <a key={key} className="gemboss-md-imglink" href={tok.src} target="_blank" rel="noopener noreferrer"
+                {...(tok.alt ? {} : { "aria-label": L.openImage })}>
+                <img className="gemboss-md-img" src={tok.src} alt={tok.alt} loading="lazy" referrerPolicy="no-referrer" />
+              </a>
+            );
+          default: return null;
+        }
+      })}
+    </>
+  );
+}
+
+function Lines({ lines, p }: { lines: string[]; p: ChatMarkdownProps }) {
+  return <>{lines.map((l, j) => <Fragment key={j}><Inline text={l} p={p} />{j < lines.length - 1 ? <br /> : null}</Fragment>)}</>;
+}
+
+function CodeBlock({ lang, body }: { lang: string; body: string }) {
+  const L = useLabels();
+  const lines = body.split("\n");
+  const long = lines.length > CODE_FOLD_LINES;
+  const [open, setOpen] = useState(false);
+  return (
+    <div className="gemboss-md-codeblock">
+      {lang ? <span className="gemboss-md-codelang">{lang}</span> : null}
+      <pre><code>{long && !open ? lines.slice(0, CODE_FOLD_LINES).join("\n") : body}</code></pre>
+      {long ? (
+        <button type="button" className="gemboss-md-codemore" aria-expanded={open} onClick={() => setOpen((v) => !v)}>
+          {open ? L.showLess : L.showAll.replace("{n}", String(lines.length))}
+        </button>
+      ) : null}
+    </div>
+  );
+}
+
+// Headings are demoted one level (h1 → h3): the bubble sits under the page's own headings. The size keeps the hierarchy.
+const HEADING_TAG = { 1: "h3", 2: "h4", 3: "h5" } as const;
+const HEADING_CLASS = { 1: "gemboss-md-h gemboss-md-h1", 2: "gemboss-md-h gemboss-md-h2", 3: "gemboss-md-h gemboss-md-h3" } as const;
+
+function BlockView({ b, p }: { b: Block; p: ChatMarkdownProps }) {
+  switch (b.t) {
+    case "heading": { const H = HEADING_TAG[b.level]; return <H className={HEADING_CLASS[b.level]}><Inline text={b.text} p={p} /></H>; }
+    case "code": return <CodeBlock lang={b.lang} body={b.body} />;
+    case "table":
+      return (
+        <div className="gemboss-md-tablewrap">
+          <table className="gemboss-md-table">
+            <thead><tr>{b.head.map((h, j) => <th key={j}><Inline text={h} p={p} /></th>)}</tr></thead>
+            <tbody>{b.rows.map((r, ri) => <tr key={ri}>{b.head.map((_, ci) => <td key={ci}><Inline text={r[ci] ?? ""} p={p} /></td>)}</tr>)}</tbody>
+          </table>
+        </div>
+      );
+    case "list": {
+      const items = b.items.map((it, j) => <li key={j}><Inline text={it} p={p} /></li>);
+      return b.ordered
+        ? <ol className="gemboss-md-list" start={b.start}>{items}</ol>
+        : <ul className="gemboss-md-list">{items}</ul>;
+    }
+    case "quote": return <blockquote className="gemboss-md-quote"><Lines lines={b.lines} p={p} /></blockquote>;
+    case "rule": return <hr className="gemboss-md-rule" />;
+    default: return <p className="gemboss-md-p"><Lines lines={b.lines} p={p} /></p>;
+  }
+}
+
+/**
+ * What a model writes, drawn with the `gemboss-md-*` classes. No raw HTML path: every node is built. Memoised on the text
+ * (a streaming transcript re-renders on every frame).
+ */
+export function ChatMarkdown(props: ChatMarkdownProps) {
+  const blocks = useMemo(() => parseBlocks(props.text), [props.text]);
+  return <>{blocks.map((b, i) => <BlockView key={i} b={b} p={props} />)}</>;
+}
+
+// ── Steps (narration) ──────────────────────────────────────────────────────────────────────────────────────────────────
+
+export interface ChatStep {
+  id: string | number;
+  /** step (default): a tool or an action, in words · thinking: the model's reasoning · trace: a raw tool call, its
+   *  payload folded · steer: a line the user typed into the running turn. */
+  kind?: "step" | "thinking" | "trace" | "steer";
+  /** running · ok · failed. Rows print and STOP: nothing on a row spins (one heartbeat, `ChatPending`, moves). */
+  state?: "running" | "ok" | "failed";
+  /** What it did, in words ("Search partners"); for a trace the call; for thinking the text so far. */
+  label: ReactNode;
+  /** What it did it to, muted after the label ("Wiser"). */
+  target?: ReactNode;
+  /** The trace's payload (folded), or a finished thought. */
+  detail?: string;
+  /** Why it failed: the row's hover text. */
+  error?: string;
+  /** This row stands for the turn: the engine's mark in the dot's place. */
+  engine?: string;
+}
+
+const STEP_CLASS = { running: "gemboss-narr-row running", ok: "gemboss-narr-row ok", failed: "gemboss-narr-row failed" } as const;
+const THINK_CLASS = { running: "gemboss-narr-row thinking running", ok: "gemboss-narr-row thinking ok", failed: "gemboss-narr-row thinking failed" } as const;
+const TRACE_CLASS = { running: "gemboss-narr-row trace running", ok: "gemboss-narr-row trace ok", failed: "gemboss-narr-row trace failed" } as const;
+const STEER_CLASS = { running: "gemboss-narr-row steer running", ok: "gemboss-narr-row steer ok", failed: "gemboss-narr-row steer failed" } as const;
+
+/** What the assistant did on the way to its answer, one row per step. */
+export function ChatSteps({ steps, label }: { steps: readonly ChatStep[]; label?: string }) {
+  const L = useLabels();
+  if (!steps.length) return null;
+  return (
+    <ul className="gemboss-narr" aria-label={label ?? L.steps}>
+      {steps.map((s) => {
+        const state = s.state ?? "ok";
+        if (s.kind === "thinking") {
+          return (
+            <li key={s.id} className={THINK_CLASS[state]}>
+              <span className="gemboss-narr-dot" aria-hidden="true">✳</span>
+              {state === "running" || !s.detail ? (
+                <span className="gemboss-narr-text gemboss-narr-thinking-live">{s.label || L.thinking}</span>
+              ) : (
+                <details className="gemboss-narr-thinking">
+                  <summary>{s.label || L.thought}</summary>
+                  <div className="gemboss-narr-thinking-body">{s.detail}</div>
+                </details>
+              )}
+            </li>
+          );
+        }
+        if (s.kind === "steer") {
+          return (
+            <li key={s.id} className={STEER_CLASS[state]}>
+              <span className="gemboss-narr-dot" aria-hidden="true">❯</span>
+              <span className="gemboss-narr-text gemboss-narr-steer">{s.label}</span>
+            </li>
+          );
+        }
+        if (s.kind === "trace") {
+          return (
+            <li key={s.id} className={TRACE_CLASS[state]} title={s.error || undefined}>
+              <span className="gemboss-narr-dot" aria-hidden="true">{state === "failed" ? "✕" : "⏺"}</span>
+              {s.detail ? (
+                <details className="gemboss-narr-trace">
+                  <summary><code>{s.label}</code></summary>
+                  <div className="gemboss-narr-trace-body"><code>{s.detail}</code></div>
+                </details>
+              ) : <code className="gemboss-narr-text gemboss-narr-trace-call">{s.label}</code>}
+            </li>
+          );
+        }
+        return (
+          <li key={s.id} className={STEP_CLASS[state]} title={s.error || undefined}>
+            {s.engine && isEngineMarkId(s.engine)
+              ? <span className="gemboss-narr-dot gemboss-narr-dot-engine"><EngineMark engine={s.engine} /></span>
+              : <span className="gemboss-narr-dot" aria-hidden="true">{state === "ok" ? "✓" : state === "failed" ? "✕" : "·"}</span>}
+            <span className="gemboss-narr-text">{s.label}{s.target ? <span className="gb-chat-target"> {s.target}</span> : null}</span>
+          </li>
+        );
+      })}
+    </ul>
+  );
+}
+
+// ── Working, the heartbeat ─────────────────────────────────────────────────────────────────────────────────────────────
+
+/**
+ * The one thing that moves while a turn runs and nothing is written yet: a pulsing ✳, a verb that changes every 2s, the
+ * seconds (and tokens, when known). For a screen reader it says its label ONCE (role="status"): the clock and the verbs
+ * are hidden from it, or it would announce every second.
+ */
+export function ChatPending({ verbs, tokens, compact, label }: { verbs?: readonly string[]; tokens?: number; compact?: boolean; label?: string }) {
+  const L = useLabels();
+  const list = verbs && verbs.length ? verbs : [L.working];
+  const [idx, setIdx] = useState(0);
+  const [elapsed, setElapsed] = useState(0);
+  useEffect(() => {
+    const t0 = performance.now();
+    const id = setInterval(() => setElapsed(Math.floor((performance.now() - t0) / 1000)), 250);
+    return () => clearInterval(id);
+  }, []);
+  useEffect(() => {
+    if (list.length <= 1) return undefined;
+    const id = setInterval(() => setIdx((i) => (i + 1) % list.length), 2000);
+    return () => clearInterval(id);
+  }, [list.length]);
+  return (
+    <div className="gemboss-ec-pending" role="status">
+      <span className="gemboss-assistant-sronly">{label ?? list[0]}</span>
+      <span className="gemboss-ec-pending-star" aria-hidden="true">✳</span>
+      {!compact ? <span className="gemboss-ec-pending-verb" key={idx} aria-hidden="true">{list[idx % list.length]}…</span> : null}
+      <span className="gemboss-ec-pending-meta" aria-hidden="true">{tokens && tokens > 0 ? `${tokens} token${tokens === 1 ? "" : "s"} · ` : ""}{elapsed}s</span>
+    </div>
+  );
+}
+
+// ── Starters, the line under an answer, errors, notes ──────────────────────────────────────────────────────────────────
+
+export interface ChatStarter {
+  /** What the button says. */
+  label: string;
+  /** What is sent (default: the label). A long prompt behind a short label. */
+  prompt?: string;
+  /** A quiet line above the label ("Example, click to fill in"). */
+  hint?: string;
+  /** Put the prompt in the composer instead of sending it (an example the user edits first). */
+  fill?: boolean;
+}
+
+/** Suggested first questions. They WRAP (a long prompt as a nowrap pill was cut in a 400px panel). */
+export function ChatStarters({ items, onPick, title }: { items: readonly ChatStarter[]; onPick: (s: ChatStarter) => void; title?: ReactNode }) {
+  if (!items.length) return null;
+  return (
+    <>
+      {title ? <p className="gb-chat-label">{title}</p> : null}
+      <div className="gemboss-ec-starters">
+        {items.map((s, i) => (
+          <button key={`${i}:${s.label}`} type="button" className="gemboss-ec-starter gb-chat-starter" onClick={() => onPick(s)}>
+            {s.hint ? <span className="gb-chat-starter-hint">{s.hint}</span> : null}
+            {s.label}
+          </button>
+        ))}
+      </div>
+    </>
+  );
+}
+
+function CopyButton({ text, label, done }: { text: string; label: string; done: string }) {
+  const [said, setSaid] = useState(false);
+  const timer = useRef<number | undefined>(undefined);
+  useEffect(() => () => window.clearTimeout(timer.current), []);
+  return (
+    <button type="button" className="ui-btn ui-btn--ghost gb-chat-copy" onClick={async () => {
+      if (!(await copyText(text))) return;
+      setSaid(true);
+      window.clearTimeout(timer.current);
+      timer.current = window.setTimeout(() => setSaid(false), 1500);
+    }}>{said ? done : label}</button>
+  );
+}
+
+/** The line under a finished answer: Copy, then what the surface wants said (engine, seconds, model, cost). */
+export function ChatMeta({ copyText: text, items }: { copyText?: string; items?: ReactNode[] }) {
+  const L = useLabels();
+  const shown = (items ?? []).filter((x) => x !== null && x !== undefined && x !== false && x !== "");
+  if (!text && !shown.length) return null;
+  return (
+    <div className="gb-chat-meta">
+      {text ? <CopyButton text={text} label={L.copy} done={L.copied} /> : null}
+      {shown.map((x, i) => <span key={i}>{x}</span>)}
+    </div>
+  );
+}
+
+/** A way out the user can take on their own machine: one sentence, and the command when there is one. */
+export interface ChatFix { text: ReactNode; command?: string }
+
+/** A turn that failed. With a `fix`: what to do, the command, Copy, and the original error folded underneath. */
+export function ChatError({ children, fix }: { children: ReactNode; fix?: ChatFix | null }) {
+  const L = useLabels();
+  if (!fix) return <p className="ui-notice ui-notice--danger gb-chat-error" role="alert">{children}</p>;
+  return (
+    <div className="ui-notice ui-notice--danger gb-chat-error" role="alert">
+      <div>{fix.text}</div>
+      {fix.command ? <code className="gb-chat-cmd">{fix.command}</code> : null}
+      {fix.command ? <div><CopyButton text={fix.command} label={L.copyCommand} done={L.copied} /></div> : null}
+      <details className="gb-chat-original"><summary>{L.originalError}</summary><span>{children}</span></details>
+    </div>
+  );
+}
+
+/** A quiet centred line in the stream ("Switched to Codex: a new conversation", "Stopped"). */
+export function ChatNote({ children }: { children: ReactNode }) {
+  return <p className="gb-chat-note">{children}</p>;
+}
+
+// ── The composer ───────────────────────────────────────────────────────────────────────────────────────────────────────
+
+/**
+ * HOW MUCH THE TOOLBAR SAYS, stepped down only as far as the room demands (the admin's rule, measured not guessed):
+ *   full "Claude Code · Opus" → compact "Claude Code" → icon (the engine's mark) → tight (a select's short label).
+ * The composer tries each step and keeps the first where no label is cut and nothing overflows.
+ */
+export type ComposerDensity = "full" | "compact" | "icon" | "tight";
+const DENSITIES: ComposerDensity[] = ["full", "compact", "icon", "tight"];
+const DensityContext = createContext<ComposerDensity>("full");
+/** For a control in `leading` that changes its TEXT, not only its CSS (a <select> with a short label). */
+export function useComposerDensity(): ComposerDensity { return useContext(DensityContext); }
+
+const LABEL_SEL = ".gemboss-ec-chiplabel, .gb-engine-chiplabel";
+const CHIP_SEL = ".gemboss-ec-chipctl, .gb-engine-chip";
+/** A label cut by its ellipsis, a chip narrower than its content, or a toolbar wider than its box: step down. */
+function crowded(box: HTMLElement): boolean {
+  const lead = box.querySelector<HTMLElement>(".gemboss-ec-toolbar-lead");
+  const bar = box.querySelector<HTMLElement>(".gemboss-ec-toolbar");
+  if (lead && lead.scrollWidth > lead.clientWidth + 1) return true;
+  if (bar && bar.scrollWidth > bar.clientWidth + 1) return true;
+  for (const l of box.querySelectorAll<HTMLElement>(LABEL_SEL)) if (l.offsetParent !== null && l.scrollWidth > l.clientWidth + 1) return true;
+  for (const c of box.querySelectorAll<HTMLElement>(CHIP_SEL)) if (c.offsetParent !== null && c.tagName !== "SELECT" && c.scrollWidth > c.clientWidth + 1) return true;
+  return false;
+}
+
+/** The paperclip every composer draws: one glyph, not 📎 in one chat and an SVG in another. */
+export function PaperclipIcon() {
+  return (
+    <svg viewBox="0 0 24 24" aria-hidden="true" focusable="false">
+      <path d="M21.4 11.1l-8.5 8.5a5.5 5.5 0 01-7.8-7.8l8.5-8.5a3.7 3.7 0 015.2 5.2l-8.5 8.5a1.8 1.8 0 01-2.6-2.6l7.8-7.8" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" />
+    </svg>
+  );
+}
+function SendIcon() {
+  return <svg viewBox="0 0 20 20" aria-hidden="true" focusable="false"><path d="M10.53 4.47a.75.75 0 0 0-1.06 0l-4.5 4.5a.75.75 0 0 0 1.06 1.06l3.22-3.22v8.69a.75.75 0 0 0 1.5 0v-8.69l3.22 3.22a.75.75 0 1 0 1.06-1.06l-4.5-4.5Z" /></svg>;
+}
+
+export interface ChatComposerProps {
+  value: string;
+  onChange: (value: string) => void;
+  /** Enter (not Shift+Enter, not mid-IME) or the send button, with text in the box. */
+  onSend: (text: string) => void;
+  /** A turn is running: the action slot is Stop when `onStop` is given (the same 44px circle, so nothing moves). */
+  busy?: boolean;
+  onStop?: () => void;
+  /** Send stays allowed while busy (a surface that queues or steers a running turn). */
+  sendWhileBusy?: boolean;
+  /** A stop is already on its way (0.30.2): Stop stays in the slot, disabled, so a second press is visibly a no-op. */
+  stopDisabled?: boolean;
+  /** Overrides whether the action may send (0.30.2): a picture attached with no words is sendable (the admin's reference
+   *  image), an upload still running is not. The text box stays editable either way; `disabled` is for the whole box. */
+  canSend?: boolean;
+  placeholder?: string;
+  /** The text box's accessible name (default "Message"). */
+  label?: string;
+  /** The chip strip: the engine picker, a mode select. Chips only (density reads it as chips). */
+  leading?: ReactNode;
+  /** Tools that are not chips: the attach button. */
+  tools?: ReactNode;
+  /** Full-width rows above the text box (a pending attachment). */
+  top?: ReactNode;
+  /** Beside the action ("2 queued"). */
+  status?: ReactNode;
+  maxLength?: number;
+  rows?: number;
+  disabled?: boolean;
+  textareaRef?: RefObject<HTMLTextAreaElement | null>;
+  onKeyDown?: KeyboardEventHandler<HTMLTextAreaElement>;
+  onPaste?: ClipboardEventHandler<HTMLTextAreaElement>;
+  className?: string;
+}
+
+/**
+ * THE MESSAGE BOX. A DIV, not a form: the engine picker's popup lives inside this row (in the top layer, but in the DOM
+ * and the React tree), and its Setup tab has a pairing form whose Enter would otherwise submit the draft (content-radar
+ * review #916). The send button keeps `type="submit"` because chat.css draws it by that; outside a form it submits nothing.
+ */
+export function ChatComposer(p: ChatComposerProps) {
+  const L = useLabels();
+  const own = useRef<HTMLTextAreaElement | null>(null);
+  const ref = p.textareaRef ?? own;
+  const boxRef = useRef<HTMLDivElement>(null);
+  const [density, setDensity] = useState<ComposerDensity>("full");
+  const [remeasure, setRemeasure] = useState(0);
+  const canSend = !p.disabled && (p.canSend ?? p.value.trim() !== "") && (!p.busy || p.sendWhileBusy || !p.onStop);
+
+  // One step per commit, before paint: the crowded frame is never seen. Terminates (four places, each pass stops or moves on).
+  useBeforePaint(() => {
+    const box = boxRef.current;
+    if (!box || box.offsetParent === null) return;
+    const i = DENSITIES.indexOf(density);
+    if (i < DENSITIES.length - 1 && crowded(box)) setDensity(DENSITIES[i + 1]);
+  }, [density, remeasure]);
+
+  useEffect(() => {
+    const box = boxRef.current;
+    const lead = box?.querySelector(".gemboss-ec-toolbar-lead");
+    if (!box || !lead) return undefined;
+    const restart = () => { setDensity("full"); setRemeasure((n) => n + 1); };
+    // WIDTH only (stepping does not change the box's width, so this cannot feed itself).
+    let width = box.clientWidth;
+    const ro = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(() => {
+      if (box.clientWidth === width) return;
+      width = box.clientWidth;
+      restart();
+    });
+    ro?.observe(box);
+    // A chip arriving, or its choice changing (`title` / `aria-label` / `data-label` carry the FULL label whatever the
+    // density). ONE observe call: a second one on the same node replaces the first one's options.
+    const mo = new MutationObserver(restart);
+    mo.observe(lead, { childList: true, subtree: true, attributes: true, attributeFilter: ["data-label", "title", "aria-label"] });
+    restart();
+    let live = true;
+    void document.fonts?.ready.then(() => { if (live) restart(); });
+    return () => { live = false; ro?.disconnect(); mo.disconnect(); };
+  }, []);
+
+  // Grow from one line to the box's max-height (chat.css: 84px), then scroll inside. Hidden (a closed tab): skip, the
+  // observer fits it when it gets a size.
+  useEffect(() => {
+    const el = ref.current;
+    if (!el) return undefined;
+    const fit = () => {
+      if (el.offsetParent === null || el.scrollHeight === 0) return;
+      const max = parseFloat(getComputedStyle(el).maxHeight) || 84;
+      el.style.height = "auto";
+      const want = el.scrollHeight + (el.offsetHeight - el.clientHeight); // border-box: add the 1px borders back
+      el.style.height = `${Math.min(want, max)}px`;
+      el.style.overflowY = want > max ? "auto" : "hidden";
+    };
+    fit();
+    if (typeof ResizeObserver === "undefined") return undefined;
+    let width = el.clientWidth;
+    const ro = new ResizeObserver(() => { if (el.clientWidth === width) return; width = el.clientWidth; fit(); });
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, [p.value, ref]);
+
+  const send = () => { if (canSend) p.onSend(p.value); };
+  const showStop = Boolean(p.busy && p.onStop);
+
+  return (
+    <DensityContext.Provider value={density}>
+      <div ref={boxRef} className={cx("gemboss-ec-input", p.className)} data-density={density}>
+        {p.top}
+        <textarea
+          ref={ref as Ref<HTMLTextAreaElement>}
+          value={p.value}
+          rows={p.rows ?? 1}
+          maxLength={p.maxLength}
+          disabled={p.disabled}
+          aria-label={p.label ?? L.message}
+          placeholder={p.placeholder}
+          onChange={(e) => p.onChange(e.target.value)}
+          onPaste={p.onPaste}
+          onKeyDown={(e) => {
+            p.onKeyDown?.(e);
+            if (e.defaultPrevented) return;
+            // Not mid-composition: Enter there picks the IME's candidate (Vietnamese Telex, Chinese pinyin), it does not send.
+            if (e.key === "Enter" && !e.shiftKey && !e.nativeEvent.isComposing && e.keyCode !== 229) { e.preventDefault(); send(); }
+          }}
+        />
+        <div className="gemboss-ec-toolbar">
+          <div className="gemboss-ec-toolbar-lead">{p.leading}</div>
+          {p.tools ? <div className="gemboss-ec-toolbar-tools">{p.tools}</div> : null}
+          {p.status}
+          {/* Two keys, two nodes: one reused <button> was born with stop's red and faded to grey (the admin, 22/09). */}
+          {showStop ? (
+            <button key="stop" type="button" className="gemboss-ec-stop" aria-label={L.stop} title={L.stop} disabled={p.stopDisabled || undefined}
+              onClick={() => { p.onStop?.(); ref.current?.focus(); }}>
+              <svg viewBox="0 0 12 12" aria-hidden="true" focusable="false"><rect x="1" y="1" width="10" height="10" rx="2" /></svg>
+            </button>
+          ) : (
+            <button key="send" type="submit" disabled={!canSend} aria-label={L.send} title={L.send} onClick={(e) => { e.preventDefault(); send(); }}>
+              <SendIcon />
+            </button>
+          )}
+        </div>
+      </div>
+    </DensityContext.Provider>
+  );
+}
+
+/** The attach button for `tools`: the paperclip, a hidden file input, the files handed over. */
+export function ChatAttach({ onFiles, accept, multiple, label, title, disabled }: {
+  onFiles: (files: File[]) => void;
+  accept?: string;
+  multiple?: boolean;
+  label?: string;
+  title?: string;
+  disabled?: boolean;
+}) {
+  const L = useLabels();
+  const input = useRef<HTMLInputElement>(null);
+  return (
+    <>
+      <button type="button" className="gemboss-ec-attach-btn" aria-label={label ?? L.attach} title={title ?? label ?? L.attach}
+        disabled={disabled} onClick={() => input.current?.click()}>
+        <PaperclipIcon />
+      </button>
+      <input ref={input} type="file" hidden accept={accept} multiple={multiple} tabIndex={-1}
+        onChange={(e) => { const files = [...(e.target.files ?? [])]; e.target.value = ""; if (files.length) onFiles(files); }} />
+    </>
+  );
+}
+
+// ── The whole chat ─────────────────────────────────────────────────────────────────────────────────────────────────────
+
+export interface ChatMessageData {
+  id?: string | number;
+  role: "user" | "assistant" | "note";
+  /** user: plain text. assistant: markdown (or plain with `markdown: false`). note: the line. */
+  text?: string;
+  markdown?: boolean;
+  /** A turn in flight: the heartbeat until text arrives; with text, the cursor after it. */
+  pending?: boolean;
+  steps?: readonly ChatStep[];
+  /** The turn failed: the message. `fix` turns it into "what to do + the command". `bridge`: it failed because of the
+   *  bridge, so it is one `BridgeNotice` line whose action opens the picker's Setup. */
+  error?: ReactNode;
+  fix?: ChatFix | null;
+  bridge?: boolean;
+  warn?: ReactNode;
+  stopped?: boolean;
+  /** Under a finished answer, after Copy: engine, seconds, model, cost. */
+  meta?: ReactNode[];
+  /** A note's look: a quiet centred line (default), or a BridgeNotice line (warn / down) with `action`. */
+  tone?: "muted" | "warn" | "down";
+  action?: { label?: string; onClick: () => void };
+  lang?: string;
+}
+
+export interface AssistantChatProps extends Omit<ChatMarkdownProps, "text"> {
+  messages: readonly ChatMessageData[];
+  busy?: boolean;
+  onSend: (text: string) => void;
+  onStop?: () => void;
+  sendWhileBusy?: boolean;
+  /** The draft, controlled. Omit both and the chat keeps it (and clears it after a send). */
+  draft?: string;
+  onDraftChange?: (v: string) => void;
+  placeholder?: string;
+  inputLabel?: string;
+  /** The empty state: an assistant bubble with what to ask, then the starters. */
+  intro?: ReactNode;
+  starters?: readonly ChatStarter[];
+  startersTitle?: ReactNode;
+  /** More starter groups under the first ("Or ask about partners in the radar:"). */
+  moreStarters?: readonly ChatStarter[];
+  moreStartersTitle?: ReactNode;
+  /** The engine picker element (and any other chip) for the composer's chip strip. */
+  engine?: ReactNode;
+  /** Tools beside the chips (`ChatAttach`). */
+  tools?: ReactNode;
+  composerTop?: ReactNode;
+  composerStatus?: ReactNode;
+  maxLength?: number;
+  /** The heartbeat's verbs ("Reading the board", "Answering"). */
+  pendingVerbs?: readonly string[];
+  /** A BridgeNotice's action ("Open setup" → the picker's Setup tab). */
+  onOpenSetup?: () => void;
+  /** Surface content under an answer (a proposal card, an action card). */
+  renderExtra?: (m: ChatMessageData, index: number) => ReactNode;
+  labels?: Partial<ChatLabels>;
+  /** The chat's own heading, shown where the frame has no title bar: full screen, or a page that is not in a frame. In
+   *  the popup and the side panel the frame's header says it already (the admin's "Ask the Operator"). */
+  title?: ReactNode;
+  subtitle?: ReactNode;
+  threadRef?: Ref<HTMLDivElement>;
+  inputRef?: RefObject<HTMLTextAreaElement | null>;
+  onComposerKeyDown?: KeyboardEventHandler<HTMLTextAreaElement>;
+  onComposerPaste?: ClipboardEventHandler<HTMLTextAreaElement>;
+  className?: string;
+}
+
+/**
+ * The whole chat: the thread (empty state, messages) over the composer, filling the frame's body. Put it inside
+ * `AssistantHost` (and `AssistantWorkspaceLayout` for the 820px reading column at full screen).
+ */
+export function AssistantChat(p: AssistantChatProps) {
+  const L = useMemo(() => ({ ...CHAT_EN, ...p.labels }), [p.labels]);
+  const [ownDraft, setOwnDraft] = useState("");
+  const controlled = p.draft !== undefined;
+  const draft = controlled ? (p.draft as string) : ownDraft;
+  const setDraft = (v: string) => { if (!controlled) setOwnDraft(v); p.onDraftChange?.(v); };
+  const ownInput = useRef<HTMLTextAreaElement | null>(null);
+  const inputRef = p.inputRef ?? ownInput;
+  const md: ChatMarkdownProps = { text: "", onNavigate: p.onNavigate, imageHosts: p.imageHosts, ownLink: p.ownLink, renderLink: p.renderLink };
+  // Back to the end on a send, and when another conversation is shown (its first message is another one, or it is empty).
+  const [sent, setSent] = useState(0);
+  const pinKey = `${sent}:${p.messages[0]?.id ?? ""}:${p.messages.length === 0}`;
+  const send = (text: string) => { p.onSend(text); setSent((n) => n + 1); if (!controlled) setOwnDraft(""); };
+  const rootRef = useRef<HTMLDivElement>(null);
+  useFullChromeRoom(rootRef);
+  const pick = (s: ChatStarter) => {
+    if (s.fill) { setDraft(s.prompt ?? s.label); inputRef.current?.focus(); return; }
+    p.onSend(s.prompt ?? s.label);
+    setSent((n) => n + 1);
+  };
+  return (
+    <LabelsContext.Provider value={L}>
+      <div ref={rootRef} className={cx("gb-chat", p.className)}>
+        {p.title ? (
+          <div className="gemboss-ec-head gb-chat-head">
+            <div className="gemboss-ec-title">{p.title}</div>
+            {p.subtitle ? <div className="gemboss-ec-sub">{p.subtitle}</div> : null}
+          </div>
+        ) : null}
+        <ChatThread busy={p.busy} scrollRef={p.threadRef} pinKey={pinKey}>
+          {p.messages.length === 0 && (p.intro || p.starters?.length) ? (
+            <ChatMessage role="assistant">
+              {p.intro ? <ChatBubble>{p.intro}</ChatBubble> : null}
+              {p.starters?.length ? <ChatStarters items={p.starters} onPick={pick} title={p.startersTitle} /> : null}
+              {p.moreStarters?.length ? <ChatStarters items={p.moreStarters} onPick={pick} title={p.moreStartersTitle} /> : null}
+            </ChatMessage>
+          ) : null}
+          {p.messages.map((m, i) => {
+            // An id when there is one, the position otherwise, never mixed in one space (id 2 and the third id-less message).
+            const key = m.id !== undefined && m.id !== null ? `id:${m.id}` : `at:${i}`;
+            if (m.role === "note") {
+              return m.tone === "warn" || m.tone === "down"
+                ? <BridgeNotice key={key} tone={m.tone} action={m.action?.label} onOpenSetup={m.action?.onClick}>{m.text}</BridgeNotice>
+                : <ChatNote key={key}>{m.text}</ChatNote>;
+            }
+            if (m.role === "user") {
+              return <ChatMessage key={key} role="user" lang={m.lang}><ChatBubble>{m.text}</ChatBubble></ChatMessage>;
+            }
+            const hasText = Boolean(m.text);
+            return (
+              <ChatMessage key={key} role="assistant" lang={m.lang}>
+                {m.steps?.length ? <ChatSteps steps={m.steps} /> : null}
+                {hasText ? (
+                  <ChatBubble streaming={m.pending}>
+                    {m.markdown === false ? m.text : <ChatMarkdown {...md} text={m.text as string} />}
+                  </ChatBubble>
+                ) : m.pending ? <ChatPending verbs={p.pendingVerbs} /> : null}
+                {p.renderExtra?.(m, i)}
+                {m.warn ? <p className="ui-notice ui-notice--warning gb-chat-notice">{m.warn}</p> : null}
+                {m.error ? (m.bridge
+                  ? <BridgeNotice onOpenSetup={p.onOpenSetup}>{m.error}</BridgeNotice>
+                  : <ChatError fix={m.fix}>{m.error}</ChatError>) : null}
+                {m.stopped ? <ChatNote>{L.stopped}</ChatNote> : null}
+                {!m.pending && hasText ? <ChatMeta copyText={m.text} items={m.meta} /> : null}
+              </ChatMessage>
+            );
+          })}
+        </ChatThread>
+        <ChatComposer
+          value={draft} onChange={setDraft} onSend={send}
+          busy={p.busy} onStop={p.onStop} sendWhileBusy={p.sendWhileBusy}
+          placeholder={p.placeholder} label={p.inputLabel} maxLength={p.maxLength}
+          leading={p.engine} tools={p.tools} top={p.composerTop} status={p.composerStatus}
+          textareaRef={inputRef} onKeyDown={p.onComposerKeyDown} onPaste={p.onComposerPaste}
+        />
+      </div>
+    </LabelsContext.Provider>
+  );
+}
+
+/**
+ * Full screen: the frame floats its buttons (Back to the popup, the surface's `fullActions`) over the top right of its
+ * body. The admin's chat has a header whose right half is empty for them; a chat without one had its first message under
+ * them (content-radar /v2/assistant, 1280). How far they reach into THIS element is measured (the frame cannot know where
+ * a child's 820px column sits: at 1920 it does not reach it at all) and written as `--gb-chat-chrome-w` / `-h` with
+ * `data-chrome` on the element; nothing when they do not overlap. Re-measured when the element, the frame or the buttons
+ * themselves change size (an action added, fonts loaded). `AssistantChat` uses it; a surface arranging the pieces itself
+ * calls it on its own column and pads by the variables.
+ */
+export function useFullChromeRoom(ref: RefObject<HTMLElement | null>) {
+  useEffect(() => {
+    const root = ref.current;
+    const dock = root?.closest(".gb-dock");
+    if (!root || !dock || typeof ResizeObserver === "undefined") return undefined;
+    let watched: Element | null = null;
+    const clear = () => { root.removeAttribute("data-chrome"); root.style.removeProperty("--gb-chat-chrome-w"); root.style.removeProperty("--gb-chat-chrome-h"); };
+    const ro = new ResizeObserver(() => measure());
+    function measure() {
+      const chrome = dock!.querySelector<HTMLElement>(":scope > [data-gb-dock-chrome]");
+      if (chrome !== watched) { if (watched) ro.unobserve(watched); if (chrome) ro.observe(chrome); watched = chrome; }
+      if (!chrome || getComputedStyle(chrome).position !== "absolute") return clear();
+      const c = chrome.getBoundingClientRect(), r = root!.getBoundingClientRect();
+      if (c.left >= r.right || c.bottom <= r.top || c.right <= r.left) return clear();
+      root!.style.setProperty("--gb-chat-chrome-w", `${Math.ceil(r.right - c.left + 8)}px`);
+      root!.style.setProperty("--gb-chat-chrome-h", `${Math.ceil(c.bottom - r.top + 8)}px`);
+      root!.setAttribute("data-chrome", "");
+    }
+    measure();
+    ro.observe(root);
+    ro.observe(dock);
+    // The buttons come and go with the mode (full ⇄ popup), and an action can be added inside them.
+    const mo = new MutationObserver(measure);
+    mo.observe(dock, { childList: true, attributes: true, attributeFilter: ["class"] });
+    return () => { ro.disconnect(); mo.disconnect(); };
+  }, [ref]);
+}
+
+/** The labels for pieces used outside `AssistantChat` (a surface arranging them itself). */
+export function ChatLabelsProvider({ labels, children }: { labels?: Partial<ChatLabels>; children?: ReactNode }) {
+  const v = useMemo(() => ({ ...CHAT_EN, ...labels }), [labels]);
+  return <LabelsContext.Provider value={v}>{children}</LabelsContext.Provider>;
+}