@horon-ai/react 0.1.0 → 0.1.2

package/src/components/agent-steering-panel.tsx

@@ -1,49 +1,79 @@
-import { ArrowElbowDownLeft, ArrowUp, Check, Lightning, Path, Pause, Play, X } from "@phosphor-icons/react";
+import { ArrowUp, Check, Lightning, Path, Pause, Play, X } from "@phosphor-icons/react";
 import { type ComponentProps, type CSSProperties, type ReactNode, useState } from "react";
 
+import { useDevice } from "../hooks/use-device";
+import { usePlatform } from "../hooks/use-platform";
 import { cn } from "../lib/cn";
+import { isModKey } from "../lib/platform";
 import { Kbd } from "./kbd";
 import { Spinner } from "./spinner";
 
+/** Progress of one step: `done` fills the marker green, `active` shows a spinner, `todo` a dashed ring. */
 export type SteeringStepStatus = "done" | "active" | "todo";
 
+/** One step in the steering rail: its label, progress status and optional duration. */
 export type SteeringStep = {
+  /** Stable key for the step. */
   id: string;
+  /** Step text; secondary colour while the step is still `todo`. */
   label: ReactNode;
+  /** Progress marker to draw. */
   status: SteeringStepStatus;
   /** Duration of a finished or running step, such as "1.4s". */
   time?: ReactNode;
 };
 
+/** One steer note: the text and whether it has already been applied. */
 export type SteeringNote = {
+  /** Stable key for the note. */
   id: string;
+  /** The steer text, shown on one row and wrapping as needed. */
   text: ReactNode;
-  /** An applied note has left the queue and carries the "Now" pill. */
+  /** An applied note has left the queue and carries the "Now" pill. @default false */
   applied?: boolean;
 };
 
+/** Props for {@link AgentSteeringPanel}: the task header, the steps, queued notes and the steer handlers. */
 export type AgentSteeringPanelProps = Omit<ComponentProps<"section">, "className" | "title"> & {
+  /** Task name in the header, truncated to one line. */
   title: ReactNode;
+  /** Second header line, such as the bot or workspace, truncated to one line. */
   subtitle?: ReactNode;
   /** The status text beside the live dot, such as "Running · 2m 10s". */
   status?: ReactNode;
+  /** Pauses the live dot pulse and swaps the button to Play; the panel does not stop work on its own. @default false */
   paused?: boolean;
+  /** Fires when the pause/resume button is pressed, with the next paused value. */
   onPausedChange?: (paused: boolean) => void;
+  /** Ordered steps of the running task; the connector under a done step turns live green. */
   steps: SteeringStep[];
+  /** Notes queued for the next step, plus any already applied. @default [] */
   notes?: SteeringNote[];
+  /** Fires with the note id when its "Now" button is pressed, to apply it immediately. */
   onApplyNow?: (id: string) => void;
+  /** Fires with the note id after its pop-out animation ends; remove it from `notes` here. */
   onRemoveNote?: (id: string) => void;
-  /** Called with the text typed in the steer box: Enter queues it for the next step, ⌘Enter interrupts now. */
+  /** Called with the text typed in the steer box: Enter queues it for the next step, Mod+Enter interrupts now. */
   onSteer?: (text: string, interrupt: boolean) => void;
+  /** Placeholder of the steer input; also its accessible name. @default "Steer the bot…" */
   placeholder?: string;
+  /** Extra classes merged onto the panel, for margins or a width override. */
   className?: string;
 };
 
 const noNotes: SteeringNote[] = [];
-type IndexStyle = CSSProperties & { "--i": number };
+type IndexStyle = CSSProperties & {
+  /** Step index, consumed by the staggered `motion-rise` delay. */
+  "--i": number;
+};
 const indexStyle = (i: number): IndexStyle => ({ "--i": i });
 
-function Marker({ status }: { status: SteeringStepStatus }) {
+/** Marker for one step: green check when done, spinner when active, dashed ring while waiting. */
+// prettier-ignore
+function Marker({ status }: {
+  /** Progress state, also used as the marker's React key so the pop animation replays on change. */
+  status: SteeringStepStatus;
+}) {
   if (status === "done") {
     return (
       <span className="flex size-4.5 animate-pop-in items-center justify-center rounded-full bg-status-live text-text-on-ink">
@@ -55,13 +85,17 @@ function Marker({ status }: { status: SteeringStepStatus }) {
   return <span aria-label="Waiting" className="size-4.5 rounded-full border border-dashed border-border-dashed" />;
 }
 
+/** One queued note: the text, a "Now" action and a remove button, or a filled "Now" pill once applied. */
 function SteeringNoteRow({
   note,
   onApplyNow,
   onRemoveNote,
 }: {
+  /** The note to render; `applied` swaps the actions for the filled pill. */
   note: SteeringNote;
+  /** Called with the note id when "Now" is pressed. */
   onApplyNow?: (id: string) => void;
+  /** Called with the note id when the pop-out animation finishes, so the parent can drop it. */
   onRemoveNote?: (id: string) => void;
 }) {
   const [leaving, setLeaving] = useState(false);
@@ -118,6 +152,25 @@ function SteeringNoteRow({
  * Paper `Agent steering` (Y51-1): a 24px-radius surface panel with the running task header, a step rail, the notes
  * queued for the next step, and a steer box. The live dot pulses every 2s, a step marker swaps with a short pop,
  * new steps rise in 220ms, and send and pause press in 150ms.
+ *
+ * The steer draft is local state: it clears after `onSteer` fires, and the panel never queues a note itself.
+ * Enter queues the text for the next step and Mod+Enter sends it as an interrupt — ⌘Enter on macOS and iOS,
+ * Ctrl+Enter on Windows, Linux and Android. The two hint chips draw the same OS keys through `Kbd` and are
+ * hidden on touch devices that show no keyboard hints. IME composition keystrokes are ignored so Korean and
+ * Japanese input do not submit mid-character.
+ *
+ * @example
+ * ```tsx
+ * <AgentSteeringPanel
+ *   title="Quarterly revenue review"
+ *   status="Running · 2m 10s"
+ *   steps={[
+ *     { id: "read", label: "Read the sheet", status: "done", time: "1.4s" },
+ *     { id: "summarise", label: "Summarise the rows", status: "active" },
+ *   ]}
+ *   onSteer={(text, interrupt) => steer(text, interrupt)}
+ * />
+ * ```
  */
 export function AgentSteeringPanel({
   title,
@@ -135,6 +188,8 @@ export function AgentSteeringPanel({
   ...props
 }: AgentSteeringPanelProps) {
   const [draft, setDraft] = useState("");
+  const { os } = usePlatform();
+  const { keyboardHints } = useDevice();
   const queued = notes.filter((note) => !note.applied);
   const submit = (interrupt: boolean) => {
     const text = draft.trim();
@@ -236,7 +291,7 @@ export function AgentSteeringPanel({
               if (event.nativeEvent.isComposing || event.keyCode === 229) return;
               if (event.key === "Enter") {
                 event.preventDefault();
-                submit(event.metaKey || event.ctrlKey);
+                submit(isModKey(event, os));
               }
             }}
             placeholder={placeholder}
@@ -253,21 +308,18 @@ export function AgentSteeringPanel({
           </button>
         </div>
 
-        <div className="flex flex-wrap items-center gap-x-3.5 gap-y-1.5 text-caption text-text-secondary">
-          <span className="flex items-center gap-1.25">
-            <Kbd>
-              <ArrowElbowDownLeft aria-hidden />
-            </Kbd>
-            next step
-          </span>
-          <span className="flex items-center gap-1.25">
-            <Kbd>⌘</Kbd>
-            <Kbd>
-              <ArrowElbowDownLeft aria-hidden />
-            </Kbd>
-            interrupt now
-          </span>
-        </div>
+        {keyboardHints && (
+          <div className="flex flex-wrap items-center gap-x-3.5 gap-y-1.5 text-caption text-text-secondary">
+            <span className="flex items-center gap-1.25">
+              <Kbd keys="Enter" />
+              next step
+            </span>
+            <span className="flex items-center gap-1.25">
+              <Kbd keys="Mod+Enter" />
+              interrupt now
+            </span>
+          </div>
+        )}
       </div>
     </section>
   );

package/src/components/approval-card.tsx

@@ -5,12 +5,16 @@ import { cn } from "../lib/cn";
 import { Button } from "./button";
 import { LiquidGlass } from "./liquid-glass";
 
+/** Lifecycle of the request: `pending` keeps the brand rim and both actions, the other states hide the actions. */
 export type ApprovalState = "pending" | "approved" | "declined";
+/** `solid` paints the raised surface, `glass` layers the glass material for use over imagery. */
 export type ApprovalCardSurface = "solid" | "glass";
 
+/** Props for {@link ApprovalCard}: the state, the question, the optional attachment and the action handlers. */
 export type ApprovalCardProps = {
+  /** Lifecycle state; drives the status dot, status text and whether the actions stay visible. @default "pending" */
   state?: ApprovalState;
-  /** `solid` (default) on raised surfaces, `glass` over imagery and glass panels. */
+  /** `solid` (default) on raised surfaces, `glass` over imagery and glass panels. @default "solid" */
   surface?: ApprovalCardSurface;
   /** Status line, defaults to "Needs your yes", "Approved" or "Declined". */
   status?: ReactNode;
@@ -18,14 +22,29 @@ export type ApprovalCardProps = {
   title: ReactNode;
   /** Name of the attached item. */
   attachment?: ReactNode;
+  /** Fires when the primary action is pressed; the card does not change its own state. */
   onApprove?: () => void;
+  /** Fires when the secondary action is pressed, for deferring without deciding. */
   onLater?: () => void;
+  /** Label of the primary button. @default "Approve" */
   approveLabel?: string;
+  /** Label of the secondary button. @default "Later" */
   laterLabel?: string;
+  /** Extra classes merged onto the card, for margins or a width override. */
   className?: string;
 };
 
-const statusClass: Record<ApprovalState, { dot: string; text: string; label: string }> = {
+const statusClass: Record<
+  ApprovalState,
+  {
+    /** Background of the status dot. */
+    dot: string;
+    /** Text colour of the status line. */
+    text: string;
+    /** Default status line when `status` is omitted. */
+    label: string;
+  }
+> = {
   pending: { dot: "bg-status-live", text: "text-text-brand", label: "Needs your yes" },
   approved: { dot: "bg-text-secondary", text: "text-text-secondary", label: "Approved" },
   declined: { dot: "bg-accent-red-500-90", text: "text-text-danger", label: "Declined" },
@@ -34,6 +53,19 @@ const statusClass: Record<ApprovalState, { dot: string; text: string; label: str
 /**
  * Figma `Approval card` (64:398): the conversation part that asks for an action.
  * Pending keeps the brand rim and the actions.
+ *
+ * Controlled by `state`: the card never flips itself, and once it leaves `pending` the actions collapse and
+ * become inert, so a settled request cannot be answered twice.
+ *
+ * @example
+ * ```tsx
+ * <ApprovalCard
+ *   title="Send the Q3 board deck to the team?"
+ *   attachment="Q3-board-deck.pdf"
+ *   onApprove={send}
+ *   onLater={dismiss}
+ * />
+ * ```
  */
 export function ApprovalCard({
   state = "pending",

package/src/components/avatar.tsx

@@ -4,26 +4,32 @@ import type { ReactNode } from "react";
 
 import { cn } from "../lib/cn";
 
+/** Diameter of the avatar: `sm` 24px, `md` 32px, `lg` 40px, `xl` 56px. */
 export type AvatarSize = "sm" | "md" | "lg" | "xl";
 
+/** Props for {@link Avatar}: the avatar type and size, the image source, fallback content and the live dot. */
 export type AvatarProps = {
-  /** `initials` (default), `bot` (robot on the brand tint) or `image`. */
+  /** `initials` (default), `bot` (robot on the brand tint) or `image`. @default "initials" */
   type?: "initials" | "bot" | "image";
+  /** Diameter token; also scales the initials, the bot icon and the live dot. @default "md" */
   size?: AvatarSize;
   /** Image URL for `type="image"`; initials show while it loads or if it fails. */
   src?: string;
+  /** Alternative text for `type="image"`; pass `""` when the name is already shown next to the avatar. @default "" */
   alt?: string;
   /** Initials, or any fallback content. */
   children?: ReactNode;
-  /** Shows the live status dot at the bottom right. */
+  /** Shows the live status dot at the bottom right. @default false */
   live?: boolean;
-  /** Initials colour: `neutral` (default) or `sky`, the Paper account profile avatar (sky-100 fill, sky-700 text). */
+  /** Initials colour: `neutral` (default) or `sky`, the Paper account profile avatar (sky-100 fill, sky-700 text). @default "neutral" */
   tone?: "neutral" | "sky";
   /**
    * Border colour of the live dot, so it matches the surface behind it (glass panels, `bg-subtle`, brand tints).
    * Defaults to `border-bg-surface`.
+   * @default "border-bg-surface"
    */
   liveRingClassName?: string;
+  /** Extra classes merged onto the wrapper, for positioning or a custom size override. */
   className?: string;
 };
 
@@ -55,7 +61,17 @@ const typeClass = {
   image: "bg-sky-200 text-text-secondary",
 } as const;
 
-/** Figma `Avatar` (61:347): Initials, Bot and Image in four sizes, with an optional live dot. */
+/**
+ * Figma `Avatar` (61:347): Initials, Bot and Image in four sizes, with an optional live dot. Built on Base UI's
+ * avatar primitive, so an image that fails to load falls back to the children instead of a broken icon.
+ *
+ * @example
+ * ```tsx
+ * <Avatar type="image" size="lg" src={user.photoUrl} alt="" live>
+ *   {initials}
+ * </Avatar>
+ * ```
+ */
 export function Avatar({
   type = "initials",
   size = "md",

package/src/components/badge.tsx

@@ -3,16 +3,27 @@ import type { ComponentProps } from "react";
 import { cn } from "../lib/cn";
 import type { ControlSize } from "../lib/size";
 
-/** `surface` is the white (raised surface) pill with a 1px default border and primary text. */
+/** Tint of the pill and its dot; `neutral` is the default.
+ *
+ * - `neutral`: 6% ink pill with secondary text, the default.
+ * - `brand`: sky-tinted pill with brand text, for counts and states tied to the brand.
+ * - `danger`: red-tinted pill with danger text, for errors and destructive states.
+ * - `solid`: filled brand pill with on-primary text, for the strongest emphasis.
+ * - `surface`: the white (raised surface) pill with a 1px default border and primary text.
+ */
 export type BadgeTone = "neutral" | "brand" | "danger" | "solid" | "surface";
+/** Size token shared with the form controls (`sm`, `md`, `lg`); the rendered heights are documented on {@link Badge}. */
 export type BadgeSize = ControlSize;
 
+/** Props for {@link Badge}: the tone, size, optional status dot and extra span props. */
 export type BadgeProps = Omit<ComponentProps<"span">, "className"> & {
+  /** Colour treatment of the pill and its dot. @default "neutral" */
   tone?: BadgeTone;
   /** Leading status dot; 4px (sm), 6px (md) or 8px (lg). */
   dot?: boolean;
-  /** `md` is the 22px Figma Badge; `sm` 20px and `lg` 26px. */
+  /** `md` is the 22px Figma Badge; `sm` 20px and `lg` 26px. @default "md" */
   size?: BadgeSize;
+  /** Extra classes merged onto the pill, for margins or alignment. */
   className?: string;
 };
 
@@ -44,7 +55,17 @@ const dotClass: Record<BadgeTone, string> = {
   surface: "bg-text-primary",
 };
 
-/** Figma `Badge` (61:283): a 22px translucent pill with label-sm text. */
+/**
+ * Figma `Badge` (61:283): a 22px translucent pill with label-sm text. Renders a non-interactive `span`, so it can
+ * sit inside buttons, list rows and headings without changing their layout height.
+ *
+ * @example
+ * ```tsx
+ * <Badge tone="brand" dot>
+ *   Running
+ * </Badge>
+ * ```
+ */
 export function Badge({ tone = "neutral", dot, size = "md", className, children, ...props }: BadgeProps) {
   return (
     <span

package/src/components/banner.tsx

@@ -5,18 +5,24 @@ import { cn } from "../lib/cn";
 import type { ControlSize } from "../lib/size";
 import { LiquidGlass } from "./liquid-glass";
 
+/** Severity of the strip: `info` tints the rim and icon brand, `danger` uses the danger rim and role="alert". */
 export type BannerTone = "info" | "danger";
+/** Size token shared with the form controls; the rendered heights are documented on {@link Banner}. */
 export type BannerSize = ControlSize;
+/** `solid` paints the raised surface, `glass` layers the glass material for use over imagery. */
 export type BannerSurface = "solid" | "glass";
 
+/** Props for {@link Banner}: the tone, size and surface of the strip plus its optional trailing action. */
 export type BannerProps = Omit<ComponentProps<"div">, "className"> & {
+  /** Severity; also picks the icon and the ARIA role. @default "info" */
   tone?: BannerTone;
   /** Trailing underlined action, such as a link or button. */
   action?: ReactNode;
-  /** Banner size: `sm` 32px minimum, `md` the Figma 48px strip (default), `lg` 56px; scales icon, text and padding. */
+  /** Banner size: `sm` 32px minimum, `md` the Figma 48px strip (default), `lg` 56px; scales icon, text and padding. @default "md" */
   size?: BannerSize;
-  /** `solid` (default) on raised surfaces, `glass` over imagery and glass panels. */
+  /** `solid` (default) on raised surfaces, `glass` over imagery and glass panels. @default "solid" */
   surface?: BannerSurface;
+  /** Extra classes merged onto the strip, for margins or width overrides. */
   className?: string;
 };
 
@@ -59,7 +65,17 @@ const solidEdgeClass: Record<BannerTone, string> = {
   danger: "border-border-danger",
 };
 
-/** Figma `Banner` (62:318): a strip with a tinted rim, 16px icon and an underlined action. */
+/**
+ * Figma `Banner` (62:318): a strip with a tinted rim, 16px icon and an underlined action. The tone sets the ARIA
+ * role — `danger` renders `role="alert"` (announced immediately), `info` renders `role="status"`.
+ *
+ * @example
+ * ```tsx
+ * <Banner tone="danger" action={<a href="/settings">Review</a>}>
+ *   Your API key expired.
+ * </Banner>
+ * ```
+ */
 export function Banner({
   tone = "info",
   action,

package/src/components/bot-instructions-panel.tsx

@@ -2,23 +2,54 @@ import { CaretDown, Play } from "@phosphor-icons/react";
 import { type ComponentProps, type KeyboardEvent, type ReactNode, useRef, useState } from "react";
 
 import { cn } from "../lib/cn";
-import { useActiveIndicator } from "../lib/use-active-indicator";
+import { useActiveIndicator } from "../hooks/use-active-indicator";
+import { useDevice } from "../hooks/use-device";
 import { Kbd } from "./kbd";
 
-type WithClass<T> = Omit<T, "className"> & { className?: string };
+/** Drops the base type's `className` so the panel can own it. */
+type WithClass<T> = Omit<T, "className"> & {
+  /** Extra classes merged onto the root element. */
+  className?: string;
+};
 
+/** Props for {@link PanelPillTabs}: the tab items, the controlled or default selection and the change handler. */
 export type PanelPillTabsProps = {
-  items: { value: string; label: ReactNode }[];
+  /** Tabs in display order; the first one is the default selection. */
+  items: {
+    /** Value handed to `onValueChange` and compared against `value`. */
+    value: string;
+    /** Tab label. */
+    label: ReactNode;
+  }[];
+  /** Controlled selected value; omit it to let the track keep its own selection. */
   value?: string;
+  /** Selection used before the first click, falling back to the first item. */
   defaultValue?: string;
+  /** Fires with the next value on click or arrow-key navigation. */
   onValueChange?: (value: string) => void;
+  /** Accessible name of the tab list. */
   "aria-label"?: string;
+  /** Extra classes merged onto the track, for width overrides. */
   className?: string;
 };
 
 /**
- * The 5% ink pill track shared by the Bot panels (Paper `YNQ-1`): 3px padding, 2px gap, 28px options with
+ * The 5% ink pill track shared by the Bot panels (Paper `YNQ-1`): 3px padding, 2px gap, 30px options with
  * 12px inset and a 10% ink selection that slides between options in 280ms.
+ *
+ * Works controlled (`value`) or uncontrolled (`defaultValue`); the arrow keys wrap around, move the selection
+ * and focus the newly selected tab, while only the selected tab stays in the tab order.
+ *
+ * @example
+ * ```tsx
+ * <PanelPillTabs
+ *   aria-label="Instructions view"
+ *   items={[
+ *     { value: "instructions", label: "Instructions" },
+ *     { value: "example", label: "Example" },
+ *   ]}
+ * />
+ * ```
  */
 export function PanelPillTabs({ items, value, defaultValue, onValueChange, className, ...props }: PanelPillTabsProps) {
   const [inner, setInner] = useState(defaultValue ?? items[0]?.value ?? "");
@@ -81,6 +112,7 @@ export function PanelPillTabs({ items, value, defaultValue, onValueChange, class
   );
 }
 
+/** Chip tint: `sky` the default light blue, `brand` the deeper sky-700, `neutral` grey. */
 export type InstructionVariableTone = "sky" | "brand" | "neutral";
 
 const variableToneClass: Record<InstructionVariableTone, string> = {
@@ -96,26 +128,53 @@ const variableDotClass: Record<InstructionVariableTone, string> = {
 };
 
 /** One piece of an instruction line: plain text, or a `{{variable}}` chip. */
-export type InstructionPart = string | { variable: string; tone?: InstructionVariableTone };
+export type InstructionPart =
+  | string
+  | {
+      /** Variable name, rendered inside the chip without the braces. */
+      variable: string;
+      /** Chip tint. @default "sky" */
+      tone?: InstructionVariableTone;
+    };
 
-export type InstructionVariable = { name: string; tone?: InstructionVariableTone; value: string };
+/** A test value for one `{{variable}}` in the prompt, shown under the instructions. */
+export type InstructionVariable = {
+  /** Variable name shown above the test value. */
+  name: string;
+  /** Dot tint matching the chip in the prompt. @default "sky" */
+  tone?: InstructionVariableTone;
+  /** Test value used when the instruction is run. */
+  value: string;
+};
 
+/** Props for {@link BotInstructionsPanel}: the bot, the prompt lines, the optional example, variables and scenarios, and the run handler. */
 export type BotInstructionsPanelProps = WithClass<Omit<ComponentProps<"section">, "title">> & {
+  /** Panel heading. @default "Instructions" */
   title?: ReactNode;
   /** Version label in the header pill, for example `v4`. */
   version?: string;
   /** Status next to the version, rendered with a live dot. */
   versionStatus?: string;
-  bot: { initial: string; name: string };
-  /** The editable prompt, one array of parts per line. */
+  /** Bot whose prompt is shown; the initial fills the 18px tile. */
+  bot: {
+    /** One-character tile label. */
+    initial: string;
+    /** Bot name next to the tile. */
+    name: string;
+  };
+  /** The prompt text, one array of parts per line, rendered read-only. */
   instructions: InstructionPart[][];
   /** Shown under the Example tab instead of the prompt. */
   example?: ReactNode;
+  /** Prompt length shown at the right of the tab row; hidden when undefined. */
   tokenCount?: number;
   /** Test values for each variable in the prompt. */
   variables?: InstructionVariable[];
+  /** Test scenarios offered as pills under the prompt. */
   scenarios?: string[];
+  /** Scenario selected on first render, falling back to the first scenario. */
   defaultScenario?: string;
+  /** Fires with the selected scenario (or undefined) when Run is pressed; the panel does not run anything itself. */
   onRun?: (scenario: string | undefined) => void;
   /** The last run's output, or a hint until there is one. */
   output?: ReactNode;
@@ -129,13 +188,17 @@ function partKey(part: InstructionPart) {
   return typeof part === "string" ? part : part.variable;
 }
 
+/** Inline rounded chip that stands in for a `{{variable}}` inside a prompt line. */
 function VariableChip({
   tone = "sky",
   className,
   children,
 }: {
+  /** Chip tint. @default "sky" */
   tone?: InstructionVariableTone;
+  /** Extra classes merged onto the chip. */
   className?: string;
+  /** Variable name shown without braces. */
   children: ReactNode;
 }) {
   return (
@@ -152,6 +215,23 @@ function Divider() {
 /**
  * Bot instructions panel (Paper `YN3-1` / `GOZ-0`): a 24px-radius surface with the bot header, an
  * Instructions / Example tab pair over the prompt text with `{{variable}}` chips, and a test-run block.
+ *
+ * The tab and the selected scenario are local state; the panel only reports a run through `onRun`. Output is
+ * re-keyed per run so it animates in every time. A caret blinks at the end of the prompt while the prompt area
+ * has focus. The Run button carries a `Mod+Enter` chip — ⌘↵ on macOS and iOS, Ctrl+Enter elsewhere — which is
+ * hidden on touch devices that show no keyboard hints.
+ *
+ * @example
+ * ```tsx
+ * <BotInstructionsPanel
+ *   version="v4"
+ *   bot={{ initial: "R", name: "Researcher" }}
+ *   instructions={[["Summarise ", { variable: "sheet" }, " for the team."]]}
+ *   variables={[{ name: "sheet", value: "Q3 metrics" }]}
+ *   scenarios={["Weekly digest", "Board update"]}
+ *   onRun={(scenario) => run(scenario)}
+ * />
+ * ```
  */
 export function BotInstructionsPanel({
   title = "Instructions",
@@ -174,6 +254,7 @@ export function BotInstructionsPanel({
   const [tab, setTab] = useState("instructions");
   const [scenario, setScenario] = useState(defaultScenario ?? scenarios?.[0]);
   const [runCount, setRunCount] = useState(0);
+  const { keyboardHints } = useDevice();
 
   return (
     <section
@@ -342,7 +423,9 @@ export function BotInstructionsPanel({
               >
                 <Play aria-hidden className="size-3.5" />
                 Run
-                <Kbd className="bg-bg-surface-6 text-text-inverse/80">⌘↵</Kbd>
+                {keyboardHints && (
+                  <Kbd keys="Mod+Enter" className="bg-bg-surface-6 text-text-inverse/80" />
+                )}
               </button>
             </div>
           </div>

package/src/components/bot-list-row.tsx

@@ -3,7 +3,9 @@ import type { ComponentProps, ReactNode } from "react";
 import { cn } from "../lib/cn";
 import { Avatar } from "./avatar";
 
+/** Props for {@link BotListRow}: the bot name, last-activity time and preview, the live and selected states. */
 export type BotListRowProps = Omit<ComponentProps<"button">, "className"> & {
+  /** Bot display name, truncated with an ellipsis when it does not fit. */
   name: ReactNode;
   /** Last activity time, such as "8:41 AM". */
   time?: ReactNode;
@@ -11,11 +13,21 @@ export type BotListRowProps = Omit<ComponentProps<"button">, "className"> & {
   preview?: ReactNode;
   /** Running bots show the live dot on the avatar. */
   live?: boolean;
+  /** The row for the bot currently open in the panel; paints the 10% ink selected fill and sets `aria-pressed`. */
   selected?: boolean;
+  /** Extra classes merged onto the button, for margins or width overrides. */
   className?: string;
 };
 
-/** Figma `Bot list row` (64:456): a flat 12px-padded row; hover 5% ink, selected 10% ink. */
+/**
+ * Figma `Bot list row` (64:456): a flat 12px-padded row; hover 5% ink, selected 10% ink. The whole row is the
+ * button, so the accessible name comes from its text content (name, time and preview).
+ *
+ * @example
+ * ```tsx
+ * <BotListRow name="Researcher" time="8:41 AM" preview="Pulled the Q3 numbers" live selected />
+ * ```
+ */
 export function BotListRow({ name, time, preview, live, selected, className, ...props }: BotListRowProps) {
   return (
     <button