@teaflask/assistant 0.0.0 → 0.3.0

package/src/components/model-picker-panels.tsx

@@ -0,0 +1,232 @@
+"use client";
+
+import type { RefObject } from "react";
+
+import type {
+  ServedModelChoice,
+  ServedThinkingEffort,
+} from "../contract/assistant-config.js";
+import type { ComposerContract } from "../core/conversation-contract.js";
+import { CheckIcon, ChevronDownIcon } from "./icons.js";
+import { effortLabelOf, nearestEffortIn } from "./model-picker-effort.js";
+import { TfButton } from "./primitives/button.js";
+
+export type PickerPanel = "root" | "model" | "effort";
+
+// Every panel's frame: its focus target, which panel the menu shows, and
+// the navigation that moves focus onto the revealed panel.
+interface PickerPanelFrame {
+  panelRef: RefObject<HTMLDivElement | null>;
+  panel: PickerPanel;
+  showPanel: (next: PickerPanel) => void;
+}
+
+// The compact root: Model and Effort as the menu's two drill-ins.
+export function ModelPickerRootPanel({
+  panelRef,
+  panel,
+  currentName,
+  currentEffort,
+  showPanel,
+}: PickerPanelFrame & {
+  currentName: string;
+  currentEffort: ServedThinkingEffort | null;
+}) {
+  return (
+    <div
+      ref={panelRef}
+      tabIndex={-1}
+      hidden={panel !== "root"}
+      role="group"
+      aria-label="Model and effort"
+      className={
+        (panel === "root" ? "tf:flex " : "tf:hidden ") +
+        "tf:flex-col tf:gap-0.5 tf:outline-none"
+      }
+    >
+      <TfButton
+        variant="row"
+        className="tf:gap-3"
+        onClick={() => {
+          showPanel("model");
+        }}
+      >
+        <span className="tf:flex-1 tf:text-left">Model</span>
+        <span className="tf:min-w-0 tf:truncate tf:text-tf-muted-foreground">
+          {currentName}
+        </span>
+        <span className="tf:-rotate-90 tf:text-tf-muted-foreground">
+          <ChevronDownIcon />
+        </span>
+      </TfButton>
+      <TfButton
+        variant="row"
+        className="tf:gap-3"
+        onClick={() => {
+          showPanel("effort");
+        }}
+      >
+        <span className="tf:flex-1 tf:text-left">Effort</span>
+        <span className="tf:min-w-0 tf:truncate tf:text-tf-muted-foreground">
+          {currentEffort === null ? "Default" : effortLabelOf(currentEffort)}
+        </span>
+        <span className="tf:-rotate-90 tf:text-tf-muted-foreground">
+          <ChevronDownIcon />
+        </span>
+      </TfButton>
+    </div>
+  );
+}
+
+// The model drill-in: one row per served option, the current one checked.
+export function ModelPickerServedModelsPanel({
+  panelRef,
+  panel,
+  menu,
+  currentModelId,
+  modelPick,
+  setModelPick,
+  showPanel,
+}: PickerPanelFrame &
+  Pick<ComposerContract, "modelPick" | "setModelPick"> & {
+    menu: ServedModelChoice;
+    currentModelId: string;
+  }) {
+  return (
+    <div
+      ref={panelRef}
+      tabIndex={-1}
+      hidden={panel !== "model"}
+      role="group"
+      aria-label="Model"
+      className={
+        (panel === "model" ? "tf:flex " : "tf:hidden ") +
+        "tf:flex-col tf:gap-0.5 tf:outline-none"
+      }
+    >
+      <PickerPanelHeading
+        label="Model"
+        onBack={() => {
+          showPanel("root");
+        }}
+      />
+      {menu.models.map((option) => (
+        <TfButton
+          key={option.id}
+          variant="row"
+          aria-pressed={option.id === currentModelId}
+          onClick={() => {
+            // The default row is the way back: it stores NO pin,
+            // so the thread keeps following operator changes. A
+            // stored effort re-resolves against the chosen model's
+            // OWN set (nearest, ties down — Amendment C): kept
+            // when supported, rewritten when not, never
+            // materialized from the display default (a null pin
+            // stays null — the config answers), and never
+            // rewritten when it is outside this bundle's
+            // vocabulary.
+            const stored = modelPick?.effort ?? null;
+            setModelPick({
+              modelId: option.id === menu.default_model_id ? null : option.id,
+              effort:
+                stored === null || option.efforts.includes(stored)
+                  ? stored
+                  : (nearestEffortIn(option.efforts, stored) ?? stored),
+            });
+            showPanel("root");
+          }}
+        >
+          <span className="tf:min-w-0 tf:flex-1 tf:truncate">
+            {option.display_name}
+          </span>
+          <span aria-hidden={option.id !== currentModelId} className="tf:w-4">
+            {option.id === currentModelId ? <CheckIcon /> : null}
+          </span>
+        </TfButton>
+      ))}
+    </div>
+  );
+}
+
+// The effort drill-in: the selected model's own ladder, the displayed
+// (clamped) value checked.
+export function ModelPickerEffortPanel({
+  panelRef,
+  panel,
+  ladder,
+  currentEffort,
+  modelPick,
+  setModelPick,
+  showPanel,
+}: PickerPanelFrame &
+  Pick<ComposerContract, "modelPick" | "setModelPick"> & {
+    ladder: readonly ServedThinkingEffort[];
+    currentEffort: ServedThinkingEffort | null;
+  }) {
+  return (
+    <div
+      ref={panelRef}
+      tabIndex={-1}
+      hidden={panel !== "effort"}
+      role="group"
+      aria-label="Reasoning effort"
+      className={
+        (panel === "effort" ? "tf:flex " : "tf:hidden ") +
+        "tf:flex-col tf:gap-0.5 tf:outline-none"
+      }
+    >
+      <PickerPanelHeading
+        label="Effort"
+        onBack={() => {
+          showPanel("root");
+        }}
+      />
+      {ladder.map((effort) => (
+        <TfButton
+          key={effort}
+          variant="row"
+          aria-pressed={effort === currentEffort}
+          onClick={() => {
+            // Clicking the already-current row writes NOTHING: the
+            // displayed value may be a clamp of configured truth.
+            if (effort !== currentEffort) {
+              // Effort-only never pins a model: the pin stays
+              // whatever it was (null follows the configured model).
+              setModelPick({
+                modelId: modelPick?.modelId ?? null,
+                effort,
+              });
+            }
+            showPanel("root");
+          }}
+        >
+          <span className="tf:min-w-0 tf:flex-1 tf:truncate">
+            {effortLabelOf(effort)}
+          </span>
+          <span aria-hidden={effort !== currentEffort} className="tf:w-4">
+            {effort === currentEffort ? <CheckIcon /> : null}
+          </span>
+        </TfButton>
+      ))}
+    </div>
+  );
+}
+
+function PickerPanelHeading({
+  label,
+  onBack,
+}: {
+  label: string;
+  onBack: () => void;
+}) {
+  return (
+    <div className="tf:mb-1 tf:flex tf:items-center tf:gap-1 tf:border-b tf:px-1 tf:pb-1">
+      <TfButton variant="icon" aria-label="Back" onClick={onBack}>
+        <span className="tf:rotate-90">
+          <ChevronDownIcon />
+        </span>
+      </TfButton>
+      <span className="tf:text-tf-label tf:font-medium">{label}</span>
+    </div>
+  );
+}

package/src/components/notice-banner.tsx

@@ -0,0 +1,44 @@
+"use client";
+
+import type { ReactNode } from "react";
+
+import { TfButton } from "./primitives/button.js";
+
+export function NoticeBanner({
+  children,
+  hook,
+}: {
+  children: ReactNode;
+  /** Optional data-tf hook, stamped on the banner's OWN box. Never wrap
+   *  a banner in a display:contents element to carry a hook:
+   *  a boxless element no-ops `filter`, so the
+   *  roster-defocus blur (styles.css, [data-tf-conversation-body]
+   *  children) left the wrapped banner crisp while its siblings
+   *  receded. */
+  hook?: string;
+}) {
+  return (
+    <div role="alert" className="tf:border-b" {...(hook ? { [hook]: "" } : {})}>
+      <div className="tf:mx-auto tf:flex tf:w-full tf:max-w-3xl tf:items-center tf:gap-2 tf:px-4 tf:py-2 tf:text-tf-label tf:text-tf-destructive">
+        {children}
+      </div>
+    </div>
+  );
+}
+
+/** The pending-decision gap's one spelling. Its own module so
+ *  `./transcript-ui` can export it without dragging the conversation
+ *  chrome into that entry's graph: the widget chrome and the dashboard
+ *  playground both render it, and the fixture bench poses it over a
+ *  populated transcript — the composition it actually ships in — rather
+ *  than re-spelling the copy. */
+export function PendingDecisionGapNotice({ onRetry }: { onRetry: () => void }) {
+  return (
+    <NoticeBanner hook="data-tf-pending-decision-gap">
+      The assistant is waiting on a request that couldn&apos;t be shown.
+      <TfButton variant="ghost" onClick={onRetry}>
+        Retry
+      </TfButton>
+    </NoticeBanner>
+  );
+}

package/src/components/operation-icons.tsx

@@ -0,0 +1,166 @@
+"use client";
+
+// The semantic icon vocabulary (contract law 6): the one ToolCallIcon →
+// glyph table, and the composite operation mark every process row leads
+// with. The mark is a pure function of the RESOLVED presentation —
+// (protocol state, icon token) — never of a tool name (TVC-032), each
+// vocabulary member renders a distinct glyph (TVC-054), and completion
+// is quiet: the settled mark is the semantic icon in settled ink, never
+// a universal checkmark. Destructive ink appears on the mark iff the
+// call failed (TVC-033); a cancelled, refused (TVC-038) or member-denied
+// (TVC-039) call stays neutral. State is never colour-only: the mark
+// carries its state word for assistive tech, and the row's headline
+// ladder says it in text.
+
+import type { ReactNode } from "react";
+
+import type { LucideIcon } from "lucide-react";
+import {
+  BrainIcon,
+  CalendarClockIcon,
+  CompassIcon,
+  FileTextIcon,
+  ListTodoIcon,
+  MessageCircleQuestionIcon,
+  SearchIcon,
+  SquareTerminalIcon,
+  UsersIcon,
+  WrenchIcon,
+} from "lucide-react";
+
+import type { ToolCallState } from "../core/tool-call-display.js";
+import type { ToolCallIcon } from "../core/tool-call-presentation.js";
+import { cx } from "./primitives/cx.js";
+
+// One glyph per resolved vocabulary member — operational meaning, never
+// a brand or a tool name (the presenter already resolved unknown tokens
+// to "generic", so this record is total over what can reach it).
+const OPERATION_GLYPHS: Record<ToolCallIcon, LucideIcon> = {
+  search: SearchIcon,
+  file: FileTextIcon,
+  terminal: SquareTerminalIcon,
+  question: MessageCircleQuestionIcon,
+  memory: BrainIcon,
+  delegation: UsersIcon,
+  routine: CalendarClockIcon,
+  // The plan-progress member (contract §8's recorded conditional):
+  // a checklist, unmistakably not the generic wrench.
+  todo: ListTodoIcon,
+  navigation: CompassIcon,
+  generic: WrenchIcon,
+};
+
+// The state language, keyed by protocol state alone — the words assistive
+// tech hears where sighted readers get ink and the headline ladder.
+const STATE_WORDS: Record<ToolCallState, string> = {
+  "input-streaming": "Queued",
+  "input-available": "Running",
+  "output-available": "Completed",
+  "output-error": "Failed",
+  // Its own quiet word: a member declined the approval — not interrupted
+  // (nobody cut it), not failed (nothing broke), and not the door's
+  // "Declined" (TVC-038 — the tool never got to answer).
+  denied: "Not approved",
+  cancelled: "Interrupted",
+  // Its own quiet word: the tool answered and declined — not
+  // interrupted (nothing cut it), not failed (nothing broke).
+  refused: "Declined",
+  // Shares cancelled's outcome word — both landed short of an outcome
+  // through no fault of the tool; the headline frames tell them apart.
+  superseded: "Interrupted",
+};
+
+/** The mark's package-owned chrome — identity, state attribute, ink
+ *  rules and the assistive state word — around any glyph. Shared by the
+ *  package mark below and the tool-view icon slot, so a registered icon
+ *  can replace the GLYPH and nothing else (tool-views.md: one
+ *  registration, two roles; the mark's state semantics are never the
+ *  adapter's to lose). */
+export function OperationMarkFrame({
+  status,
+  children,
+}: {
+  status: ToolCallState;
+  children: ReactNode;
+}) {
+  return (
+    <span
+      // Deliberately NO icon-token attribute here: the glyph itself must
+      // carry the distinctness (TVC-054's negative control proved an
+      // icon attribute lets two members share one glyph unnoticed).
+      data-tf-op-mark=""
+      data-tf-op-state={status}
+      className={cx(
+        "tf:grid tf:size-4 tf:shrink-0 tf:place-items-center",
+        // Queued (a pending call on a run that is not streaming) dims —
+        // the mark stays semantic, never a dashed mystery circle.
+        status === "input-streaming" && "tf:opacity-45",
+        // The one loud pixel (the visual spec's Status-Only Color Rule):
+        // failure wears destructive ink; cancellation, refusal and a
+        // member's denial stay neutral.
+        status === "output-error" && "tf:text-tf-destructive",
+      )}
+    >
+      {children}
+      <span className="tf:sr-only">{STATE_WORDS[status]}</span>
+    </span>
+  );
+}
+
+/** The process row's leading mark: semantic identity with local state.
+ *  Rendered as the row summary's FIRST child — that position is contract
+ *  (TVC-050 measures the icon column on it). */
+export function OperationMark({
+  icon,
+  status,
+}: {
+  icon: ToolCallIcon;
+  status: ToolCallState;
+}) {
+  const Glyph = OPERATION_GLYPHS[icon];
+  return (
+    <OperationMarkFrame status={status}>
+      <Glyph aria-hidden className="tf:size-4" />
+    </OperationMarkFrame>
+  );
+}
+
+/** The bare semantic glyph, for consent frames: the decision card's title
+ *  carries the words and the frame carries the state, so the glyph arrives
+ *  silent — no state word, no ink rule, aria-hidden. Same
+ *  one-glyph-per-member table as the operation mark, never a fork. */
+export function OperationGlyph({
+  icon,
+  className,
+}: {
+  icon: ToolCallIcon;
+  className?: string;
+}) {
+  const Glyph = OPERATION_GLYPHS[icon];
+  return <Glyph aria-hidden className={cx("tf:size-4", className)} />;
+}
+
+/** The inline state pill (Layer A's state badge): a small textual badge
+ *  on the affected row for the states that must never read as quiet —
+ *  failure, interruption, awaiting input. Mechanical state words only
+ *  (the headline ladder owns authored copy); text is the signal, colour
+ *  merely underlines it. */
+export function StatePill({
+  children,
+  destructive = false,
+}: {
+  children: string;
+  destructive?: boolean;
+}) {
+  return (
+    <span
+      data-tf-state-pill=""
+      className={cx(
+        "tf:shrink-0 tf:rounded-full tf:border tf:border-tf-border tf:px-1.5 tf:py-px tf:text-xs tf:leading-4 tf:whitespace-nowrap",
+        destructive && "tf:text-tf-destructive",
+      )}
+    >
+      {children}
+    </span>
+  );
+}

package/src/components/pretty-print.ts

@@ -0,0 +1,9 @@
+export function prettyPrintParameters(parameters: unknown): string {
+  if (parameters === undefined || parameters === null) {
+    return "";
+  }
+  if (typeof parameters === "string") {
+    return parameters;
+  }
+  return JSON.stringify(parameters, null, 2);
+}

package/src/components/primitives/autofocus.ts

@@ -0,0 +1,26 @@
+// The package's opt-in initial-focus convention, shared by every surface
+// that moves focus on open: content marks its own landing spot with
+// data-tf-autofocus (the composer does), and the surface honors it. What
+// happens without a mark is the surface's own affair — the modal dialog
+// falls back to the native first-focusable, the non-modal panel
+// deliberately moves nothing.
+
+/** Focuses the surface's marked autofocus target, with one frame of
+ * grace for content that mounts a beat after the surface is shown. The
+ * predicate guards the deferred attempt: a surface that closed inside
+ * that frame must not have focus pulled into it. */
+export function focusAutofocusTarget(
+  surface: HTMLElement,
+  stillShowing: () => boolean,
+): void {
+  const target = surface.querySelector<HTMLElement>("[data-tf-autofocus]");
+  if (target !== null) {
+    target.focus();
+    return;
+  }
+  requestAnimationFrame(() => {
+    if (stillShowing()) {
+      surface.querySelector<HTMLElement>("[data-tf-autofocus]")?.focus();
+    }
+  });
+}

package/src/components/primitives/button.tsx

@@ -0,0 +1,205 @@
+"use client";
+
+import { forwardRef } from "react";
+import type { AnchorHTMLAttributes, ButtonHTMLAttributes } from "react";
+
+import { cx } from "./cx.js";
+
+// The package's primitives layer: raw interactive elements are legal only
+// here (the lint law mirrors the dashboard's shadcn-primitives rule).
+
+// The Graphite button grammar: filled primary-grade actions are pills
+// with the control wash; quiet variants sit on the control-radius step.
+// `send` is the chat bar's circular primary; `icon` the rail/masthead
+// square; `row` the rail's nav row (aria-current carries its selection)
+// and `rowAction` its taller sibling for the rail's one command;
+// `rowTouch` both at the 44px touch floor; `prompt` the empty state's row.
+type TfButtonVariant =
+  | "primary"
+  | "ghost"
+  | "send"
+  | "stop"
+  | "icon"
+  | "iconFloating"
+  | "row"
+  | "rowAction"
+  | "rowTouch"
+  | "rowActionTouch"
+  | "prompt"
+  | "bare"
+  | "chip"
+  | "chipQuiet"
+  | "outline"
+  | "answerRow";
+
+interface TfButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  variant?: TfButtonVariant;
+}
+
+// Each variant resets the UA button border itself: no preflight ships with
+// the package, so every shape states its own `border-0` rather than
+// inheriting the host page's idea of what a button looks like.
+const VARIANT_CLASSES: Record<TfButtonVariant, string> = {
+  primary:
+    "tf:justify-center tf:rounded-full tf:border-0 tf:px-3 tf:py-1.5 tf:text-tf-label tf:font-medium " +
+    "tf:bg-tf-primary tf:text-tf-primary-foreground tf:shadow-tf-control " +
+    "tf:hover:opacity-90 tf:disabled:opacity-50",
+  ghost:
+    "tf:justify-center tf:rounded-tf tf:border-0 tf:px-3 tf:py-1.5 tf:text-tf-label tf:font-medium " +
+    "tf:bg-tf-transparent tf:text-tf-foreground tf:hover:bg-tf-accent tf:disabled:opacity-50",
+  // Nothing to send is a resting state, not a broken one: the disabled
+  // circle steps back to the muted wash instead of showing a filled ink
+  // button at 40% — a washed-out primary reads as a rendering fault.
+  send:
+    "tf:size-8 tf:shrink-0 tf:justify-center tf:rounded-full tf:border-0 " +
+    "tf:bg-tf-primary tf:text-tf-primary-foreground tf:shadow-tf-control " +
+    "tf:hover:opacity-90 tf:disabled:bg-tf-muted tf:disabled:text-tf-muted-foreground " +
+    "tf:disabled:opacity-100 tf:disabled:shadow-none",
+  // The send circle's busy-state counterpart: same silhouette, filled-ink
+  // register even through the "Stopping…" beat. That beat is narrated
+  // with aria-disabled, never the disabled attribute — disabling the
+  // focused control drops keyboard focus to <body>.
+  stop:
+    "tf:size-8 tf:shrink-0 tf:justify-center tf:rounded-full tf:border-0 " +
+    "tf:bg-tf-primary tf:text-tf-primary-foreground tf:shadow-tf-control " +
+    "tf:hover:opacity-90 tf:aria-disabled:cursor-not-allowed tf:aria-disabled:opacity-70",
+  icon:
+    "tf:size-7 tf:justify-center tf:rounded-tf tf:border-0 tf:bg-tf-transparent tf:text-tf-muted-foreground " +
+    "tf:hover:bg-tf-accent tf:hover:text-tf-foreground tf:disabled:opacity-50",
+  // A floating icon control: round, on its own paper plate with a hairline
+  // and the control wash, for glyphs hovering over arbitrary pixels. A
+  // VARIANT, not a caller className: cx is a plain join, so a caller's
+  // bg-tf-background loses to icon's own bg-tf-transparent by sheet order.
+  iconFloating:
+    "tf:justify-center tf:rounded-full tf:border tf:bg-tf-background " +
+    "tf:text-tf-muted-foreground tf:shadow-tf-control " +
+    "tf:hover:bg-tf-accent tf:hover:text-tf-foreground tf:disabled:opacity-50",
+  // 32px at 14px medium — the app's measured rail register, so the
+  // assistant's history reads at the same density as the docs tree.
+  row:
+    "tf:h-8 tf:w-full tf:justify-start tf:rounded-tf tf:border-0 tf:px-2.5 tf:text-left tf:text-sm tf:font-medium " +
+    "tf:bg-tf-transparent tf:text-tf-muted-foreground tf:hover:bg-tf-accent " +
+    "tf:hover:text-tf-foreground tf:aria-[current=true]:bg-tf-accent " +
+    "tf:aria-[current=true]:text-tf-foreground tf:disabled:opacity-50",
+  rowAction:
+    "tf:h-9 tf:w-full tf:justify-start tf:gap-2 tf:rounded-tf tf:border-0 tf:px-2.5 tf:text-left tf:text-sm " +
+    "tf:font-medium tf:bg-tf-transparent tf:text-tf-foreground tf:hover:bg-tf-accent " +
+    "tf:disabled:opacity-50",
+  // The drawer's rows clear the 44px touch floor and read a step larger:
+  // a phone is held further away than a rail is leaned over.
+  rowTouch:
+    "tf:h-11 tf:w-full tf:justify-start tf:gap-2 tf:rounded-tf tf:border-0 tf:px-3 tf:text-left " +
+    "tf:text-tf-body tf:font-medium tf:bg-tf-transparent tf:text-tf-muted-foreground " +
+    "tf:hover:bg-tf-accent tf:hover:text-tf-foreground " +
+    "tf:aria-[current=true]:bg-tf-accent tf:aria-[current=true]:text-tf-foreground " +
+    "tf:disabled:opacity-50",
+  // The drawer's edition of rowAction. A variant rather than a colour
+  // override on rowTouch: cx is a plain join, so a passed text-tf-foreground
+  // and rowTouch's own muted ink land at equal specificity and the
+  // later-emitted utility (the muted one) wins.
+  rowActionTouch:
+    "tf:h-11 tf:w-full tf:justify-start tf:gap-2 tf:rounded-tf tf:border-0 tf:px-3 tf:text-left " +
+    "tf:text-tf-body tf:font-medium tf:bg-tf-transparent tf:text-tf-foreground " +
+    "tf:hover:bg-tf-accent tf:disabled:opacity-50",
+  // The opening prompts. A row, not a pill: three pills of unequal width
+  // centre-justified make a ragged line, and rows survive a 390px column.
+  // The trailing arrow is held at zero opacity rather than unmounted so
+  // the right edge never twitches. px-4 puts the leading glyph on the
+  // composer's own text inset, hanging off the chat bar's left edge.
+  prompt:
+    "tf:min-h-11 tf:w-full tf:justify-start tf:gap-2.5 tf:rounded-tf tf:border-0 tf:px-4 tf:py-2 " +
+    "tf:text-left tf:text-tf-label tf:bg-tf-transparent tf:text-tf-foreground " +
+    "tf:hover:bg-tf-accent tf:disabled:opacity-50 " +
+    "tf:[&_[data-tf-prompt-mark]]:text-tf-muted-foreground " +
+    "tf:[&_[data-tf-prompt-go]]:opacity-0 tf:[&_[data-tf-prompt-go]]:transition-opacity " +
+    "tf:hover:[&_[data-tf-prompt-go]]:opacity-100 " +
+    "tf:focus-visible:[&_[data-tf-prompt-go]]:opacity-100 " +
+    // Touch has no hover to reveal the go arrow; it stays visible there.
+    "tf:pointer-coarse:[&_[data-tf-prompt-go]]:opacity-100",
+  // A button that draws nothing of its own — for content that IS the
+  // affordance (the companion perch's mark, the bubble's sentence). Keeps
+  // the focus ring, resets the UA chrome, and takes the surrounding ink:
+  // the UA's buttontext would paint black on a dark popover.
+  bare: "tf:rounded-tf tf:border-0 tf:bg-tf-transparent tf:p-0 tf:text-inherit tf:disabled:opacity-50",
+  // The composer shelf's chip (the provider/model slot): a quiet rounded
+  // control at the 13px label step. Two emphases as two variants (cx is a
+  // plain join, so emphasis has to be the variant's): `chip` keeps full
+  // ink for an affordance that asks, `chipQuiet` is the settled standing's.
+  chip:
+    "tf:rounded-full tf:border-0 tf:px-2 tf:py-1 tf:text-tf-label tf:font-medium " +
+    "tf:bg-tf-transparent tf:text-tf-foreground tf:hover:bg-tf-accent " +
+    "tf:disabled:opacity-50",
+  chipQuiet:
+    "tf:rounded-full tf:border-0 tf:px-2 tf:py-1 tf:text-tf-label tf:font-medium " +
+    "tf:bg-tf-transparent tf:text-tf-muted-foreground tf:hover:bg-tf-accent " +
+    "tf:hover:text-tf-foreground tf:disabled:opacity-50",
+  // A bounded secondary action/status control. It shares the pill
+  // silhouette with the composer's chips, but keeps a hairline so it is
+  // unmistakably interactive inside a floating menu.
+  outline:
+    "tf:justify-center tf:rounded-full tf:border tf:px-2.5 tf:py-1 tf:text-tf-label tf:font-medium " +
+    "tf:bg-tf-background tf:text-tf-foreground tf:shadow-tf-control " +
+    "tf:hover:bg-tf-accent tf:disabled:opacity-50",
+  // The question panel's answer row: one suggestion per line, spanning
+  // the panel, on the 44px touch floor. Selection is the emphasis wash,
+  // via aria-checked — state speaks through the attribute the screen
+  // reader already gets (No-Accent: never a color). Borderless: the
+  // row's edges are the panel's.
+  answerRow:
+    "tf:min-h-11 tf:w-full tf:items-start tf:justify-start tf:gap-3 tf:rounded-tf tf:border-0 " +
+    "tf:bg-tf-transparent tf:px-3 tf:py-2.5 tf:text-left tf:text-tf-label tf:text-tf-foreground " +
+    "tf:wrap-anywhere tf:hover:bg-tf-accent tf:disabled:opacity-50 " +
+    "tf:aria-checked:bg-tf-emphasis",
+};
+
+// forwardRef rather than ref-as-prop: the peer range admits React 18.3,
+// where a function component receives no ref through props — and callers
+// that anchor to the element (the drawer's history disclosure, the focus
+// hand-backs) need the ref to attach.
+export const TfButton = forwardRef<HTMLButtonElement, TfButtonProps>(
+  function TfButton({ variant = "primary", className, type, ...props }, ref) {
+    return (
+      <button
+        ref={ref}
+        type={type ?? "button"}
+        className={cx(
+          "tf:appearance-none",
+          "tf:inline-flex tf:items-center tf:gap-1.5 tf:transition-colors",
+          "tf:focus-visible:outline-2 tf:focus-visible:outline-offset-2 tf:focus-visible:outline-tf-ring",
+          "tf:disabled:cursor-not-allowed",
+          VARIANT_CLASSES[variant],
+          className,
+        )}
+        {...props}
+      />
+    );
+  },
+);
+
+// A navigation wearing the button grammar — for actions whose "click" is
+// a link (the connect panel's approve CTA). Same class source as
+// TfButton so the pill can never drift; no disabled arm, because anchors
+// have none.
+export function TfLinkButton({
+  variant = "primary",
+  className,
+  children,
+  ...props
+}: AnchorHTMLAttributes<HTMLAnchorElement> & { variant?: TfButtonVariant }) {
+  return (
+    <a
+      className={cx(
+        // no-underline: the UA underlines anchors and no preflight ships
+        // with the package — a pill with an underline reads as a bug.
+        "tf:appearance-none tf:no-underline",
+        "tf:inline-flex tf:items-center tf:gap-1.5 tf:transition-colors",
+        "tf:focus-visible:outline-2 tf:focus-visible:outline-offset-2 tf:focus-visible:outline-tf-ring",
+        VARIANT_CLASSES[variant],
+        className,
+      )}
+      {...props}
+    >
+      {children}
+    </a>
+  );
+}