@horon-ai/react 0.1.1 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@horon-ai/react",
-	"version": "0.1.1",
+	"version": "0.1.2",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/horon-ai/design.git",
@@ -30,7 +30,7 @@
 	"dependencies": {
 		"@base-ui/react": "^1.9.0",
 		"@fontsource-variable/geist-mono": "^5.3.0",
-		"@horon-ai/tokens": "0.1.1",
+		"@horon-ai/tokens": "0.1.2",
 		"@phosphor-icons/react": "^2.1.10",
 		"@tanstack/react-table": "^9.3.1",
 		"pretendard": "^1.3.9",

package/src/components/agent-activity.tsx

@@ -5,8 +5,22 @@ import { useReducedMotion } from "../hooks/use-reduced-motion";
 import { cn } from "../lib/cn";
 import { Spinner } from "./spinner";
 
-/** Figma `Thinking` (Agent activity 108:660): a 69x31 subtle pill with three 7px dots at 35/55/80% ink. */
-export function ThinkingIndicator({ label = "Thinking", className }: { label?: string; className?: string }) {
+/**
+ * Figma `Thinking` (Agent activity 108:660): a 69x31 subtle pill with three 7px dots at 35/55/80% ink.
+ * Announced as `role="status"`; the three dots bounce with a 150ms stagger.
+ *
+ * @example
+ * ```tsx
+ * <ThinkingIndicator label="Searching the workspace…" />
+ * ```
+ */
+// prettier-ignore
+export function ThinkingIndicator({ label = "Thinking", className }: {
+  /** Accessible status text, not rendered visibly. @default "Thinking" */
+  label?: string;
+  /** Extra classes merged onto the pill, for margins or alignment. */
+  className?: string;
+}) {
   return (
     <span
       role="status"
@@ -79,13 +93,15 @@ function useRevealedLength(text: string, smooth: boolean, reducedMotion: boolean
   return Math.min(shown, text.length);
 }
 
+/** Props for {@link StreamingText}: the growing answer, whether it is still streaming, and whether chunks are revealed smoothly. */
 export type StreamingTextProps = Omit<ComponentProps<"div">, "className" | "children"> & {
   /** Everything received so far; pass the growing string as chunks arrive. */
   text: string;
-  /** True while more text is coming: the caret shows, and the rest is revealed when it turns false. */
+  /** True while more text is coming: the caret shows, and the rest is revealed when it turns false. @default true */
   streaming?: boolean;
-  /** Reveal arriving chunks a few characters per frame instead of in jumps. Off under reduced motion. */
+  /** Reveal arriving chunks a few characters per frame instead of in jumps. Off under reduced motion. @default true */
   smooth?: boolean;
+  /** Extra classes merged onto the bubble, such as a maximum width. */
   className?: string;
 };
 
@@ -94,6 +110,16 @@ export type StreamingTextProps = Omit<ComponentProps<"div">, "className" | "chil
  * right after the last character and wraps with it. The caret holds still while characters land and blinks
  * while waiting for the next chunk; it goes away when the stream ends. Screen readers get the answer once,
  * when it is complete, instead of every chunk.
+ *
+ * `text` is the whole answer so far, not a delta: passing only the newest chunk would drop earlier text. The
+ * reveal restarts from the shared prefix when `text` is rewritten rather than extended.
+ *
+ * @example
+ * ```tsx
+ * function Answer({ text, done }: { text: string; done: boolean }) {
+ *   return <StreamingText text={text} streaming={!done} />;
+ * }
+ * ```
  */
 export function StreamingText({ text, streaming = true, smooth = true, className, ...props }: StreamingTextProps) {
   const reducedMotion = useReducedMotion();
@@ -124,16 +150,31 @@ export function StreamingText({ text, streaming = true, smooth = true, className
   );
 }
 
+/** Progress of a tool call: `running` shows a spinner, `done` a check, `failed` a warning and danger text. */
 export type ToolStepState = "running" | "done" | "failed";
 
+/** Props for {@link ToolStep}: the tool line, an optional detail line and the progress state. */
 export type ToolStepProps = Omit<ComponentProps<"button">, "className" | "title"> & {
+  /** Progress state, which also picks the leading icon and the title colour. @default "running" */
   state?: ToolStepState;
+  /** The tool call line, truncated to one line. */
   title: ReactNode;
+  /** Optional second line, such as the target or a short result, truncated to one line. */
   detail?: ReactNode;
+  /** Extra classes merged onto the row, for margins. */
   className?: string;
 };
 
-/** Figma `Tool step` (108:660): a flat 12px-radius row with spinner, check or warning, and a caret. */
+/**
+ * Figma `Tool step` (108:660): a flat 12px-radius row with spinner, check or warning, and a caret.
+ * Renders a real `button`, so pass `onClick` to open the call's detail; the caret does not expand anything
+ * on its own.
+ *
+ * @example
+ * ```tsx
+ * <ToolStep state="done" title="Search the web" detail="3 results" onClick={openCall} />
+ * ```
+ */
 export function ToolStep({ state = "running", title, detail, className, ...props }: ToolStepProps) {
   return (
     <button
@@ -158,16 +199,43 @@ export function ToolStep({ state = "running", title, detail, className, ...props
   );
 }
 
-export type WorkLogStep = { id: string; title: ReactNode; detail?: ReactNode; running?: boolean };
+/** One compact line inside a work log. */
+export type WorkLogStep = {
+  /** Stable key for the step. */
+  id: string;
+  /** Step text, truncated to one line. */
+  title: ReactNode;
+  /** Optional second line with a short result or target. */
+  detail?: ReactNode;
+  /** Shows a small spinner instead of the check while the step is still running. */
+  running?: boolean;
+};
 
-/** Figma `Work log` (108:660): a flat subtle card with a wrench summary row and compact steps. */
+/**
+ * Figma `Work log` (108:660): a flat subtle card with a wrench summary row and compact steps. It is a native
+ * `<details open>`, so the summary collapses and expands without extra state; the caret rotates while closed.
+ *
+ * @example
+ * ```tsx
+ * <WorkLog
+ *   summary="4 steps"
+ *   steps={[
+ *     { id: "read", title: "Read the sheet", detail: "18 rows", running: false },
+ *     { id: "write", title: "Draft the summary", running: true },
+ *   ]}
+ * />
+ * ```
+ */
 export function WorkLog({
   summary,
   steps,
   className,
 }: {
+  /** Summary line in the toggle row, such as "4 steps". */
   summary: ReactNode;
+  /** Steps listed under the summary. */
   steps: WorkLogStep[];
+  /** Extra classes merged onto the card, for margins or a width override. */
   className?: string;
 }) {
   return (

package/src/components/agent-lane.tsx

@@ -4,20 +4,36 @@ import type { ReactNode } from "react";
 import { cn } from "../lib/cn";
 import { Spinner } from "./spinner";
 
+/** Lifecycle of the lane: `running` shows a spinner and a pulsing tile, `done` a check, `failed` a warning and a danger rim. */
 export type AgentLaneStatus = "running" | "done" | "failed";
 
+/** Props for {@link AgentLane}: the sub-agent identity, its task, and the optional tool, output, usage and timing lines. */
 export type AgentLaneProps = {
+  /** Lifecycle state; also picks the tile shade (sky-400, sky-600, sky-800) and the result icon. */
   status: AgentLaneStatus;
-  bot: { initial: string; name: ReactNode };
+  /** Identity of the sub-agent shown in the header. */
+  bot: {
+    /** One-character tile label, usually the first letter of the name. */
+    initial: string;
+    /** Display name, truncated when the header runs out of room. */
+    name: ReactNode;
+  };
   /** Duration, such as "1.9s". */
   elapsed?: ReactNode;
+  /** The short task line under the header, wrapping onto several lines. */
   task: ReactNode;
   /** 14px tool icon and source, such as "Notion · Q3 metrics dashboard". */
-  tool?: { icon: ReactNode; label: ReactNode };
+  tool?: {
+    /** Tool icon, sized 14px by the row. */
+    icon: ReactNode;
+    /** Tool and source description, truncated to one line. */
+    label: ReactNode;
+  };
   /** Latest output, or the error when failed. */
   output?: ReactNode;
   /** Usage caption, such as "2.6k tokens". */
   usage?: ReactNode;
+  /** Extra classes merged onto the card, for layout inside a lane grid. */
   className?: string;
 };
 
@@ -27,7 +43,20 @@ const botTile: Record<AgentLaneStatus, string> = {
   failed: "bg-sky-800",
 };
 
-/** Figma `Agent lane` (Agent orchestrator 113:953): one sub-agent's card in a fan-out, flat subtle with a red rim on failure. */
+/**
+ * Figma `Agent lane` (Agent orchestrator 113:953): one sub-agent's card in a fan-out, flat subtle with a red rim on failure.
+ *
+ * @example
+ * ```tsx
+ * <AgentLane
+ *   status="running"
+ *   bot={{ initial: "R", name: "Researcher" }}
+ *   task="Gather the Q3 metrics"
+ *   tool={{ icon: <span aria-hidden>N</span>, label: "Notion · Q3 metrics dashboard" }}
+ *   elapsed="1.9s"
+ * />
+ * ```
+ */
 export function AgentLane({ status, bot, elapsed, task, tool, output, usage, className }: AgentLaneProps) {
   return (
     <div

package/src/components/agent-lanes-timeline.tsx

@@ -4,58 +4,99 @@ import { type ComponentProps, type CSSProperties, type ReactNode } from "react";
 import { cn } from "../lib/cn";
 import { Spinner } from "./spinner";
 
+/** Bar tone: done is 6% ink, running is 20% live green, failed is 14% red, waiting is an outlined brand bar. */
 export type LaneTaskTone = "done" | "running" | "failed" | "waiting";
 
+/** One bar on a bot's row: its label, time range in minutes before the window end, tone and optional badge. */
 export type LaneTask = {
+  /** Stable key; also how a `LaneHandoff` refers to this task. */
   id: string;
+  /** Text inside the bar, truncated when the bar is too narrow. */
   label: ReactNode;
+  /** 14px icon before the label. */
   icon?: ReactNode;
+  /** Bar fill and text colour. */
   tone: LaneTaskTone;
   /** Minutes before the end of the window, 0 is now: a task from 28 minutes ago to 16 minutes ago is `-28` to `-16`. */
   start: number;
+  /** Minutes before the end of the window where the bar ends; must be greater than `start`. */
   end: number;
   /** A pill inside the bar, such as "Needs you". */
   badge?: ReactNode;
 };
 
+/** Avatar tint of a bot row: `sky` is sky-500, `steel` sky-700, `neutral` neutral-500 and `ink` the brand fill. */
 export type LaneBotTone = "sky" | "steel" | "neutral" | "ink";
 
+/** One lane in the timeline: the bot's identity, its tag and the task bars on its row. */
 export type LaneBot = {
+  /** Stable key for the row; also the lane order. */
   id: string;
+  /** Bot name shown beside the avatar. */
   name: ReactNode;
+  /** Second line under the name, such as the tools the bot uses. */
   tools?: ReactNode;
+  /** One-character avatar label, usually the first letter of the name. */
   initial: string;
+  /** Avatar fill, chosen to keep neighbouring bots distinct. */
   tone: LaneBotTone;
   /** A small tag next to the name: "Idle", "Needs you". */
   badge?: ReactNode;
+  /** Tag fill: `ink` is the brand fill, `subtle` the default 6% ink. @default "subtle" */
   badgeTone?: "subtle" | "ink";
+  /** Bars on this bot's row; tasks from different bots may overlap in time. */
   tasks: LaneTask[];
 };
 
-export type LaneHandoff = { from: string; to: string };
+/** A dashed curve from one task's end to another task's start, such as a hand-off to the next bot. */
+export type LaneHandoff = {
+  /** Task id the curve starts from. */
+  from: string;
+  /** Task id the curve ends at. */
+  to: string;
+};
 
-export type LaneStatus = { id: string; tone: "live" | "ink"; label: ReactNode };
+/** A legend entry in the header: a dot plus a label. */
+export type LaneStatus = {
+  /** Stable key for the entry. */
+  id: string;
+  /** `live` paints the dot green, `ink` paints it with the brand fill. */
+  tone: "live" | "ink";
+  /** Legend text, such as "2 running". */
+  label: ReactNode;
+};
 
+/** The approval strip below the timeline: one question and its two actions. */
 export type AgentLanesTimelineApproval = {
+  /** The approval question in the strip at the bottom. */
   message: ReactNode;
+  /** Fires when "Later" is pressed. */
   onLater?: () => void;
+  /** Fires when "Approve" is pressed. */
   onApprove?: () => void;
 };
 
+/** Props for {@link AgentLanesTimeline}: the lanes, the time window and optional header, hand-offs and approval strip. */
 export type AgentLanesTimelineProps = Omit<ComponentProps<"section">, "className" | "title"> & {
+  /** Panel heading. @default "Bots" */
   title?: ReactNode;
+  /** Legend entries shown next to the heading. @default [] */
   statuses?: LaneStatus[];
-  /** The range pill at the header's right edge. */
+  /** The range pill at the header's right edge. @default "Last 30m" */
   range?: ReactNode;
+  /** One row per bot, in lane order; at least two row heights are always reserved. */
   bots: LaneBot[];
+  /** Hand-off curves drawn over the rows; a hand-off naming an unknown task is skipped. @default [] */
   handoffs?: LaneHandoff[];
-  /** Window length in minutes; the tick labels sit every five. */
+  /** Window length in minutes; the tick labels sit every five. @default 30 */
   windowMinutes?: number;
-  /** Where the current line sits, in minutes before the end of the window. The line glides to a new value in 280ms. */
+  /** Where the current line sits, in minutes before the end of the window. The line glides to a new value in 280ms. @default 0 */
   cursor?: number;
+  /** Adds the approval strip below the timeline. */
   approval?: AgentLanesTimelineApproval;
   /** Makes the range pill actionable; without it the range renders as a plain label. */
   onRangeClick?: () => void;
+  /** Extra classes merged onto the panel, for margins or a width override. */
   className?: string;
 };
 
@@ -75,7 +116,10 @@ const barTone: Record<LaneTaskTone, string> = {
 
 const noStatuses: LaneStatus[] = [];
 const noHandoffs: LaneHandoff[] = [];
-type RowStyle = CSSProperties & { "--i": number };
+type RowStyle = CSSProperties & {
+  /** Lane index, consumed by the staggered `motion-rise` delay. */
+  "--i": number;
+};
 const rowStyle = (lane: number): RowStyle => ({ top: TOP + lane * ROW, height: ROW, "--i": lane });
 
 const ROW = 64;
@@ -91,6 +135,32 @@ const trackW = (fraction: number) => `calc(${TRACK} * ${fraction})`;
  * Paper `Agent lanes` (YCO-1): a 24px-radius surface panel with one lane per bot on a shared time axis, a current
  * line, hand-off curves between bots and an approval strip. The current line glides in 280ms with the emphasized
  * easing, rows tint on hover in 150ms, and running bars carry a spinner.
+ *
+ * The track has a 700px minimum width and scrolls horizontally, so narrow panels stay readable instead of
+ * squeezing the bars. Times are minutes before the window's end, not timestamps.
+ *
+ * @example
+ * ```tsx
+ * <AgentLanesTimeline
+ *   bots={[
+ *     {
+ *       id: "researcher",
+ *       name: "Researcher",
+ *       initial: "R",
+ *       tone: "sky",
+ *       tasks: [{ id: "pull", label: "Pull metrics", tone: "done", start: -28, end: -16 }],
+ *     },
+ *     {
+ *       id: "writer",
+ *       name: "Writer",
+ *       initial: "W",
+ *       tone: "steel",
+ *       tasks: [{ id: "draft", label: "Draft summary", tone: "running", start: -16, end: 0 }],
+ *     },
+ *   ]}
+ *   handoffs={[{ from: "pull", to: "draft" }]}
+ * />
+ * ```
  */
 export function AgentLanesTimeline({
   title = "Bots",
@@ -106,7 +176,15 @@ export function AgentLanesTimeline({
   ...props
 }: AgentLanesTimelineProps) {
   const ticks = Array.from({ length: windowMinutes / 5 - 1 }, (_, i) => -(windowMinutes - 5 * (i + 1)));
-  const taskAt = new Map<string, { task: LaneTask; lane: number }>();
+  const taskAt = new Map<
+    string,
+    {
+      /** The task the hand-off refers to. */
+      task: LaneTask;
+      /** Lane index of the bot that owns the task, used for the curve's vertical endpoints. */
+      lane: number;
+    }
+  >();
   bots.forEach((bot, lane) => {
     for (const task of bot.tasks) taskAt.set(task.id, { task, lane });
   });

package/src/components/agent-panel.tsx

@@ -7,9 +7,22 @@ import { cn } from "../lib/cn";
 import { isModKey } from "../lib/platform";
 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;
+};
 
-/** The solid panel that hosts the Figma Agents blocks (Agent tasks 112:797): surface fill, 24px radius, 16px padding. */
+/**
+ * The solid panel that hosts the Figma Agents blocks (Agent tasks 112:797): surface fill, 24px radius, 16px padding.
+ *
+ * @example
+ * ```tsx
+ * <AgentPanel filter={<FilterBar items={[{ value: "all", label: "All" }]} />}>
+ *   <TaskComposer onStart={start} pickers={<ComposerChip leading="R">Researcher</ComposerChip>} />
+ * </AgentPanel>
+ * ```
+ */
 export function AgentPanel({
   className,
   filter,
@@ -32,13 +45,18 @@ export function AgentPanel({
   );
 }
 
+/** Props for {@link ComposerChip}: a leading tile letter or icon, its fill, and the usual button props. */
 export type ComposerChipProps = WithClass<ComponentProps<"button">> & {
   /** 16px tile initial (bots) or a 14px icon (projects). */
   leading?: ReactNode;
+  /** Tile fill, defaulting to the brand; pass a sky or neutral shade to match the bot it stands for. */
   tileClassName?: string;
 };
 
-/** A 30px 5% ink picker chip with a 12px caret, used for the bot and project in the task composer. */
+/**
+ * A 30px 5% ink picker chip with a 12px caret, used for the bot and project in the task composer.
+ * Part of {@link TaskComposer}; the chip is a plain button, so it needs its own `onClick` or menu wiring.
+ */
 export function ComposerChip({ leading, tileClassName, className, children, ...props }: ComposerChipProps) {
   return (
     <button
@@ -67,18 +85,42 @@ export function ComposerChip({ leading, tileClassName, className, children, ...p
   );
 }
 
+/** Props for {@link TaskComposer}: the draft text, picker chips, the start handler and the labels. */
 export type TaskComposerProps = {
+  /** Placeholder of the textarea; also its accessible name. @default "Describe a task for a bot" */
   placeholder?: string;
+  /** Controlled draft text; leave undefined and pass `onValueChange` to lift the text, or omit both for a free draft. */
   value?: string;
+  /** Fires on every keystroke with the next text, so the caller can hold the draft. */
   onValueChange?: (value: string) => void;
   /** Picker chips, usually two `ComposerChip`s. */
   pickers?: ReactNode;
+  /** Fires on the Start button and on Mod+Enter; the composer does not clear the draft itself. */
   onStart?: () => void;
+  /** Label of the start button. @default "Start" */
   startLabel?: string;
+  /** Extra classes merged onto the box, for margins or width overrides. */
   className?: string;
 };
 
-/** Figma task `Composer` (Agent tasks 112:797): a 4% ink box, 18px radius, with pickers, a Mod+Enter hint and Start. */
+/**
+ * Figma task `Composer` (Agent tasks 112:797): a 4% ink box, 20px radius, with pickers, a key hint and Start.
+ *
+ * The textarea starts at one row and grows with its content up to 160px (`max-h-40`) before it scrolls.
+ * Mod+Enter submits: ⌘Enter on macOS and iOS, Ctrl+Enter on Windows, Linux and Android. The hint is a
+ * `Kbd keys="Mod+Enter"` chip, so it draws the same OS keys, and it is hidden on touch devices that have
+ * no hovering fine pointer.
+ *
+ * @example
+ * ```tsx
+ * <TaskComposer
+ *   value={draft}
+ *   onValueChange={setDraft}
+ *   onStart={start}
+ *   pickers={<ComposerChip leading="R">Researcher</ComposerChip>}
+ * />
+ * ```
+ */
 export function TaskComposer({
   placeholder = "Describe a task for a bot",
   value,

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

@@ -8,45 +8,72 @@ 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, 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">
@@ -58,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);
@@ -121,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,

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",