@textui/chat 0.6.0

package/src/hitl.tsx

@@ -0,0 +1,392 @@
+import type { BoxProps, Rect, RenderOutput } from '@textui/core';
+import {
+  defineComponent, useApp, useFocusScope, useInput, useTheme,
+} from '@textui/core';
+import {
+  Button,
+  Checkbox,
+  Column,
+  MarkdownView,
+  Panel,
+  RadioGroup,
+  Row,
+  TextArea,
+  TextInput,
+} from '@textui/widgets';
+import type { ChatAnswer, ChatPendingInput, ChatQuestion, ChatSendStatus } from './types.js';
+import { useReportMeasure } from './measure.js';
+
+/**
+ * The block that means the agent is stopped, waiting on a person.
+ *
+ * It is the only thing on the screen that is waiting on the reader, so it
+ * takes the focus, traps it, and is answerable without leaving the keyboard.
+ * Rendered as one more bubble in the transcript it scrolls away, and a blocked
+ * agent that has scrolled off is a session that looks merely slow.
+ *
+ * Two kinds, and they are nothing alike:
+ *
+ *   a **tool confirmation** is a yes or a no about a command, with named
+ *   options where the host offers them;
+ *
+ *   a **question** carries no tool call at all. Its prose is the request's own
+ *   message and what is being asked is its questions. Rendering it as a
+ *   confirmation loses the entire request - the choices vanish, the question
+ *   is never shown, and what is left is a heading and an Approve button.
+ */
+
+export interface ChatHitlProps extends BoxProps {
+  input: ChatPendingInput;
+  /**
+   * The answers so far, keyed by question id.
+   *
+   * Owned by whoever mounts this rather than by the block: a host may have an
+   * action for a draft answer precisely because another client can be looking
+   * at the same question, and a value only this box knows is one nobody else
+   * can see. Unused by a tool confirmation.
+   */
+  draft?: Record<string, ChatAnswer>;
+  onDraft?(next: Record<string, ChatAnswer>): void;
+  onApprove(optionId?: string): void;
+  onDeny(): void;
+  onAnswer(answers: Record<string, ChatAnswer>, accepted: boolean): void;
+  /** Leave it up, but give the keyboard back. */
+  onEscape?(): void;
+  /** Where the block is on screen whenever that changes, and `null` once it is gone. */
+  onMeasure?(rect: Rect | null): void;
+}
+
+export const ChatHitl: (props: ChatHitlProps) => RenderOutput =
+  defineComponent<ChatHitlProps>('ChatHitl', (props) => {
+    // It sits above the composer rather than inside it, so it says where it
+    // starts: whoever keeps clear of the composer has to keep clear of this.
+    const { input, draft, onDraft, onApprove, onDeny, onAnswer, onEscape, onMeasure, ...rest } = props;
+    useReportMeasure(onMeasure);
+    const theme = useTheme();
+    // Focused on arrival, and not trapped.
+    //
+    // Trapping read well - the answer is the only thing to do - and it was
+    // wrong. A trap routes every key inside the scope, so while a session was
+    // blocked the transcript could not be scrolled, escape could not leave the
+    // screen, and the block that said `esc read` was the one thing making that
+    // impossible. You approve a command on the strength of what is written
+    // above it, so reading has to stay available while it is up.
+    //
+    // The keys that answer it are global (see `ConfirmRequest`), so they still
+    // work from wherever the reader has gone.
+    useFocusScope({ id: 'chat.hitl', autoFocus: true, restore: true });
+
+    // Wrapped, so that what `onMeasure` reports is the box this occupies
+    // rather than the room inside its border, which is one row lower.
+    return (
+      <Column {...rest}>
+      <Panel
+        title={input.kind === 'toolConfirmation' ? (input.call.confirmationTitle ?? 'The agent asks') : 'The agent asks'}
+        tone="warning"
+        border={theme.border}
+        meta={`${theme.glyphs.warning} waiting on you`}
+      >
+        {input.kind === 'toolConfirmation'
+          ? <ConfirmRequest input={input} onApprove={onApprove} onDeny={onDeny} {...(onEscape ? { onEscape } : {})} />
+          : (
+            <QuestionForm
+              input={input}
+              draft={draft ?? {}}
+              onDraft={onDraft ?? (() => {})}
+              onAnswer={onAnswer}
+              {...(onEscape ? { onEscape } : {})}
+            />
+          )}
+      </Panel>
+      </Column>
+    );
+  });
+
+/** A yes or a no about a command, and the named options the host offered. */
+export const ConfirmRequest = defineComponent<{
+  input: Extract<ChatPendingInput, { kind: 'toolConfirmation' }>;
+  onApprove(optionId?: string): void;
+  onDeny(): void;
+  onEscape?(): void;
+}>('ConfirmRequest', ({ input, onApprove, onDeny, onEscape }) => {
+  const theme = useTheme();
+  const options = input.call.options ?? [];
+
+  // The letters are on the block, not on the application: they only exist
+  // while it is up, and while it is up nothing else wants them.
+  useInput((event) => {
+    if (event.name === 'a') { onApprove(); return true; }
+    if (event.name === 'd') { onDeny(); return true; }
+    if (event.name === 'escape') { onEscape?.(); return true; }
+    const digit = Number(event.name);
+    if (Number.isInteger(digit) && digit >= 1 && digit <= options.length) {
+      onApprove(options[digit - 1]?.id);
+      return true;
+    }
+    return false;
+  }, { global: true });
+
+  return (
+    <Column gap={1}>
+      {input.call.intention ? <MarkdownView content={input.call.intention} quiet /> : null}
+      {input.call.input ? (
+        <Column bg="surfaceAlt" padding={[0, 1]}>
+          <text content={input.call.input} wrap="word" />
+        </Column>
+      ) : null}
+
+      {/* Numbered, because option ids are opaque - a live host sends whole
+          sentences with punctuation in them - so the number is what a person
+          can actually answer with, and it is on the control rather than in a
+          list above it. */}
+      <Row gap={2}>
+        <Button label="Approve" tone="success" variant="solid" icon={theme.glyphs.check} hint="a" autoFocus onPress={() => onApprove()} />
+        <Button label="Deny" tone="danger" icon={theme.glyphs.cross} hint="d" onPress={onDeny} />
+        {options.map((option, i) => (
+          <Button key={option.id} label={option.label} variant="ghost" hint={String(i + 1)} onPress={() => onApprove(option.id)} />
+        ))}
+      </Row>
+    </Column>
+  );
+});
+
+/**
+ * A question, with its questions.
+ *
+ * Every answer names its own kind, keyed by question id, and a required one
+ * left empty is not sendable - accepting with no answers resumes the agent on
+ * the answers it already had, which for a question it has just asked is none.
+ */
+export const QuestionForm = defineComponent<{
+  input: Extract<ChatPendingInput, { kind: 'chatInput' }>;
+  /** The answers so far. Controlled: every change goes out through `onDraft`. */
+  draft: Record<string, ChatAnswer>;
+  onDraft(next: Record<string, ChatAnswer>): void;
+  onAnswer(answers: Record<string, ChatAnswer>, accepted: boolean): void;
+  onEscape?(): void;
+}>('QuestionForm', ({ input, draft, onDraft, onAnswer, onEscape }) => {
+  const theme = useTheme();
+  const app = useApp();
+  const answers = draft;
+
+  const set = (id: string, answer: ChatAnswer | null): void => {
+    const next = { ...answers };
+    if (answer === null) delete next[id];
+    else next[id] = answer;
+    onDraft(next);
+  };
+
+  const missing = input.questions.filter((question) => question.required && !answers[question.id]);
+  const send = (): void => { if (missing.length === 0) onAnswer(answers, true); };
+
+  useInput((event) => {
+    if (event.name === 'escape') { onEscape?.(); return true; }
+    // Enter sends, which is what the hint row under this says while a question
+    // is up - but only from inside the block. A reader who has deliberately
+    // tabbed down to the composer to queue a message is pressing enter at the
+    // composer, and answering the question with it would be the same mistake
+    // in the other direction. The fields that consume enter themselves - a
+    // text input, a checkbox, the Send button - never reach this.
+    if (event.name === 'enter') {
+      const at = app.focus.focused();
+      if (at === null || app.focus.scopeOf(at) !== 'chat.hitl') return false;
+      send();
+      return true;
+    }
+    return false;
+  }, { global: true });
+
+  return (
+    <Column gap={1}>
+      <MarkdownView content={input.message} />
+      {input.questions.map((question, i) => (
+        <QuestionField
+          key={question.id}
+          question={question}
+          answer={answers[question.id] ?? null}
+          // The first field takes the keyboard, and the scope asking for it is
+          // not enough: a scope's `autoFocus` only claims focus when nothing
+          // holds any, and while a question is up the composer holds it. So a
+          // question rendered its field, put `required` beside it, disabled
+          // Send until it was answered - and every key typed at it went into
+          // the composer behind. A control that says it wants focus is the one
+          // thing that takes it off another scope, which is why the
+          // confirmation's Approve button works and this did not.
+          autoFocus={i === 0}
+          onChange={(answer) => set(question.id, answer)}
+          onSubmit={send}
+        />
+      ))}
+
+      <Row gap={2}>
+        <Button
+          label="Send"
+          tone="success"
+          variant="solid"
+          icon={theme.glyphs.check}
+          hint="enter"
+          disabled={missing.length > 0}
+          onPress={() => onAnswer(answers, true)}
+        />
+        <Button label="Decline" variant="ghost" icon={theme.glyphs.cross} onPress={() => onAnswer({}, false)} />
+        {missing.length > 0 ? (
+          <text content={`${theme.glyphs.warning} ${missing.length} still to answer`} fg="warning" />
+        ) : null}
+      </Row>
+    </Column>
+  );
+});
+
+/** One question, rendered by its kind. The kind decides the answer's shape. */
+const QuestionField = defineComponent<{
+  question: ChatQuestion;
+  answer: ChatAnswer | null;
+  /** Passed to whichever control this kind renders, and to only one of them. */
+  autoFocus?: boolean;
+  onChange(answer: ChatAnswer | null): void;
+  /** Enter, from a field that reads it before anything else does. */
+  onSubmit(): void;
+}>('QuestionField', ({ question, answer, autoFocus, onChange, onSubmit }) => {
+  const theme = useTheme();
+  const options = question.options ?? [];
+  const selectedMany = answer?.kind === 'selected-many' ? answer.value : [];
+
+  return (
+    <Column gap={0}>
+      <Row gap={1}>
+        <text content={question.message} bold wrap="word" flex={1} />
+        {question.required ? <text content="required" fg="warning" /> : null}
+      </Row>
+
+      {question.kind === 'boolean' ? (
+        <Checkbox
+          label="yes"
+          autoFocus={autoFocus === true}
+          checked={answer?.kind === 'boolean' ? answer.value : false}
+          onChange={(checked: boolean) => onChange({ kind: 'boolean', value: checked })}
+        />
+      ) : null}
+
+      {question.kind === 'single-select' ? (
+        <RadioGroup
+          autoFocus={autoFocus === true}
+          options={options.map((option, i) => ({ value: option.id, label: `${i + 1}. ${option.label}` }))}
+          {...(answer?.kind === 'selected' ? { value: answer.value } : {})}
+          onChange={(value: string) => onChange({ kind: 'selected', value })}
+        />
+      ) : null}
+
+      {question.kind === 'multi-select' ? (
+        <Column>
+          {options.map((option, i) => (
+            <Checkbox
+              key={option.id}
+              label={`${i + 1}. ${option.label}`}
+              checked={selectedMany.includes(option.id)}
+              onChange={(checked: boolean) => onChange({
+                kind: 'selected-many',
+                value: checked
+                  ? [...selectedMany, option.id]
+                  : selectedMany.filter((id) => id !== option.id),
+              })}
+            />
+          ))}
+        </Column>
+      ) : null}
+
+      {/*
+        * Prose, in a field that looks like one.
+        *
+        * A `TextArea` rather than a `TextInput` because what a host asks for
+        * in words is answered in words: "which file, and why" is two lines
+        * more often than one, and a single-line field silently makes the
+        * second one impossible. Enter sends - the hint row under this says so
+        * - and `alt+enter` (or `ctrl+enter`) is the newline, which is the
+        * composer's bargain in the same screen.
+        *
+        * The placeholder is not decoration. An empty bordered box with no
+        * caret in it is not obviously somewhere you can type, and a question
+        * whose field reads as a gap in the layout is a question that looks
+        * unanswerable.
+        */}
+      {question.kind === 'text' ? (
+        <TextArea
+          value={answer?.kind === 'text' ? answer.value : ''}
+          autoFocus={autoFocus === true}
+          maxRows={6}
+          border={theme.border}
+          placeholder="Type your answer · enter sends · alt+enter for a new line"
+          caretTone="accent"
+          onSubmit={onSubmit}
+          onChange={(value: string) => onChange(value === '' ? null : { kind: 'text', value })}
+        />
+      ) : null}
+
+      {question.kind === 'number' || question.kind === 'integer' ? (
+        <TextInput
+          value={answer && 'value' in answer ? String(answer.value) : ''}
+          autoFocus={autoFocus === true}
+          label="number"
+          hideLabel
+          placeholder="A number"
+          onSubmit={onSubmit}
+          onChange={(value: string) => onChange(
+            value === '' ? null : { kind: 'number', value: Number(value) },
+          )}
+        />
+      ) : null}
+
+      {question.allowFreeformInput && question.kind !== 'text' ? (
+        // Freeform answers *instead of* choosing, never as one more choice: a
+        // host reading only the selection must not be handed typed words in
+        // the field where it expects an option id.
+        <Row gap={1}>
+          <text content={theme.glyphs.chevronRight} fg="subtle" />
+          <TextInput
+            value={answer?.kind === 'text' ? answer.value : ''}
+            label="or say it in words"
+            placeholder="or say it in words"
+            hideLabel
+            flex={1}
+            onSubmit={onSubmit}
+            onChange={(value: string) => onChange(value === '' ? null : { kind: 'text', value })}
+          />
+        </Row>
+      ) : null}
+    </Column>
+  );
+});
+
+/**
+ * What came of the answer, on the row between the block and the composer.
+ *
+ * That row was a blank one, and it is where a person is already looking after
+ * pressing a button on the block above it. A press that reaches a host which
+ * then says nothing is indistinguishable from a key that was never read - so
+ * this says the answer has gone, and says so in red when it did not.
+ *
+ * Nothing to say is no row rather than an empty one: a status line that is
+ * always there is a row of chrome, and the composer is a row further from the
+ * conversation for the whole of every session in which nothing goes wrong.
+ */
+export interface ChatInputStatusProps extends BoxProps {
+  /** Nothing to say is `null`, and no row. */
+  status: ChatSendStatus | null;
+}
+
+export const ChatInputStatus: (props: ChatInputStatusProps) => RenderOutput =
+  defineComponent<ChatInputStatusProps>('ChatInputStatus', (props) => {
+    const theme = useTheme();
+    const { status, ...rest } = props;
+    if (!status) return null;
+    const failed = status.state === 'failed';
+    const tone = failed ? 'danger' : 'muted';
+    return (
+      <Row gap={1} {...rest}>
+        {/* The hollow dot this screen already uses for "in progress", rather
+            than an ellipsis in front of a sentence that ends in one. */}
+        <text content={failed ? theme.glyphs.warning : theme.glyphs.bulletHollow} fg={tone} />
+        <text content={status.text} fg={tone} flex={1} truncate="end" />
+      </Row>
+    );
+  });

package/src/icons.ts

@@ -0,0 +1,109 @@
+import type { UnicodeLevel } from '@textui/core';
+
+/**
+ * A mark for a setting, and for the value it is set to.
+ *
+ * These are hints, not decisions, and the distinction is the whole design.
+ * The settings a session has are the *host's* - their keys, their titles,
+ * their values and the sentence under each one all arrive over the wire, and
+ * a client that switched on them would be back to working against one host.
+ * So nothing here is required to match: an unrecognised setting gets a
+ * neutral mark and keeps every word the host gave it.
+ *
+ * What the mark buys is a row that survives being squeezed. The control row
+ * truncates labels from the right as the terminal narrows, and a chip that is
+ * only a label truncates to nothing legible; a chip that leads with a mark
+ * still says which question it is at four cells wide.
+ *
+ * Matched on the key *and* on the label, because hosts disagree about both:
+ * the same question is `permissionMode` on one and `autoApprove` on the next,
+ * and is titled "Approvals" by one of them and "Agent Mode" by the other.
+ */
+
+interface Mark {
+  full: string;
+  ascii: string;
+}
+
+const pick = (mark: Mark, unicode: UnicodeLevel): string =>
+  (unicode === 'ascii' ? mark.ascii : mark.full);
+
+/** Which question. Ordered: the first that matches wins. */
+const SETTINGS: { when: RegExp; mark: Mark }[] = [
+  { when: /harness|provider|agent(?!\s*mode)/, mark: { full: '◆', ascii: '@' } },
+  { when: /model/, mark: { full: '◇', ascii: '#' } },
+  { when: /branch/, mark: { full: '⋔', ascii: 'Y' } },
+  { when: /workspace|director|folder|cwd|path/, mark: { full: '⌂', ascii: '~' } },
+  { when: /isolat|worktree|target/, mark: { full: '▣', ascii: '=' } },
+  { when: /approv|permission|mode/, mark: { full: '◉', ascii: '%' } },
+];
+
+const OTHER_SETTING: Mark = { full: '▪', ascii: '-' };
+
+/**
+ * Which answer.
+ *
+ * The approval modes are the reason this exists: five of them, all named in
+ * the same two words - "Auto Mode", "Plan Mode", "Ask Before Edits" - and a
+ * list of five look-alike labels is a list you read twice. The marks put them
+ * in an order you can see, from "asks about everything" to "asks about
+ * nothing".
+ *
+ * Ordered, and the value is tested before the label: `bypassPermissions` and
+ * `autoApprove` both contain "auto", and only one of them means "decide for
+ * yourself".
+ */
+const VALUES: { when: RegExp; mark: Mark }[] = [
+  { when: /bypass|approveall|autoapprove|allow all|yolo/, mark: { full: '⚠', ascii: '!' } },
+  { when: /plan/, mark: { full: '≡', ascii: '=' } },
+  { when: /auto|assist/, mark: { full: '⊙', ascii: 'o' } },
+  { when: /accept|edit|write/, mark: { full: '✓', ascii: 'v' } },
+  { when: /ask|default|manual|interactive|confirm/, mark: { full: '?', ascii: '?' } },
+  { when: /worktree/, mark: { full: '⋔', ascii: 'Y' } },
+  // Not the house, which is the *workspace* chip's mark. Working in place and
+  // the directory being worked in are two chips side by side, and giving them
+  // the same mark is the one thing a mark is supposed to prevent.
+  { when: /folder|workspace|inplace|in place/, mark: { full: '▣', ascii: '=' } },
+  { when: /observe|readonly|read only/, mark: { full: '◌', ascii: '.' } },
+];
+
+const OTHER_VALUE: Mark = { full: '·', ascii: '-' };
+
+const normalise = (text: string): string => text.toLowerCase().replace(/[\s_-]+/g, '');
+
+function match(table: { when: RegExp; mark: Mark }[], ...against: (string | undefined)[]): Mark | null {
+  for (const text of against) {
+    if (!text) continue;
+    const flat = normalise(text);
+    // Both spellings: `when` clauses like /allow all/ want the words apart and
+    // /autoapprove/ wants them together, and which one a host used is not
+    // something to have an opinion about.
+    const spaced = text.toLowerCase();
+    const found = table.find((entry) => entry.when.test(flat) || entry.when.test(spaced));
+    if (found) return found.mark;
+  }
+  return null;
+}
+
+/** The mark for one of the host's questions. Never absent. */
+export function settingIcon(unicode: UnicodeLevel, key: string, title?: string): string {
+  return pick(match(SETTINGS, key, title) ?? OTHER_SETTING, unicode);
+}
+
+/**
+ * The mark for one of its answers.
+ *
+ * Absent rather than neutral when nothing matches *and* the setting is not one
+ * whose values are worth marking - a branch name is not a mode, and a column
+ * of identical dots beside a list of branches is noise with a shape.
+ */
+export function valueIcon(
+  unicode: UnicodeLevel,
+  value: string,
+  label?: string,
+  options: { fallback?: boolean } = {},
+): string | undefined {
+  const found = match(VALUES, value, label);
+  if (found) return pick(found, unicode);
+  return options.fallback === true ? pick(OTHER_VALUE, unicode) : undefined;
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+export * from './types.js';
+export * from './blocks.js';
+export * from './diff.js';
+export * from './icons.js';
+export * from './picker.js';
+export * from './measure.js';
+export * from './bubble.js';
+export * from './transcript.js';
+export * from './toolcall.js';
+export * from './controls.js';
+export * from './composer.js';
+export * from './hitl.js';
+export * from './details.js';
+export * from './sessions.js';
+export * from './sessionhead.js';
+export * from './filediff.js';

package/src/measure.ts

@@ -0,0 +1,21 @@
+import type { Rect } from '@textui/core';
+import { useEffect, useMeasure, useRef } from '@textui/core';
+
+/**
+ * Tell whoever asked where this component is, and when it is gone.
+ *
+ * Reported on every change rather than once: a composer grows a slash menu
+ * upward and grows again with a wrapped draft, and the block that asks about
+ * a tool is only there while something is waiting. `null` on the way out, or
+ * a screen that had one would keep making room for it after it had gone.
+ *
+ * The callback is read through a ref so an inline arrow - which is a new
+ * function every render - does not re-run the unmount report every frame.
+ */
+export function useReportMeasure(onMeasure: ((rect: Rect | null) => void) | undefined): void {
+  const rect = useMeasure();
+  const latest = useRef(onMeasure);
+  latest.current = onMeasure;
+  useEffect(() => { latest.current?.(rect); }, [rect.x, rect.y, rect.width, rect.height]);
+  useEffect(() => () => { latest.current?.(null); }, []);
+}

package/src/picker.ts

@@ -0,0 +1,105 @@
+import type { TextUIApp } from '@textui/core';
+import { argumentOf } from '@textui/widgets';
+
+/**
+ * The palette, moved.
+ *
+ * A chip on the composer's control row asks one question - which harness,
+ * which model, how much it may do without asking, which workspace - and every
+ * one of those is a command with an argument. The command palette already
+ * knows how to ask about exactly that: `openAt` drills straight into an
+ * argument, `choices` may be a list, a function or a promise, an argument
+ * *without* choices is answered by typing, and `preview` shows what a
+ * highlighted value would do.
+ *
+ * So this is not a second overlay. It is the same one, anchored above the
+ * control that asked, and shown one command's question rather than the whole
+ * registry. Anything registered later - a workspace list, a thinking level, a
+ * subagent - is a command with an argument and needs nothing here.
+ */
+
+export const PICKER = 'chat.picker';
+
+export interface PickerOptions {
+  /** The command whose argument is being asked about. */
+  commandId: string;
+  /** The node the panel sits above: the chip's own focus id. */
+  anchorId: string;
+  /**
+   * A fixed width. Left off, the panel is as wide as its widest answer, up to
+   * `maxWidth` - which is what a chip wants: "Worktree" and "Step-by-step
+   * collaboration" are the same question asked at two very different widths.
+   */
+  width?: number;
+  maxWidth?: number;
+  visibleRows?: number;
+  /**
+   * Put each value's sentence on its own line.
+   *
+   * For the questions whose answers are two words apart - "Accept edits" and
+   * "Plan only" - and told apart entirely by the line under them. Inline,
+   * that line shares the width with the label and shows the same truncated
+   * half of every answer.
+   */
+  descriptions?: 'inline' | 'below';
+}
+
+export function openPicker(app: TextUIApp, options: PickerOptions): void {
+  const command = app.commands.get(options.commandId);
+  if (!command) return;
+  // A chip whose command has no question to ask runs it: the workspace chip
+  // opens a dialog of its own, and a palette drilled into nothing is a list
+  // of one row that runs it anyway.
+  if (!argumentOf(command)) { void app.execute(options.commandId, undefined, 'menu'); return; }
+
+  // The chip that opened this one closes it. A control whose panel is already
+  // showing is a toggle - clicking it again to make it go away is the first
+  // thing anybody tries, and reopening it looks like the click did nothing.
+  const showing = app.layers.entries().find((entry) => entry.id === PICKER);
+  const already = showing?.node as { openAt?: string } | undefined;
+  if (already?.openAt === options.commandId) {
+    app.layers.close(PICKER);
+    return;
+  }
+
+  // Closed first, so opening a second chip's panel replaces the first rather
+  // than stacking two of them with the same id.
+  app.layers.close(PICKER);
+  app.layers.open({
+    id: PICKER,
+    // Floating, not modal: there is no scrim, because the row it is asking
+    // about has to stay readable underneath it. Which value is in force is
+    // half of what makes the question answerable.
+    layer: 'floating',
+    trapFocus: true,
+    dismissOnEscape: true,
+    dismissOnOutsideClick: true,
+    // Above the chip, aligned to its left edge - so it rises out of the
+    // control rather than appearing somewhere else on the screen. A composer
+    // sits at the bottom, so `top` is the side with room.
+    position: { kind: 'anchor', targetId: options.anchorId, side: 'top', align: 'start' },
+    node: {
+      component: 'CommandPalette',
+      ...(options.width !== undefined ? { width: options.width } : {}),
+      maxWidth: options.maxWidth ?? 52,
+      visibleRows: options.visibleRows ?? 6,
+      // One command, so the panel opens on its values instead of on a search
+      // box with everything in it.
+      commands: [command],
+      openAt: options.commandId,
+      ...(options.descriptions ? { descriptions: options.descriptions } : {}),
+      onClose: { handler: () => app.layers.close(PICKER) },
+    },
+    // Back to the chip that asked, however it was closed.
+    //
+    // The layer's own scope restores focus when a choice is made, and does not
+    // when the panel is dismissed with escape - which strands the keyboard on
+    // a node inside a layer that is no longer there, and the next tab starts
+    // from nowhere. Saying where focus goes is cheaper than depending on which
+    // of the two paths ran.
+    // Back to the chip that asked, whichever way it was closed. The layer's
+    // own scope restores focus after a choice; a dismissal would otherwise
+    // leave the keyboard on a node that is no longer mounted.
+    onClose: () => app.focus.focus(options.anchorId),
+  });
+}