@djangocfg/widget-chat 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Reforms.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,124 @@
+# @djangocfg/widget-chat
+
+The chat surface: transcript, composer, tool calls, streaming markdown.
+Transport-agnostic — the host supplies an adapter and the package supplies
+everything a chat looks like.
+
+Text-only by design. There is no attaching, no pasting a file, no file part in
+the transcript: a message is prose, plus whatever the model streams back.
+
+## Install
+
+```bash
+pnpm add @djangocfg/widget-chat @djangocfg/ui-core
+```
+
+```tsx
+import { Chat } from '@djangocfg/widget-chat';
+import '@djangocfg/widget-chat/styles';
+
+<Chat
+  adapter={myAdapter}
+  capabilities={{ tools: myTools, voice: myVoice }}
+  renderers={myRenderers}
+/>
+```
+
+Every capability is optional and absent means absent, never stubbed: a chat with
+none of them is a working read-and-send surface, not a degraded one. The nine
+are `suggestions`, `tools`, `retry`, `cancelRun`, `voice`, `voiceSounds`,
+`think`, `media` and `mentionNames`.
+
+## Layers
+
+Layers import strictly downward and each is importable alone.
+
+| Subpath | Layer | React? |
+|---|---|---|
+| `./core` | the model: transcript, parts, links, queue, recall, voice | no |
+| `./store` | the store and its React bindings | yes |
+| `./primitives` | unopinionated pieces and hooks | yes |
+| `./composer` | the input surface | yes |
+| `./content` | markdown rendering (streamdown + shiki + katex) | yes |
+| `./ui` | the assembled components a host mounts | yes |
+| `./widgets` | transcript blocks: media |
+| `./utils`, `./i18n`, `./testing`, `./styles` | helpers, 17 locales, mocks, CSS |
+
+**`./content` is not re-exported from the root, and that is the one deliberate
+exclusion.** It pulls streamdown plus shiki and katex — a host rendering a
+read-only transcript, or supplying its own markdown renderer, must not pay for a
+syntax highlighter.
+
+## The test that decides ownership
+
+> **A file belongs here when a second product would have to write it again,
+> unchanged.**
+
+Not "it is about chat". An adapter speaking one server's vocabulary is entirely
+about chat and belongs to the HOST. A transcript shortcut every consumer needs
+byte for byte belongs here.
+
+Two corollaries, both argued the other way and settled by a defect:
+
+*   **Needing i18n does not make something the host's.** The package owns its
+    17-locale dictionary — a typed `ChatCopy` object, not a `t(key)` resolver.
+    Copy used to arrive as props; that made adding one string a four-file
+    change, and it let a host assemble a translated string into a DOM selector,
+    breaking the composer's caret in one locale with types and tests green.
+*   **Needing a domain type DOES make it the host's.** Anything mapping a
+    server's rows stays outside, because holding it here would point this
+    package at a wire contract — the arrow the structure exists to avoid.
+
+## Why it exists
+
+The predecessor was 947 lines with **83 near-all-optional props** plus 16 hooks
+— a combinatorial explosion nobody could reason about. So: **new capability adds
+a part type, a capability, or a widget — never a prop on `<Chat>`**, whose count
+is gated by a test.
+
+## The link scheme
+
+A chip is written as a markdown link, sent as text, parsed back, and re-drawn.
+That round trip needs a URL scheme the host can distinguish from an ordinary
+link. The scheme is yours; the one shape is ours:
+
+```ts
+import { configureMentionScheme } from '@djangocfg/widget-chat/core';
+
+configureMentionScheme('myapp');   // once, at startup, before the first render
+// a picked tool then reads myapp://tool/<id>
+```
+
+One shape, because a tool is the only thing this package both writes and parses.
+A host that lets the user name people, documents or tickets addresses them with
+its own scheme and resolves them itself — guessing at that grammar here would
+give every host a round trip it did not ask for.
+
+Configure it **before the first render**. Two places read the scheme back — the
+hardened protocol allowlist in `content/response.tsx` and the media `src`
+allowlist in `core/media/allowed-src.ts` — and the first reads it lazily for
+exactly this reason. Setting it later leaves already-written links addressing
+the old scheme, which then render as plain text.
+
+## Documentation
+
+This file is the contract. [`@docs/`](./@docs/README.md) is the long form —
+six pages, each covering one seam:
+
+| Page | Covers |
+|---|---|
+| [getting-started](./@docs/getting-started.md) | Install, the adapter, the three things that fail silently. |
+| [architecture](./@docs/architecture.md) | The layers, the seven props, the executable gates. |
+| [streaming](./@docs/streaming.md) | `StreamChunk`, the reducer, cancellation. |
+| [capabilities](./@docs/capabilities.md) | The nine capabilities and the extension seams. |
+| [composer](./@docs/composer.md) | Keys, recall, autosize, drafts. |
+| [styling](./@docs/styling.md) | The structure/appearance split and theming. |
+
+`CLAUDE.md` is the third document and answers a different question: what is
+easy to break.
+
+## Verify
+
+```bash
+pnpm --filter @djangocfg/widget-chat check-types test
+```

package/package.json

@@ -0,0 +1,95 @@
+{
+  "name": "@djangocfg/widget-chat",
+  "version": "0.1.1",
+  "description": "A transport-agnostic chat surface: a pure core, a store, primitives, a composer, and the assembled components a host mounts",
+  "keywords": [
+    "chat",
+    "ai",
+    "streaming",
+    "markdown",
+    "composer",
+    "react",
+    "typescript"
+  ],
+  "author": {
+    "name": "DjangoCFG",
+    "url": "https://djangocfg.com"
+  },
+  "homepage": "https://djangocfg.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/markolofsen/django-cfg.git",
+    "directory": "widgets/chat"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./styles": "./src/styles/index.css",
+    "./core": "./src/core/index.ts",
+    "./store": "./src/store/index.ts",
+    "./primitives": "./src/primitives/index.ts",
+    "./widgets": "./src/widgets/index.ts",
+    "./content": "./src/content/index.ts",
+    "./composer": "./src/composer/index.ts",
+    "./ui": "./src/ui/index.ts",
+    "./utils": "./src/utils/index.ts",
+    "./i18n": "./src/i18n/index.ts",
+    "./testing": "./src/testing/index.ts"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.stories.tsx",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "check": "tsc --noEmit",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@djangocfg/widget-kit": "^0.1.1",
+    "@djangocfg/widget-media": "^0.1.1",
+    "@streamdown/code": "^1.1.1",
+    "@streamdown/math": "^1.0.2",
+    "mdast-util-to-string": "^4.0.0",
+    "rehype-harden": "^1.1.8",
+    "remark-parse": "^11.0.0",
+    "unified": "^11.0.5",
+    "use-stick-to-bottom": "^1.1.6"
+  },
+  "peerDependencies": {
+    "@djangocfg/i18n": "^2.1.542",
+    "@djangocfg/ui-core": "^2.1.542",
+    "lucide-react": "^0.545.0",
+    "react": "^19.0.0",
+    "remark-gfm": "^4.0.0",
+    "streamdown": "^2.6.0"
+  },
+  "devDependencies": {
+    "@djangocfg/i18n": "^2.1.542",
+    "@djangocfg/typescript-config": "^2.1.542",
+    "@djangocfg/ui-core": "^2.1.542",
+    "@storybook/react-vite": "^10.5.0",
+    "@types/node": "^25.9.5",
+    "@types/react": "19.2.15",
+    "@types/react-dom": "19.2.3",
+    "lucide-react": "0.545.0",
+    "react": "19.2.7",
+    "react-dom": "19.2.7",
+    "remark-gfm": "4.0.1",
+    "storybook": "^10.5.0",
+    "streamdown": "2.6.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.10"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/composer/composer.tsx

@@ -0,0 +1,100 @@
+import { useCallback, useEffect, useRef, type FormEvent, type PointerEvent, type ReactNode } from "react";
+
+import { useChatSurfaces, useDraft } from "../store";
+import { ComposerContext } from "./context";
+import { focusComposerField } from "./focus-field";
+
+export interface ComposerProps {
+  readonly children: ReactNode;
+  readonly className?: string;
+  /**
+   * A press on the composer's own padding focuses the field, caret at the end.
+   * Default true: the box is mostly padding, and clicking its middle did
+   * nothing. Opt out when the composer is not the only thing in the form.
+   */
+  readonly focusOnPress?: boolean;
+}
+
+/**
+ * The composer root: a form, a draft, and nothing else.
+ *
+ * Its prop count is capped on purpose. Everything that would have been
+ * `sendLabel` / `renderChip` lives in a part the host chooses to render —
+ * `@rules/budgets.md`, "a boolean prop is a component someone was too lazy to write".
+ *
+ * A real `<form>` rather than a div with a click handler: that is what makes
+ * Enter-to-submit, implicit submission and a screen reader's form semantics work
+ * without re-implementing any of them.
+ */
+export function Composer({ children, className, focusOnPress = true }: ComposerProps) {
+  const draft = useDraft();
+  const { send } = draft;
+  const surfaces = useChatSurfaces();
+
+  // Appending, never replacing: a mention from the transcript is one more
+  // addressee, not a new draft. Spaced on both sides so tokens cannot fuse.
+  // Read through a ref: depending on the text would re-register this on every
+  // keystroke.
+  const { setText } = draft;
+  const textRef = useRef(draft.draft.text);
+  textRef.current = draft.draft.text;
+  const registerMention = surfaces?.registerMention;
+  useEffect(() => {
+    if (registerMention === undefined) return;
+    registerMention((token: string) => {
+      const current = textRef.current;
+      const lead = current === "" || /\s$/.test(current) ? "" : " ";
+      setText(`${current}${lead}${token} `);
+    });
+    return () => registerMention(null);
+  }, [registerMention, setText]);
+
+  const { setReplyTo } = draft;
+  const registerReplyTo = surfaces?.registerReplyTo;
+  useEffect(() => {
+    if (registerReplyTo === undefined) return;
+    registerReplyTo(setReplyTo);
+    return () => registerReplyTo(null);
+  }, [registerReplyTo, setReplyTo]);
+
+  const onSubmit = useCallback(
+    (event: FormEvent<HTMLFormElement>) => {
+      // Always: a native submit would navigate the page away.
+      event.preventDefault();
+      send();
+    },
+    [send],
+  );
+
+  const onPointerDown = useCallback(
+    (event: PointerEvent<HTMLFormElement>) => {
+      if (!focusOnPress) return;
+      // ONLY the form's own padding. A press that landed on a child is that
+      // child's — without this, clicking the mic or a chip also focuses the
+      // field and steals the caret from the control the user aimed at.
+      if (event.target !== event.currentTarget) return;
+      // Prevent the default so the press does not blur the field it is about to
+      // focus; a form's padding is not focusable, but the mousedown still
+      // clears the current selection.
+      event.preventDefault();
+      focusComposerField(event.currentTarget);
+    },
+    [focusOnPress],
+  );
+
+  return (
+    <ComposerContext.Provider value={draft}>
+      <form
+        // Registered, not exposed as a ref prop: a host needs the field to put
+        // the caret back after a modal closes, and threading a ref out would
+        // spend a prop on this capped component for one host's benefit.
+        ref={surfaces?.registerComposer}
+        className={className}
+        onPointerDown={onPointerDown}
+        onSubmit={onSubmit}
+      >
+        {children}
+      </form>
+    </ComposerContext.Provider>
+  );
+}

package/src/composer/context.ts

@@ -0,0 +1,33 @@
+/**
+ * The composer's own context, deliberately separate from `ChatContext`.
+ *
+ * `useDraft()` holds per-composer state (the text being typed, the chips not yet
+ * sent). Putting it on the chat context would make two composers on one screen
+ * share a draft, and would re-render every transcript row on each keystroke —
+ * the chat context is read by rows that must not care about typing.
+ */
+
+import { createContext, useContext } from "react";
+
+import type { DraftApi } from "../store/use-draft";
+
+export const ComposerContext = createContext<DraftApi | null>(null);
+
+export function useComposer(): DraftApi {
+  const value = useContext(ComposerContext);
+  if (value === null) {
+    throw new Error("composer parts must be used inside <Composer>");
+  }
+  return value;
+}
+
+/**
+ * The draft when there is one, null otherwise.
+ *
+ * For a part that must decide whether to render at all BEFORE it needs the
+ * draft: hooks cannot run conditionally, so the throwing variant would fire
+ * before an absent capability could return null.
+ */
+export function useOptionalComposer(): DraftApi | null {
+  return useContext(ComposerContext);
+}

package/src/composer/controls/button.tsx

@@ -0,0 +1,104 @@
+import type { ButtonHTMLAttributes, ReactNode, Ref } from "react";
+
+/**
+ * One control in the composer's toolbar row.
+ *
+ * Four buttons arrived here with four different answers to "what does a control
+ * look like": the engine chip tinted itself with `accent` — BLUE in this theme,
+ * so hovering lit up a filled pill beside the blue send button — the
+ * dictation-language caret used `accent` too, the mic changed only its text
+ * colour and so appeared to have no hit box at all, and send is permanently
+ * filled with no hover at all. Read as a row they were four unrelated widgets.
+ *
+ * A component rather than a `.composer-box button` rule is what makes that
+ * stay fixed: three of these are owned by DIFFERENT packages, so a descendant
+ * selector would style whatever they happen to render and silently lose to any
+ * utility class they carry. Asking for the component is a decision each caller
+ * makes once; inheriting from an ancestor is a coincidence of nesting.
+ *
+ * It renders a `<button>` and nothing else — no context, no portal — so a host
+ * that needs a menu, a tooltip or a popover wraps this, and every one of them
+ * still agrees about size, radius and hover.
+ */
+
+export type ComposerButtonTone = "neutral" | "primary";
+
+export interface ComposerButtonProps
+  extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "className"> {
+  /**
+   * `primary` is the SEND action, and there is exactly one of it. A second
+   * filled control in the row would make the composer offer two equal answers
+   * to "what does Enter do".
+   */
+  readonly tone?: ComposerButtonTone;
+  /**
+   * Wider than square, for a control that carries text (the engine chip).
+   *
+   * The default is the 32px square every icon control uses; text needs room
+   * either side of it, and stretching the square by padding alone would make
+   * the two kinds disagree about height.
+   */
+  readonly wide?: boolean;
+  readonly className?: string;
+  readonly children?: ReactNode;
+  readonly ref?: Ref<HTMLButtonElement>;
+}
+
+const BASE =
+  // The design system's control radius, matching the box around them: both are
+  // rounded rectangles from the same scale, so the row reads as one object.
+  // (It was `rounded-full` while the box was a capsule — the box drives this.)
+  "shrink-0 items-center justify-center rounded-[var(--radius-control,0.625rem)] transition-colors " +
+  // Height DERIVED from the field beside it, never a literal — a hardcoded 32px
+  // silently went 2px short the moment the body text moved from 15px to 16. The
+  // expression lives in `composer.css`, which needs the same number to keep the
+  // box's capsule radius concentric with these circles; two copies of one
+  // measurement is exactly how the corners stop matching.
+  "h-[var(--chat-composer-control-h,2.125rem)] disabled:opacity-40 " +
+  // Focus is the host theme's ring, borrowed rather than imported — this
+  // package declares no dependency on a component library.
+  "outline-none focus-visible:outline-2 focus-visible:outline-offset-2 " +
+  "focus-visible:outline-[var(--ring,currentColor)] " +
+  "[&_svg]:size-4 [&_svg]:shrink-0";
+
+const TONES: Record<ComposerButtonTone, string> = {
+  // A quiet plate on hover, never a tint. `--accent` is the theme's highlight
+  // (blue here), and a filled blue plate beside the blue send button reads as a
+  // second primary action rather than as a hover.
+  neutral:
+    "text-muted-foreground not-disabled:hover:bg-muted not-disabled:hover:text-foreground " +
+    "aria-expanded:bg-muted aria-expanded:text-foreground",
+  // Already filled, so it answers with depth instead of a plate.
+  primary: "bg-primary text-primary-foreground not-disabled:hover:brightness-95",
+};
+
+export function ComposerButton({
+  tone = "neutral",
+  wide = false,
+  className,
+  children,
+  ref,
+  type = "button",
+  ...rest
+}: ComposerButtonProps) {
+  // `flex` for the wide variant, `grid` for the square one — and the difference
+  // is load-bearing, not cosmetic. A single-column grid stacks its children in
+  // ROWS, so a chip carrying icon + label + caret put the caret on a third row
+  // and pushed it out through the button's fixed 32px height, below the
+  // composer's own edge. Flex lays the same three out along the row, which is
+  // what `gap-1.5` was always describing.
+  // `aspect-square` rather than a second copy of the height expression: the
+  // square variant must stay square whatever that height resolves to, and
+  // repeating the calc is how the two drift apart.
+  const width = wide ? "flex gap-1.5 px-2.5" : "grid aspect-square";
+  return (
+    <button
+      {...rest}
+      ref={ref}
+      type={type}
+      className={`${BASE} ${width} ${TONES[tone]} ${className ?? ""}`}
+    >
+      {children}
+    </button>
+  );
+}

package/src/composer/controls/language-menu.tsx

@@ -0,0 +1,123 @@
+import { useMemo, useState, type ChangeEvent, type ReactNode } from "react";
+
+import { WEB_SPEECH_LANGUAGES, matchesLanguageQuery } from "../../core";
+
+export interface LanguageMenuProps {
+  /** The tag in force, so the current row can be marked. */
+  readonly current: string;
+  readonly onSelect: (tag: string) => void;
+  /** Accessible name of the list. Copy is the host's — no locales here. */
+  readonly label: string;
+  readonly searchLabel: string;
+  readonly emptyLabel: string;
+  readonly className?: string;
+  /**
+   * Rendered above the search box. Absent ⇒ no header at all.
+   *
+   * The panel's OWNER supplies this, because only it knows whether the list is
+   * a whole surface or one view inside a larger one — and a back control that
+   * leads nowhere is worse than no header.
+   */
+  readonly header?: ReactNode;
+}
+
+interface Row {
+  readonly tag: string;
+  readonly name: string;
+  readonly region: string;
+  /** Everything searchable, lowercased once so the filter stays a substring test. */
+  readonly haystack: string;
+}
+
+/**
+ * Every dialect as a flat row.
+ *
+ * Flat rather than language-then-dialect: a two-level menu makes the common
+ * case — "I want Russian" — two interactions, and the search box already
+ * collapses the hierarchy better than nesting does.
+ *
+ * Built once at module scope. The catalogue is static, and rebuilding 60-odd
+ * languages worth of rows per render would be work done on every keystroke.
+ */
+const ROWS: readonly Row[] = WEB_SPEECH_LANGUAGES.flatMap((language) =>
+  language.dialects.map((dialect) => ({
+    tag: dialect.code,
+    name: language.name,
+    region: dialect.region,
+    haystack:
+      `${language.name} ${language.englishName} ${language.iso} ${dialect.code} ${dialect.region}`.toLowerCase(),
+  })),
+);
+
+/** The display name for a tag, or the tag itself when it is not in the catalogue. */
+export function languageLabel(tag: string): string {
+  const row = ROWS.find((candidate) => candidate.tag === tag);
+  if (row !== undefined) return row.name;
+  // A host may pin a tag the catalogue does not carry. Showing it raw is honest;
+  // showing nothing would hide the value that decides whether dictation works.
+  return tag;
+}
+
+/**
+ * The dictation language list.
+ *
+ * Search is LAYOUT-INDEPENDENT (`matchesLanguageQuery`): typing "hec" on an
+ * English layout while thinking «рус» finds Русский, because the physical keys
+ * are right and only the layout is wrong. That is the single most common way a
+ * bilingual user searches this list, and it is why the search index packs the
+ * native name, the English name, the ISO code, the tag and the region together.
+ */
+export function LanguageMenu({
+  current,
+  onSelect,
+  label,
+  searchLabel,
+  emptyLabel,
+  className,
+  header,
+}: LanguageMenuProps) {
+  const [query, setQuery] = useState("");
+
+  const rows = useMemo(
+    () => (query.trim() === "" ? ROWS : ROWS.filter((row) => matchesLanguageQuery(row.haystack, query))),
+    [query],
+  );
+
+  const onQuery = (event: ChangeEvent<HTMLInputElement>): void => setQuery(event.target.value);
+
+  return (
+    <div className={className}>
+      {header}
+      <input
+        type="search"
+        value={query}
+        onChange={onQuery}
+        aria-label={searchLabel}
+        className="border-border w-full border-b bg-transparent px-3 py-2 text-sm outline-none"
+        // Autofocus is correct HERE and almost nowhere else: the view is reached
+        // by a deliberate press and its only purpose is to be searched.
+        autoFocus
+      />
+      {rows.length === 0 ? (
+        <p className="text-muted-foreground px-3 py-2 text-sm">{emptyLabel}</p>
+      ) : (
+        <ul role="listbox" aria-label={label} className="max-h-64 overflow-y-auto py-1">
+          {rows.map((row) => (
+            <li key={row.tag}>
+              <button
+                type="button"
+                role="option"
+                aria-selected={row.tag === current}
+                onClick={() => onSelect(row.tag)}
+                className="hover:bg-accent flex w-full items-baseline gap-2 px-3 py-1.5 text-left text-sm aria-selected:font-medium"
+              >
+                <span className="min-w-0 truncate">{row.name}</span>
+                <span className="text-muted-foreground min-w-0 truncate text-xs">{row.region}</span>
+              </button>
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}

package/src/composer/controls/send.tsx

@@ -0,0 +1,83 @@
+import { useCallback, type ReactNode } from "react";
+
+import { useChatCopy } from "../../i18n";
+import { useCapabilities, useTurn } from "../../store";
+import { ComposerButton } from "./button";
+import { ComposerTooltip } from "./tooltip";
+import { useComposer } from "../context";
+
+export interface ComposerSendProps {
+  readonly className?: string;
+  /**
+   * Icon or glyph. The accessible name comes from the labels, never from this.
+   *
+   * A FUNCTION of `isStreaming`, matching `ToolCallHeader` and the other
+   * primitives: the glyph must change with the role — an arrow that still says
+   * "send" while the button stops a turn is a lie about what clicking does.
+   * A static node cannot express that, and passing `isStreaming` back in as a
+   * prop would be a second reader of store state the button already holds.
+   */
+  readonly children?: (isStreaming: boolean) => ReactNode;
+}
+
+/**
+ * Send, or Stop while a turn streams.
+ *
+ * One component, not two and not a `mode` prop: whether a turn is in flight is
+ * store state, and a prop would let the host disagree with the store — a Send
+ * button next to a streaming reply, clicking which queues a second turn.
+ */
+export function ComposerSend({ className, children }: ComposerSendProps) {
+  const { canSend, send } = useComposer();
+  const { isStreaming, stop } = useTurn();
+  const { cancelRun } = useCapabilities();
+  const copy = useChatCopy().composer;
+
+  const onClick = useCallback(() => {
+    if (isStreaming) {
+      // Both, in this order. `stop()` ends the local stream so the button
+      // answers immediately; `cancel()` ends the RUN, which the abort cannot
+      // reach — it is detached from its caller on purpose.
+      //
+      // Only from this button: `leaveRoom` also aborts, and cancelling there
+      // would truncate an answer because a tab closed, which is exactly what
+      // the detachment prevents.
+      stop();
+      void cancelRun?.cancel();
+      return;
+    }
+    send();
+  }, [isStreaming, stop, cancelRun, send]);
+
+  const label = isStreaming ? copy.stop : copy.send;
+  // Tooltipped like every other control in the row: the lone exception reads as
+  // an oversight. It also carries a fact the icon cannot — the key that sends,
+  // bound in `field/keys.ts`. Stop has no binding, so nothing is claimed for it.
+  const tooltip = isStreaming ? (
+    label
+  ) : (
+    <span className="flex flex-col gap-0.5">
+      <span>{label}</span>
+      <span className="opacity-70">{copy.sendShortcut}</span>
+    </span>
+  );
+
+  // `type="button"` in both roles — `ComposerButton`'s default: submit would
+  // fire the form's handler as well as this one, sending twice; and while
+  // streaming there is nothing to submit.
+  return (
+    <ComposerTooltip label={tooltip}>
+      <ComposerButton
+        tone="primary"
+        className={className}
+        aria-label={label}
+        // Stop must stay reachable on an empty draft — that is exactly when the
+        // user has sent and is waiting.
+        disabled={!isStreaming && !canSend}
+        onClick={onClick}
+      >
+        {children?.(isStreaming)}
+      </ComposerButton>
+    </ComposerTooltip>
+  );
+}