@djangocfg/widget-chat 0.1.1

package/src/composer/field/input.tsx

@@ -0,0 +1,214 @@
+import {
+  useCallback,
+  useRef,
+  type ChangeEvent,
+  type ClipboardEvent,
+  type CSSProperties,
+  type KeyboardEvent,
+  type Ref,
+} from "react";
+
+import { FIELD_SIZING, useAutosize } from "./use-autosize";
+import { useComposer } from "../context";
+
+export interface ComposerInputProps {
+  readonly placeholder?: string;
+  /** The accessible name. Copy is the host's — this package carries no locales. */
+  readonly label: string;
+  readonly className?: string;
+  /** Rows to grow to before scrolling. */
+  readonly maxRows?: number;
+  /**
+   * The textarea node, for a host that must reach it.
+   *
+   * Exists for the two things only the element can do: `focus()`, and placing
+   * the CARET. History recall restores a caret position along with the text,
+   * and there is no ref-free way to call `setSelectionRange`.
+   *
+   * A ref rather than an `onFocus`-style prop: it is React's own escape hatch
+   * for "I need the element", it adds no behaviour here, and it cannot grow
+   * into a second way of driving the input.
+   */
+  readonly ref?: Ref<HTMLTextAreaElement>;
+  /**
+   * Runs BEFORE this component's own Enter handling, and can veto it with
+   * `preventDefault()`.
+   *
+   * The seam anything claiming a key needs — recall claims the arrows, and a
+   * host popup over the textarea would claim Enter and Escape.
+   *
+   * The protocol is `defaultPrevented`, not an `isClaimed` prop, and two
+   * references independently landed on it: Vercel's `prompt-input.tsx` calls
+   * the external handler first and returns early if it prevented default, and
+   * the archive's `ComposerRichTextarea.tsx:172` does the same. It is the
+   * better shape because the veto travels with the event — a boolean prop would
+   * be a second source of truth, updated one render later than the keystroke
+   * that needs it.
+   *
+   * Deliberately the only escape hatch, and never a general `...props` spread:
+   * a spread would let a host quietly re-bind `onChange`, `value` or `onPaste`
+   * and take ownership of state this component holds, which is the exact door
+   * the 83-prop predecessor left open. A host building a menu here also needs
+   * the caret and an `aria-*` channel; both existed for the mention menu and
+   * left with it, and should come back together or not at all.
+   */
+  readonly onKeyDown?: (event: KeyboardEvent<HTMLTextAreaElement>) => void;
+}
+
+/**
+ * Rows to grow to before the box scrolls internally.
+ *
+ * Eight, matching both references. Twelve turned a long paste into a wall that
+ * pushed the transcript off screen — the composer took the room the answer
+ * needs, which is the wrong trade for a surface whose job is reading replies.
+ */
+const DEFAULT_MAX_ROWS = 8;
+
+/**
+ * The text area.
+ *
+ * The KEYBOARD and the clipboard: Enter-to-send, IME composition, and the
+ * paste rule. They belong together because they all reason about the same
+ * thing — what a keystroke means in this field — and they all need the same
+ * ref.
+ *
+ * Autosize used to live here too and does not any more (`use-autosize.ts`). It
+ * shares the node and nothing else: it reasons about PIXELS, carries its own
+ * feature-detection constant, and reading it while looking for a key handler
+ * was pure noise. The file was over its 300-line budget, and the budget's own
+ * comment names the wrong fix — raising the limit — so it was split instead.
+ */
+export function ComposerInput({
+  placeholder,
+  label,
+  className,
+  maxRows = DEFAULT_MAX_ROWS,
+  ref: externalRef,
+  onKeyDown: hostKeyDown,
+}: ComposerInputProps) {
+  const { draft, setText, handlePaste, send, canSend } = useComposer();
+  const ref = useRef<HTMLTextAreaElement | null>(null);
+
+  /**
+   * Fill the internal ref (autosize measures through it) and the host's, if
+   * one was passed. A callback rather than handing the host `ref` directly:
+   * the two must both see the node, and a single `ref` prop can only serve one.
+   */
+  const attach = useCallback(
+    (node: HTMLTextAreaElement | null) => {
+      ref.current = node;
+      if (typeof externalRef === "function") externalRef(node);
+      else if (externalRef) externalRef.current = node;
+    },
+    [externalRef],
+  );
+  /**
+   * True between `compositionstart` and `compositionend`. A CJK/IME candidate
+   * window uses Enter to CONFIRM the candidate, and that Enter also reaches
+   * keydown — sending there truncates the word being composed and is the classic
+   * "my Japanese input sends half a sentence" bug. `event.isComposing` covers
+   * most browsers, but Safari has historically cleared it on the confirming
+   * keystroke, so we track the events too and treat either signal as composing.
+   */
+  const composing = useRef(false);
+
+  const multiline = useAutosize(ref, draft.text, maxRows);
+
+  const onChange = useCallback(
+    (event: ChangeEvent<HTMLTextAreaElement>) => {
+      setText(event.target.value);
+    },
+    [setText],
+  );
+
+  const onPaste = useCallback(
+    (event: ClipboardEvent<HTMLTextAreaElement>) => {
+      // The hook owns `preventDefault` and returns whether it consumed the
+      // event; it must NOT be called again or re-implemented here. Long text
+      // landing in both the box and a chip is the failure this prevents.
+      handlePaste(event);
+    },
+    [handlePaste],
+  );
+
+  const onKeyDown = useCallback(
+    (event: KeyboardEvent<HTMLTextAreaElement>) => {
+      // The host first, then its veto. This is the ONLY way a surface outside
+      // this component can claim a key: it renders elsewhere and focus never
+      // leaves the textarea. Recall claims the arrows this way.
+      hostKeyDown?.(event);
+      if (event.defaultPrevented) return;
+
+      if (event.key !== "Enter") return;
+      if (event.shiftKey) return;
+      if (composing.current || event.nativeEvent.isComposing) return;
+      // Modifier chords belong to the OS/host (newline on some platforms), and
+      // claiming them here would make the composer disagree with the textarea.
+      if (event.altKey || event.ctrlKey || event.metaKey) return;
+      // Before the guard: a plain Enter must never insert a newline on the send
+      // path, including when the draft is empty and nothing is sent.
+      event.preventDefault();
+      if (!canSend) return;
+      send();
+    },
+    [canSend, send, hostKeyDown],
+  );
+
+  const onCompositionStart = useCallback(() => {
+    composing.current = true;
+  }, []);
+
+  const onCompositionEnd = useCallback(() => {
+    composing.current = false;
+  }, []);
+
+  return (
+    <textarea
+      ref={attach}
+      className={className}
+      value={draft.text}
+      placeholder={placeholder}
+      aria-label={label}
+      rows={1}
+      /*
+        Has the draft outgrown ONE line?
+
+        As DATA, because CSS cannot ask it: the answer decides whether a SIBLING
+        (the control row) keeps sharing this row, and no container query or
+        `:has()` can read another element's measured height. A host styles
+        `[data-multiline]`; the package chooses no layout.
+
+        MEASURED, not `text.includes("\\n")`. A single long line that SOFT-WRAPS
+        has no newline in it and is the common case — it is what a user types.
+        `useAutosize` already knows the height, so the flag comes from there
+        rather than from a second measurement that could disagree with it.
+      */
+      data-multiline={multiline || undefined}
+      /*
+       * Autosize, declared rather than measured — where the engine can.
+       *
+       * Inline rather than a class because this package ships no CSS and
+       * `className` belongs to the host: a host that styles the field must not
+       * have to know that the cap is `maxRows`, and the two numbers cannot be
+       * allowed to drift apart. `lh` is the row unit, so the cap stays in rows
+       * whatever the host's line-height is.
+       *
+       * Empty on browsers without support, where the effect above sizes the box
+       * instead. Never both — a written `height` would override this.
+       */
+      // `fieldSizing` is newer than the pinned csstype, so the cast is the
+      // property being real and the types being behind — not a shape being
+      // forced. Remove it once csstype carries the property.
+      style={
+        FIELD_SIZING
+          ? ({ fieldSizing: "content", maxHeight: `${maxRows}lh` } as CSSProperties)
+          : undefined
+      }
+      onChange={onChange}
+      onPaste={onPaste}
+      onKeyDown={onKeyDown}
+      onCompositionStart={onCompositionStart}
+      onCompositionEnd={onCompositionEnd}
+    />
+  );
+}

package/src/composer/field/keys.ts

@@ -0,0 +1,44 @@
+import type { KeyboardEvent } from "react";
+
+export interface ComposerKeysOptions {
+  readonly recall: {
+    reset(): void;
+    onKeyDown(event: KeyboardEvent<HTMLTextAreaElement>): void;
+  };
+  readonly draftText: string;
+  /**
+   * Enter is about to send the draft.
+   *
+   * The resolver decides WHICH key sends; it does not know what the send means
+   * to anyone else. The caller announces it.
+   */
+  readonly onSending?: () => void;
+}
+
+/**
+ * One keyboard, one claimant: recall.
+ *
+ * It stays a resolver rather than folding into the component because the order
+ * of the two things that happen on Enter is the whole subtlety, and it is
+ * testable here without a DOM. Two menus used to claim keys ahead of recall;
+ * both left with the product that supplied their vocabularies.
+ */
+export function composerKeyDown(
+  event: KeyboardEvent<HTMLTextAreaElement>,
+  options: ComposerKeysOptions,
+): void {
+  const { recall, draftText, onSending } = options;
+
+  // Reset BEFORE the composer clears the draft: after it there is nothing left
+  // to record, and a ladder left mid-walk makes the next ArrowUp resume from
+  // wherever the last one stopped rather than from the newest prompt.
+  // `onSending` fires here, BEFORE the send, and that timing is the point: a
+  // transcript-derived ladder only moves when history is re-read, which is not
+  // until the turn lands, and ArrowUp must reach what was just sent before then.
+  // Announcing from the send path instead would reopen that gap.
+  if (event.key === "Enter" && !event.shiftKey && draftText.trim() !== "") {
+    onSending?.();
+    recall.reset();
+  }
+  recall.onKeyDown(event);
+}

package/src/composer/field/use-autosize.ts

@@ -0,0 +1,134 @@
+import { useCallback, useLayoutEffect, useRef, useState, type RefObject } from "react";
+
+/**
+ * Can the browser size a field to its own content?
+ *
+ * When it can, autosize is a CSS declaration and the measure-and-write cycle
+ * below is dead weight — worse than dead, since writing `height` in JS overrides
+ * what `field-sizing` computed. When it cannot (Firefox, Safari before 26) the
+ * effect is the only implementation, so it stays.
+ *
+ * Read ONCE at module scope, not per keystroke: it is a property of the engine
+ * and cannot change while the page is loaded. Guarded for SSR, where there is no
+ * `CSS` object at all and the JS path is the safe assumption.
+ */
+export const FIELD_SIZING =
+  typeof CSS !== "undefined" &&
+  typeof CSS.supports === "function" &&
+  CSS.supports("field-sizing", "content");
+
+/**
+ * Grow a textarea with its content, up to `maxRows`, then scroll.
+ *
+ * Beside `input.tsx` rather than inside it: the two share the node and nothing
+ * else. `input.tsx` is a KEYBOARD component — paste, Enter-to-send and IME
+ * composition all reason about what a keystroke means — while this measures
+ * pixels and carries a module-scope feature-detection constant of its own.
+ *
+ * Runs as a layout effect, not an effect: the box must reach its final height
+ * in the same paint as the text, or every keystroke shows one frame at the old
+ * height. Keyed on the text so a PROGRAMMATIC change resizes too — sending
+ * clears the draft, "attach as text" fills it, and neither is a keystroke.
+ */
+export function useAutosize(
+  ref: RefObject<HTMLTextAreaElement | null>,
+  text: string,
+  maxRows: number,
+): boolean {
+  // More than one line, INCLUDING a soft-wrapped long one — which
+  // `text.includes("\n")` cannot see and is what users actually type.
+  const [multiline, setMultiline] = useState(false);
+  // The field's width while the flag is OFF — the one width the wrap question
+  // may be asked at. Learned from the field itself rather than configured, so a
+  // host that lays the composer out differently needs no second number here.
+  const compactWidth = useRef<number | null>(null);
+
+  const resize = useCallback(() => {
+    const node = ref.current;
+    if (node === null) return;
+
+    // Multiline, measured. Before the `field-sizing` return: the flag is about
+    // rendered height either way, and after it this never runs on a modern
+    // browser.
+    //
+    // Asked as a ROW COUNT rather than as a height comparison. `scrollHeight`
+    // is an integer, so a fractional line height never divides evenly into it
+    // and any "taller than one line" test needs a tolerance — the sort of
+    // constant that is invisibly wrong on the one browser nobody checked.
+    // Rounding the quotient puts the tolerance where it belongs: half a row,
+    // whatever a row happens to measure.
+    //
+    // `scrollHeight` includes the field's own vertical padding, so the inset
+    // comes off first — without it EVERY field reports as multiline.
+    const probe = window.getComputedStyle(node);
+    const rowHeight = Number.parseFloat(probe.lineHeight);
+    if (!Number.isNaN(rowHeight) && rowHeight > 0) {
+      const inset =
+        Number.parseFloat(probe.paddingTop) + Number.parseFloat(probe.paddingBottom);
+      const rowsAt = () => Math.round((node.scrollHeight - inset) / rowHeight);
+      // Measured at the COMPACT width, always — never at the current one.
+      //
+      // The flag widens the field, so asking a wide field "do you wrap?" asks
+      // about a width the answer itself created: the text fits, the flag drops,
+      // the field narrows, the text wraps, the flag returns. Measured at 19
+      // flips over 36 keystrokes, one per character.
+      //
+      // `compactWidth` is the width the field has while the flag is off, so the
+      // question is always the stable one: does this text fit on one line THERE.
+      const compact = compactWidth.current;
+      if (compact === null || node.getBoundingClientRect().width <= compact) {
+        compactWidth.current = node.getBoundingClientRect().width;
+        setMultiline(rowsAt() > 1);
+      } else {
+        const restore = node.style.width;
+        node.style.width = `${compact}px`;
+        const wraps = rowsAt() > 1;
+        node.style.width = restore;
+        setMultiline(wraps);
+      }
+    }
+
+    // The browser already sized the box from its content — measuring and
+    // writing a pixel height on top would fight it, and writing `height` at all
+    // defeats `field-sizing` outright.
+    if (FIELD_SIZING) return;
+    // Collapse first: scrollHeight never shrinks while the box is already tall
+    // enough to hold the old text, so measuring without this makes the textarea
+    // a one-way ratchet that only ever grows.
+    node.style.height = "auto";
+    const style = window.getComputedStyle(node);
+    const lineHeight = Number.parseFloat(style.lineHeight);
+    const vertical =
+      Number.parseFloat(style.paddingTop) +
+      Number.parseFloat(style.paddingBottom) +
+      Number.parseFloat(style.borderTopWidth) +
+      Number.parseFloat(style.borderBottomWidth);
+    // `lineHeight: normal` parses to NaN; then there is no row unit to cap by,
+    // and an unbounded box beats a box collapsed to zero.
+    const cap = Number.isNaN(lineHeight) ? Number.POSITIVE_INFINITY : lineHeight * maxRows + vertical;
+    const next = Math.min(node.scrollHeight, cap);
+    node.style.height = `${next}px`;
+    node.style.overflowY = node.scrollHeight > cap ? "auto" : "hidden";
+  }, [ref, maxRows]);
+
+  useLayoutEffect(resize, [resize, text]);
+
+  /**
+   * Follow the caret once the field scrolls internally.
+   *
+   * The browser does this for typing but NOT for a programmatic write, which is
+   * what dictation is — `setText` from a speech callback left the box frozen
+   * while the transcript grew past it.
+   */
+  useLayoutEffect(() => {
+    const node = ref.current;
+    if (node === null) return;
+    if (node.scrollHeight <= node.clientHeight) return;
+    // Only with the caret at the end: mid-text it would yank the view away from
+    // what the user is editing.
+    if (node.selectionEnd !== node.value.length) return;
+    node.scrollTop = node.scrollHeight;
+  }, [ref, text]);
+
+  return multiline;
+}

package/src/composer/focus-field.ts

@@ -0,0 +1,27 @@
+/**
+ * Put the caret back in the composer's field, at the END of the draft.
+ *
+ * Two controls need this and neither owns the textarea: the form's padding
+ * (a press on empty space means "keep typing") and the tool menu (a pick is a
+ * statement of intent, and the sentence naming its object comes next). The
+ * field's own ref is deliberately local to `ComposerField`, so the shared route
+ * is the DOM — both callers render inside the same `<form>`.
+ *
+ * Kept in one place because the "caret at the end" half is the part that goes
+ * wrong: `focus()` alone leaves it wherever the browser last had it, which on a
+ * written draft is the beginning.
+ */
+
+/**
+ * Focus the composer's textarea within `root`, caret after the last character.
+ *
+ * A no-op when the field already holds focus — re-running the selection would
+ * fight a caret the user just placed by clicking.
+ */
+export function focusComposerField(root: HTMLElement | null | undefined): void {
+  const field = root?.querySelector("textarea");
+  if (!field || field === document.activeElement) return;
+  field.focus();
+  const end = field.value.length;
+  field.setSelectionRange(end, end);
+}

package/src/composer/index.ts

@@ -0,0 +1,86 @@
+// The input subsystem — its own layer, not a leaf inside primitives/.
+//
+// Measured: the archived chat's composer is 3 200 lines across 21 files and the
+// editor it wraps another 3 191. Seven thousand lines is a subsystem.
+//
+// EDITOR POLICY: textarea first, a richer editor only on a named trigger.
+// Formatting while typing is out of scope; the one structural weakness is that
+// a textarea cannot host a POPUP well, and a mention menu is a popup — so the
+// switch criteria are things a textarea cannot do, never a taste argument.
+//
+// What keeps that swap cheap: mention DETECTION is a pure function of
+// (text, caret) and lives in core/, so it survives the swap untouched. Only the
+// rendering surface is replaced.
+//
+// LAYOUT, grouped by job rather than by artifact kind:
+//   field/     the textarea and everything positioned against its caret
+//   controls/  the row's buttons, which agree on shape through `button.tsx`
+//   tray/      what sits around the draft rather than in it
+//   stories/   the workbench; no product code may import it
+// At the root: the shell, the context all three groups read, and this barrel.
+// A context inside a group would make the other three reach sideways into it.
+//
+// May import: primitives, store, core, utils, content.
+// May NOT import: ui, widgets.
+
+export { Composer } from "./composer";
+export type { ComposerProps } from "./composer";
+export { ComposerButton } from "./controls/button";
+export type { ComposerButtonProps, ComposerButtonTone } from "./controls/button";
+// Exported so a host's `toolbarEnd` control gets the row's ONE tooltip shape
+// rather than reaching for the status bar's.
+export { ComposerTooltip } from "./controls/tooltip";
+export type { ComposerTooltipProps } from "./controls/tooltip";
+export { ComposerInput } from "./field/input";
+export type { ComposerInputProps } from "./field/input";
+export { ComposerField } from "./field/field";
+export type { ComposerFieldProps } from "./field/field";
+export { ComposerPickedTools, PickedToolChip } from "./tray/picked-tools";
+export type { ComposerPickedToolsProps, PickedToolChipProps } from "./tray/picked-tools";
+export { ComposerSend } from "./controls/send";
+export type { ComposerSendProps } from "./controls/send";
+export { ComposerQueue } from "./tray/queue";
+export type { ComposerQueueProps } from "./tray/queue";
+
+// The notice block ABOVE the composer box — composed parts, so a host adds a
+// line or a link in its own JSX rather than asking for a prop.
+export {
+  ComposerBanner,
+  ComposerBannerAction,
+  ComposerBannerActions,
+  ComposerBannerBody,
+  ComposerBannerDescription,
+  ComposerBannerDismiss,
+  ComposerBannerIcon,
+  ComposerBannerTitle,
+} from "./tray/banner";
+export type {
+  ComposerBannerActionProps,
+  ComposerBannerDismissProps,
+  ComposerBannerIconProps,
+  ComposerBannerProps,
+  ComposerBannerTone,
+} from "./tray/banner";
+// A session-control verb in flight. Beside the banner because it renders as
+// one, and above the composer for the same reason.
+export { CommandProgress } from "./tray/command-progress";
+export type { CommandProgressProps } from "./tray/command-progress";
+export { ComposerVoice } from "./controls/voice";
+export type { ComposerVoiceProps } from "./controls/voice";
+export { ComposerThink } from "./controls/think";
+export type { ComposerThinkProps } from "./controls/think";
+// The `+` arsenal. Its sheet is a DIRECTORY beside `controls/` — a filter, a
+// grouped list and their matching rule do not fit one 300-line file, and
+// splitting after the fact is how a file ends up owning three jobs.
+export { ComposerTools } from "./controls/tools";
+export type { ComposerToolsProps } from "./controls/tools";
+export { ToolMenu } from "./tools/menu";
+export type { ToolMenuProps } from "./tools/menu";
+export { ToolRows } from "./tools/rows";
+export type { ToolRowsProps } from "./tools/rows";
+export { LanguageMenu, languageLabel } from "./controls/language-menu";
+export type { LanguageMenuProps } from "./controls/language-menu";
+export { useComposer } from "./context";
+export { useDraftPersistence } from "./use-draft-persistence";
+export { useReplaceText } from "./tray/use-replace-text";
+export type { AskReplace } from "./tray/use-replace-text";

package/src/composer/stories/field.tsx

@@ -0,0 +1,112 @@
+import { useEffect, useRef, useState, type KeyboardEvent } from "react";
+
+import { useRecall } from "../../store";
+import { ComposerInput } from "../field/input";
+import { useComposer } from "../context";
+import { useDraftPersistence } from "../use-draft-persistence";
+
+/**
+ * The composer's FIELD, for stories: the textarea and ↑/↓ recall over it.
+ *
+ * Separate from `harness.tsx` because the seam is real, not because a limit
+ * forced it: everything here is the field assembly, and the harness above it is
+ * the surrounding chrome.
+ */
+
+const field = "w-full resize-none bg-transparent text-foreground outline-none";
+
+/**
+ * The field wiring, assembled independently of the shipped assembly.
+ *
+ * `field/field.tsx` is the shipped join; this is a SECOND, minimal one — which
+ * is the point. A contract exercised in exactly one place is a contract nobody
+ * has tested against a different caller. If the pieces only fit one way, they
+ * fail to fit here, visibly.
+ */
+export function Field({
+  initialText,
+  sendOnMount,
+  history,
+  draftRoom,
+}: {
+  readonly initialText?: string;
+  readonly sendOnMount: boolean;
+  readonly history?: readonly string[];
+  /** Persist the draft under this room. Absent ⇒ no persistence, as in a host. */
+  readonly draftRoom?: string;
+}) {
+  const { draft, setText, send } = useComposer();
+  const ref = useRef<HTMLTextAreaElement>(null);
+
+  // The ladder GROWS as prompts are sent, because a fixed fixture would show
+  // recall working over data no user action produced — and the interesting bug
+  // (a sent prompt not reaching the ladder) would be invisible.
+  const [sentPrompts, setSentPrompts] = useState<readonly string[]>(history ?? []);
+  const recall = useRecall({ entries: sentPrompts, input: ref, draft, setText });
+
+  // BEFORE the seed: effects run in call order, so a restore lands first and an
+  // explicit `initialText` overrides it. To SEE a restore, pass no seed.
+  useDraftPersistence(draftRoom);
+  useSeed(initialText, setText);
+  // AFTER the seed has reached the store, never beside it: `useSeed` writes
+  // during render, so a send issued in the same pass would post an empty draft
+  // and the story would park on an idle Send having proved nothing.
+  useSendOnce(sendOnMount && draft.text.length > 0, send);
+
+  const onKeyDown = (event: KeyboardEvent<HTMLTextAreaElement>) => {
+    // Record the prompt on Enter, BEFORE the composer clears the draft — after
+    // it there is nothing left to record. A real host derives this from the
+    // transcript (`core/recall/from-transcript.ts`); a story has none.
+    if (event.key === "Enter" && !event.shiftKey && draft.text.trim() !== "") {
+      const text = draft.text;
+      setSentPrompts((prev) => [...prev, text]);
+      recall.reset();
+    }
+    recall.onKeyDown(event);
+  };
+
+  return (
+    <div className="relative grid gap-1">
+      <ComposerInput
+        label="Message"
+        placeholder="Ask anything…"
+        className={field}
+        ref={ref}
+        onKeyDown={onKeyDown}
+      />
+    </div>
+  );
+}
+
+/**
+ * Send exactly once, in an effect, when `ready` first becomes true.
+ *
+ * An effect rather than the render-phase shortcut `useSeed` uses: `send()`
+ * starts a turn and writes to the store, which during render would be a state
+ * update in another component's render pass. Seeding text is idempotent; posting
+ * a turn is not.
+ */
+function useSendOnce(ready: boolean, send: () => void) {
+  const done = useRef(false);
+  useEffect(() => {
+    if (!ready || done.current) return;
+    done.current = true;
+    send();
+  }, [ready, send]);
+}
+
+/**
+ * Seed the field once, in an effect.
+ *
+ * `setText` writes to the composer store, so doing it during render updated
+ * `Composer` from inside `Field`'s render pass — React's
+ * "Cannot update a component while rendering a different component".
+ */
+function useSeed(text: string | undefined, setText: (value: string) => void) {
+  const done = useRef(false);
+  useEffect(() => {
+    if (done.current || text === undefined) return;
+    done.current = true;
+    setText(text);
+  }, [text, setText]);
+}