@djangocfg/widget-assistant 0.0.0-stage → 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

@@ -1,3 +1,34 @@
-# Temporary Holding Version
+# @djangocfg/widget-assistant
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The assistant chat for a site: the SSE wire and session, the persistent host, the docked column, the floating button and the phone sheet, on top of `@djangocfg/widget-chat`.
+It knows nothing about one site (`src/boundary.test.ts` enforces it), so what a host passes stays small: **a language (from the framework's locale provider), an adapter, suggestions and its own part renderers.** Source-only: the host transpiles it (`DEFAULT_TRANSPILE_PACKAGES`) and imports `@djangocfg/widget-assistant/styles` once.
+
+```tsx
+<AssistantChat adapter={adapter} suggestions={suggestions} dataRenderers={renderers} />
+```
+
+## Folders (one job each)
+
+| Folder | Job |
+|---|---|
+| `wire/` | the HTTP and SSE contract: frames, parser, transport, stored conversation |
+| `stream/` | one conversation: adapter, session hook, reconcile after a lost stream, the scripted transport for stories |
+| `composer/` | what the widget's composer lacks, mounted inside it (`ComposerBehaviour`): dictation keys, caret, height, the Help list |
+| `messages/` | the rows around messages: copy footer, the reconnecting/stalled line |
+| `shell/` | where the chat lives: column frame, dock/sheet, floating button with its hint, locked view, open/width state |
+| `i18n/` | the assistant's own words, 17 languages bundled (`locales/`), `useAssistantCopy()`; the language comes from `@djangocfg/i18n`'s provider, the same one the widget's own copy follows |
+| `styles/` | widget stylesheet entry, layout, composer and button motion |
+
+`Host.tsx` (exported as `./host`) keeps one mounted chat for many surfaces; `AssistantChat.tsx` composes the widget.
+
+## Behaviour worth knowing
+
+- **Dictation keys.** `⌘D` / `Ctrl+D` starts and stops (`formatHotkey` draws the right one for the system). While dictating, Enter stops and sends, Escape stops and keeps the text, from anywhere. Every stop waits with the microphone open until the field stops changing (450 ms of quiet, 2.5 s at most): the engine reports words late, and the widget's stop closes it and drops them. The engine is our own (`composer/wholeTranscript.ts`): it rebuilds the whole transcript from the browser's results at every event and restarts itself when the browser ends a run, because the widget's stitching of separate results kept only the last words.
+- **Field.** While dictating its height only grows (no jumping between bursts). Pressing the empty strip around the composer focuses the field (keyboard devices only).
+- **Caret.** Opening the panel on a keyboard device focuses the field; after a send the caret returns to the field, or to the microphone when the send ended a dictation (Enter then starts the next one). Never on phones.
+- **Floating button.** Pops in, shows a message-style hint after a moment (`hint` prop; text defaults to the bundled one), then a ring every so often. No close control; the host decides how often to show it.
+- **Help.** A quiet link under the composer opens the list of keys (`ComposerHelp`).
+
+## Tests
+
+`pnpm --filter @djangocfg/widget-assistant check test`: the wire, stream and boundary tests, and `tsc --noEmit`.

package/package.json

@@ -1,6 +1,74 @@
 {
   "name": "@djangocfg/widget-assistant",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "A site assistant on top of @djangocfg/widget-chat: the SSE wire and session layer, a persistent host, docked column, floating button and sheet, dictation, Help and 17 built-in locales",
+  "keywords": [
+    "chat",
+    "assistant",
+    "sse",
+    "dictation",
+    "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/assistant"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./host": "./src/Host.tsx",
+    "./styles": "./src/styles/index.css"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.stories.tsx",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "check": "tsc --noEmit",
+    "check-types": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@djangocfg/widget-chat": "^0.1.14",
+    "zustand": "^5.0.14"
+  },
+  "peerDependencies": {
+    "@djangocfg/i18n": "^2.1.585",
+    "@djangocfg/ui-core": "^2.1.585",
+    "lucide-react": "^0.545.0",
+    "react": "^19.0.0"
+  },
+  "devDependencies": {
+    "@djangocfg/i18n": "^2.1.585",
+    "@djangocfg/typescript-config": "^2.1.585",
+    "@djangocfg/ui-core": "^2.1.585",
+    "@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",
+    "storybook": "^10.5.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.10"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/AssistantChat.tsx

@@ -0,0 +1,115 @@
+'use client';
+
+import { useMemo, useRef, type ReactNode } from 'react';
+
+import {
+  Chat,
+  ChatTranscript,
+  DataRenderer,
+  type ChatAdapter,
+  type ChatCapabilities,
+  type ChatMessage,
+  type PartRenderProps,
+} from '@djangocfg/widget-chat';
+import { Response } from '@djangocfg/widget-chat/content';
+
+import type { SessionNotice } from './stream/useSession';
+import { createWholeTranscriptSpeech } from './composer/wholeTranscript';
+import { AssistantComposer } from './composer/AssistantComposer';
+import { ComposerHelp } from './composer/ComposerHelp';
+import { MessageFooter } from './messages/MessageFooter';
+import { NoticeLine } from './messages/NoticeLine';
+
+/** Draws one `data` part of a known `kind`. Return `undefined` to hand the part to the widget's own renderer. */
+export type DataPartRenderer = (data: unknown, props: PartRenderProps) => ReactNode | undefined;
+
+/** The dictation language the composer offers a picker for: a BCP-47 tag the host remembers. */
+export interface SpeechLanguage {
+  value: string;
+  onChange: (language: string) => void;
+}
+
+interface Props {
+  adapter: ChatAdapter;
+  /** Example prompts shown in an empty chat. */
+  suggestions: string[];
+  /** The room on screen: `id` changes when the thread is reloaded (reconcile, clear), which reseeds the transcript. */
+  conversation?: { id?: string; history: readonly ChatMessage[] };
+  /** The host's drawing of structured parts, by `kind` (for example `film_cards`). Unknown kinds fall through to the widget. */
+  dataRenderers?: Readonly<Record<string, DataPartRenderer>>;
+  /** Dictation language and its picker (the microphone menu). Absent: the browser's default engine with the widget's default language. */
+  speech?: SpeechLanguage;
+  /** A plain line above the composer: reconnecting, or a stalled run with its Retry (`onRetry`). */
+  notice?: SessionNotice | null;
+  onRetry?: () => void;
+  /** Raise to put the caret in the field (the panel was just opened on a device with a keyboard). Not applied on first render. */
+  focusWhen?: boolean;
+  /** A keyboard device: after a send the caret goes back to the field (to the microphone when the send ended a dictation). */
+  refocus?: boolean;
+  className?: string;
+}
+
+const EMPTY_ROOM = { history: [] } as const;
+const NO_RENDERERS: Readonly<Record<string, DataPartRenderer>> = {};
+
+/**
+ * The chat: the framework widget with markdown text, the host's structured parts, message actions, and the full composer (dictation with its language menu,
+ * recall of sent prompts with the arrow keys, an unsent draft that survives a reload). The widget's packaged layout shows only a bare composer, so the layout
+ * is composed here from its own primitives: every behaviour is the widget's, nothing is re-implemented.
+ */
+export function AssistantChat({ adapter, suggestions, conversation = EMPTY_ROOM, dataRenderers = NO_RENDERERS, speech, notice, onRetry, focusWhen, refocus, className }: Props) {
+  const renderers = useMemo(
+    () => ({
+      text: ({ part }: PartRenderProps) => (part.type === 'text' ? <Response>{part.text}</Response> : null),
+      data: (props: PartRenderProps) => {
+        const { part } = props;
+        if (part.type === 'data') {
+          const drawn = dataRenderers[part.kind]?.(part.data, props);
+          if (drawn !== undefined) return drawn;
+        }
+        return DataRenderer(props);
+      },
+    }),
+    [dataRenderers],
+  );
+  // The language is read at each start, through a ref: the capability must not be rebuilt when the picker changes.
+  const language = useRef(speech?.value);
+  language.current = speech?.value;
+  const voice = useMemo(() => createWholeTranscriptSpeech(() => language.current ?? (typeof navigator === 'undefined' ? 'en-US' : navigator.language)), []);
+  const capabilities = useMemo<ChatCapabilities>(
+    () => ({ suggestions: { items: suggestions.map((prompt, index) => ({ id: `s${index}`, title: prompt, prompt })) }, ...(voice ? { voice } : {}) }),
+    [suggestions, voice],
+  );
+  const slots = useMemo(
+    () => ({
+      // Progress while a run streams is the widget's own pending row inside the transcript; a second line under the composer repeated it and
+      // moved the input. Only a rare notice (reconnecting, stalled) uses this slot.
+      footer: (
+        <>
+          {notice ? <NoticeLine notice={notice} onRetry={onRetry} /> : null}
+          <ComposerHelp />
+        </>
+      ),
+    }),
+    [notice, onRetry],
+  );
+  return (
+    <Chat
+      adapter={adapter}
+      capabilities={capabilities}
+      renderers={renderers}
+      conversation={conversation}
+      slots={slots}
+      className={`assistant-chat flex h-full min-h-0 flex-col ${className ?? ''}`}
+      body={{
+        kind: 'custom',
+        children: (
+          <>
+            <ChatTranscript footer={(message) => <MessageFooter message={message} />} />
+            <AssistantComposer speech={speech} draftRoom={conversation.id ?? 'assistant'} focusWhen={focusWhen} refocus={refocus} />
+          </>
+        ),
+      }}
+    />
+  );
+}

package/src/Host.tsx

@@ -0,0 +1,57 @@
+'use client';
+
+import { createContext, useContext, useEffect, useLayoutEffect, useMemo, useRef, type ReactNode } from 'react';
+import { createPortal } from 'react-dom';
+
+/**
+ * One mounted chat, many places. The chat is rendered through a portal into one detached element (`AssistantPortal`); a surface (`AssistantSlot`) attaches that
+ * element where it is visible and parks it when it unmounts. Navigating or switching surface while a run streams therefore never unmounts the chat:
+ * nothing is aborted and the thread state is not rebuilt. `AssistantHostProvider` wraps the page tree once, in the layout.
+ */
+interface HostValue {
+  element: HTMLElement;
+  park: HTMLElement;
+}
+const HostContext = createContext<HostValue | null>(null);
+
+export function AssistantHostProvider({ children }: { children: ReactNode }) {
+  // Browser only: on the server there is no element, and slots render empty.
+  const value = useMemo<HostValue | null>(() => {
+    if (typeof document === 'undefined') return null;
+    const element = document.createElement('div');
+    element.className = 'h-full min-h-0';
+    const park = document.createElement('div');
+    park.hidden = true;
+    park.appendChild(element);
+    return { element, park };
+  }, []);
+
+  useEffect(() => {
+    if (!value) return;
+    document.body.appendChild(value.park);
+    return () => value.park.remove();
+  }, [value]);
+
+  return <HostContext.Provider value={value}>{children}</HostContext.Provider>;
+}
+
+/** Renders the chat (`children`) into the host element. Mount it once, for a signed-in viewer, inside the provider. */
+export function AssistantPortal({ children }: { children: ReactNode }) {
+  const host = useContext(HostContext);
+  return host ? createPortal(children, host.element) : null;
+}
+
+/** A place that shows the chat: an empty box the chat element is moved into while the slot is mounted. */
+export function AssistantSlot({ className }: { className?: string }) {
+  const host = useContext(HostContext);
+  const box = useRef<HTMLDivElement>(null);
+  useLayoutEffect(() => {
+    if (!host || !box.current) return;
+    const place = box.current;
+    place.appendChild(host.element);
+    return () => {
+      if (host.element.parentElement === place) host.park.appendChild(host.element);
+    };
+  }, [host]);
+  return <div ref={box} className={className} />;
+}

package/src/composer/AssistantComposer.tsx

@@ -0,0 +1,19 @@
+'use client';
+
+import { ChatComposer } from '@djangocfg/widget-chat';
+
+import { ComposerBehaviour } from './ComposerBehaviour';
+import { useSentPrompts } from './useSentPrompts';
+
+interface Props {
+  speech?: { value: string; onChange: (language: string) => void };
+  draftRoom: string;
+  focusWhen?: boolean;
+  refocus?: boolean;
+}
+
+/** The widget's composer with its recall fed from the live transcript and our behaviour mounted inside. Must sit inside the chat. */
+export function AssistantComposer({ speech, draftRoom, focusWhen, refocus }: Props) {
+  const history = useSentPrompts();
+  return <ChatComposer history={history} speechLanguage={speech} draftRoom={draftRoom} toolbarEnd={<ComposerBehaviour focusWhen={focusWhen} refocus={refocus} />} />;
+}

package/src/composer/ComposerBehaviour.tsx

@@ -0,0 +1,84 @@
+'use client';
+
+import { useCallback, useEffect, useRef } from 'react';
+
+import { useHotkey } from '@djangocfg/ui-core/hooks';
+import { useComposer } from '@djangocfg/widget-chat';
+
+import { useCaretFocus } from './useCaretFocus';
+import { useComposerNodes } from './useComposerNodes';
+import { DICTATION_TOGGLE } from './keys';
+import { useFocusArea } from './useFocusArea';
+import { useGracefulStop } from './useGracefulStop';
+import { useHeightFloor } from './useHeightFloor';
+import { useRecording } from './useRecording';
+
+interface Props {
+  focusWhen?: boolean;
+  refocus?: boolean;
+}
+
+/**
+ * What the widget's composer lacks, mounted inside it (the `toolbarEnd` slot, the only place the draft's `send` is reachable). Renders nothing.
+ *
+ * While dictation is on, Enter and Escape mean the same wherever the focus is: pressing the microphone leaves the focus on that button, so Enter re-pressed it and
+ * merely stopped the recording, and the field's own Enter handling works only with the caret in the field. Enter stops the recording and sends what was heard;
+ * Escape stops it and keeps the text. The field's height and the caret are handled by the hooks beside this file.
+ */
+export function ComposerBehaviour({ focusWhen = false, refocus = false }: Props) {
+  const marker = useRef<HTMLSpanElement>(null);
+  const nodes = useComposerNodes(marker);
+  const { field } = nodes;
+  const composer = useComposer();
+  const latest = useRef(composer);
+  latest.current = composer;
+
+  const recording = useRecording(nodes);
+  useHeightFloor(nodes, recording);
+  useFocusArea(nodes, marker, refocus);
+  useCaretFocus(nodes, { focusWhen, refocus, recording, onSend: composer.onSend });
+
+  // Waits for the words still being recognised, then commits them into the draft; sending reads the draft after that.
+  const stop = useGracefulStop(nodes, recording, useCallback(() => latest.current.draft.text, []));
+
+  const sendWhenStopped = useCallback(() => {
+    stop(() => {
+      if (latest.current.canSend) latest.current.send();
+    });
+  }, [stop]);
+
+  // In the field the widget's own Enter would send at once and cut the dictation; this capture listener takes the key first, so the send waits like the stop does.
+  useEffect(() => {
+    const node = field();
+    if (!recording || !node) return;
+    const take = (event: KeyboardEvent) => {
+      if (event.key !== 'Enter' || event.shiftKey || event.altKey || event.ctrlKey || event.metaKey || event.isComposing) return;
+      event.preventDefault();
+      event.stopImmediatePropagation();
+      sendWhenStopped();
+    };
+    node.addEventListener('keydown', take, true);
+    return () => node.removeEventListener('keydown', take, true);
+  }, [recording, field, sendWhenStopped]);
+
+  // Elsewhere (the focus stayed on the microphone button) the same Enter comes through the hotkey.
+  useHotkey(
+    'enter',
+    (event) => {
+      if (event.target instanceof HTMLTextAreaElement) return;
+      sendWhenStopped();
+    },
+    { enabled: recording, inInput: true, preventDefault: true },
+  );
+  // One key to start and to stop, wherever the focus is. Stopping waits like every other stop; starting is the microphone's own press.
+  useHotkey(DICTATION_TOGGLE, () => (recording ? stop() : nodes.mic()?.click()), { inInput: true, preventDefault: true });
+  useHotkey('escape', () => stop(), { enabled: recording, inInput: true, preventDefault: true });
+
+  // Assistive technology and password managers learn the key from the button itself.
+  const { mic } = nodes;
+  useEffect(() => {
+    mic()?.setAttribute('aria-keyshortcuts', 'Meta+D Control+D');
+  }, [mic, recording]);
+
+  return <span ref={marker} hidden />;
+}

package/src/composer/ComposerHelp.tsx

@@ -0,0 +1,46 @@
+'use client';
+
+import { Kbd, Popover, PopoverContent, PopoverTrigger } from '@djangocfg/ui-core/components';
+import { formatHotkey } from '@djangocfg/ui-core/hooks';
+
+import { useAssistantCopy } from '../i18n';
+import { DICTATION_TOGGLE } from './keys';
+
+/** The keys the composer answers to, in the order a person needs them. `combo` is a hotkey string, drawn for the viewer's system (⌘ on Apple, Ctrl elsewhere). */
+function useRows() {
+  const copy = useAssistantCopy();
+  return [
+    { combo: DICTATION_TOGGLE, text: copy.helpDictate },
+    { combo: 'enter', text: copy.helpSend },
+    { combo: 'escape', text: copy.helpStop },
+    { combo: 'arrowup', text: copy.helpRecall },
+    { combo: 'shift+enter', text: copy.helpNewline },
+  ];
+}
+
+/** A quiet "Help" under the composer; pressing it opens the short list of keys. */
+export function ComposerHelp() {
+  const copy = useAssistantCopy();
+  const rows = useRows();
+  return (
+    <div className="px-4 pb-1 text-end">
+      <Popover>
+        <PopoverTrigger asChild>
+          <button type="button" className="rounded px-1 text-xs text-muted-foreground underline-offset-2 outline-none hover:text-foreground hover:underline focus-visible:ring-2 focus-visible:ring-ring">
+            {copy.helpLabel}
+          </button>
+        </PopoverTrigger>
+        <PopoverContent side="top" align="end" className="w-72 p-3">
+          <ul className="space-y-2">
+            {rows.map(({ combo, text }) => (
+              <li key={combo} className="flex items-start justify-between gap-3 text-sm">
+                <span className="text-muted-foreground">{text}</span>
+                <Kbd className="shrink-0">{formatHotkey(combo)}</Kbd>
+              </li>
+            ))}
+          </ul>
+        </PopoverContent>
+      </Popover>
+    </div>
+  );
+}

package/src/composer/keys.ts

@@ -0,0 +1,2 @@
+/** Starts or stops dictation from anywhere in the composer (`mod` is ⌘ on Apple systems and Ctrl elsewhere). */
+export const DICTATION_TOGGLE = 'mod+d';

package/src/composer/useCaretFocus.ts

@@ -0,0 +1,49 @@
+import { useEffect, useRef } from 'react';
+
+import type { ComposerNodes } from './useComposerNodes';
+
+interface Options {
+  /** Each time this turns true the caret goes to the field (the panel was opened on a device with a keyboard); never on first render. */
+  focusWhen: boolean;
+  /** A keyboard device: after a send the caret returns to the field, or to the microphone when the send ended a dictation (so Enter starts the next one). */
+  refocus: boolean;
+  recording: boolean;
+  /** The draft's send listener registry. */
+  onSend: (listener: () => void) => () => void;
+}
+
+/** Where the caret is after the panel opens and after a send. Both are for keyboards only: on a phone either would raise the keyboard over the answer. */
+export function useCaretFocus({ mic, field }: ComposerNodes, { focusWhen, refocus, recording, onSend }: Options): void {
+  const wasOn = useRef(focusWhen);
+  useEffect(() => {
+    if (focusWhen && !wasOn.current) {
+      const node = field();
+      node?.focus();
+      node?.setSelectionRange(node.value.length, node.value.length);
+    }
+    wasOn.current = focusWhen;
+  }, [focusWhen, field]);
+
+  // Read through a ref because the send listener runs before the widget ends the dictation.
+  const dictating = useRef(false);
+  useEffect(() => {
+    if (recording) {
+      dictating.current = true;
+      return;
+    }
+    // A send that follows the stop (Enter outside the field waits 60 ms) still counts as ending a dictation; a later one does not.
+    const id = window.setTimeout(() => {
+      dictating.current = false;
+    }, 400);
+    return () => window.clearTimeout(id);
+  }, [recording]);
+
+  useEffect(() => {
+    if (!refocus) return;
+    return onSend(() => {
+      const next = dictating.current ? mic() : field();
+      dictating.current = false;
+      window.setTimeout(() => next?.focus(), 0);
+    });
+  }, [refocus, onSend, mic, field]);
+}

package/src/composer/useComposerNodes.ts

@@ -0,0 +1,14 @@
+import { useCallback, type RefObject } from 'react';
+
+/**
+ * The composer's own elements, found from a marker rendered inside it. The widget keeps the field and the microphone private, so the DOM is the only route; the
+ * selectors are the widget's classes (`composer-box`, `composer-mic`), which its stylesheet also relies on.
+ */
+export function useComposerNodes(marker: RefObject<HTMLElement | null>) {
+  const box = useCallback(() => marker.current?.closest('.composer-box') ?? null, [marker]);
+  const mic = useCallback(() => box()?.querySelector<HTMLButtonElement>('.composer-mic') ?? null, [box]);
+  const field = useCallback(() => box()?.querySelector<HTMLTextAreaElement>('textarea') ?? null, [box]);
+  return { mic, field };
+}
+
+export type ComposerNodes = ReturnType<typeof useComposerNodes>;

package/src/composer/useFocusArea.ts

@@ -0,0 +1,29 @@
+import { useEffect } from 'react';
+
+import type { ComposerNodes } from './useComposerNodes';
+
+const INTERACTIVE = 'button, a, input, textarea, select, [role="button"], [role="dialog"], [data-radix-popper-content-wrapper]';
+
+/**
+ * A press on the empty space around the composer (its column, and the padding of the chat under the transcript) puts the caret in the field, so the target is the whole
+ * strip and not only the box. A press on a control, or anywhere in the transcript, is left alone. Keyboard devices only (`enabled`): on a phone it raises the keyboard.
+ */
+export function useFocusArea({ field }: ComposerNodes, marker: { current: HTMLElement | null }, enabled: boolean): void {
+  useEffect(() => {
+    const column = marker.current?.closest<HTMLElement>('.chat-column');
+    const root = marker.current?.closest<HTMLElement>('.assistant-chat');
+    if (!enabled || !column || !root) return;
+    const take = (event: MouseEvent) => {
+      const target = event.target as HTMLElement;
+      // The root itself is its padding strip; inside it only the composer column counts, never the transcript.
+      const inStrip = column.contains(target) || target === root;
+      if (!inStrip || target.closest(INTERACTIVE)) return;
+      event.preventDefault();
+      const node = field();
+      node?.focus();
+      node?.setSelectionRange(node.value.length, node.value.length);
+    };
+    root.addEventListener('mousedown', take);
+    return () => root.removeEventListener('mousedown', take);
+  }, [enabled, field, marker]);
+}

package/src/composer/useGracefulStop.ts

@@ -0,0 +1,63 @@
+import { useCallback, useEffect, useRef } from 'react';
+
+import type { ComposerNodes } from './useComposerNodes';
+
+/**
+ * The microphone stays open after a stop is asked for, until the words stop arriving. Recognition runs behind the voice: the engine reports a phrase a few hundred
+ * milliseconds after it was said, and the widget's stop closes the engine at once and drops what is still on its way. So the stop waits for the field to stay unchanged for
+ * `QUIET_MS` (but at least that long, and never past `PATIENCE_MS`); the stop is then the widget's own, and its commit puts what was heard into the draft.
+ */
+export const QUIET_MS = 450;
+export const PATIENCE_MS = 2500;
+const POLL_MS = 80;
+
+/**
+ * `stop(after)` ends the dictation after the grace period, then runs `after` once the transcript has reached the draft. The microphone button's own press while
+ * recording goes through the same wait (a capture listener takes the press first and re-issues it later), so every way to stop loses nothing.
+ */
+export function useGracefulStop({ mic }: ComposerNodes, recording: boolean, draftText: () => string): (after?: () => void) => void {
+  const waiting = useRef(false);
+  const ours = useRef(false);
+
+  const stop = useCallback(
+    (after?: () => void) => {
+      if (waiting.current) return;
+      waiting.current = true;
+      const began = Date.now();
+      let seen = draftText();
+      let changed = began;
+      const settle = () => {
+        const now = Date.now();
+        const text = draftText();
+        if (text !== seen) {
+          seen = text;
+          changed = now;
+        }
+        if (now - changed < QUIET_MS && now - began < PATIENCE_MS) return void window.setTimeout(settle, POLL_MS);
+        ours.current = true;
+        mic()?.click();
+        ours.current = false;
+        waiting.current = false;
+        // The widget commits the transcript on that click; the draft holds it one render later.
+        if (after) window.setTimeout(after, 80);
+      };
+      window.setTimeout(settle, POLL_MS);
+    },
+    [mic, draftText],
+  );
+
+  useEffect(() => {
+    const button = mic();
+    if (!recording || !button) return;
+    const take = (event: Event) => {
+      if (ours.current) return;
+      event.preventDefault();
+      event.stopImmediatePropagation();
+      stop();
+    };
+    button.addEventListener('click', take, true);
+    return () => button.removeEventListener('click', take, true);
+  }, [recording, mic, stop]);
+
+  return stop;
+}

package/src/composer/useHeightFloor.ts

@@ -0,0 +1,27 @@
+import { useEffect } from 'react';
+
+import type { ComposerNodes } from './useComposerNodes';
+
+/**
+ * While `active`, the field may only grow. Dictation arrives in bursts and the engine revises its guess, so the height would otherwise go up and down with each one:
+ * the tallest height seen is kept as a floor, and the floor goes when `active` ends.
+ */
+export function useHeightFloor({ field }: ComposerNodes, active: boolean): void {
+  useEffect(() => {
+    const node = field();
+    if (!active || !node) return;
+    let tallest = 0;
+    const watch = new ResizeObserver(() => {
+      const height = node.offsetHeight;
+      if (height > tallest) {
+        tallest = height;
+        node.style.minHeight = `${height}px`;
+      }
+    });
+    watch.observe(node);
+    return () => {
+      watch.disconnect();
+      node.style.minHeight = '';
+    };
+  }, [active, field]);
+}