@cueplusplus/ui 0.3.0 → 0.5.0

package/dist/date/_segments.js

@@ -36,11 +36,46 @@ function segmentGroupClasses(size) {
 * through data attributes.
 */
 const segmentClasses = "rounded-[2px] px-[0.0625rem] tabular-nums outline-none data-[focused]:bg-accent data-[focused]:text-accent-fg data-[placeholder]:text-fg-subtle data-[disabled]:opacity-40 data-[type=literal]:px-0 data-[type=literal]:text-fg-subtle";
-/** The `DateInput` children render prop, wired to the segment skin. */
+/**
+* The `DateInput` children render prop, wired to the segment skin.
+*
+* `suppressHydrationWarning`, and it is not papering over a bug of ours. A
+* segment's text comes from `Intl.DateTimeFormat`, which resolves against the
+* *ICU data of whatever is rendering* — and a server and a browser update their
+* ICU on different schedules. Today, `en-US` at 7:30 PM is `7:30\u202FPM` from
+* Node 24 (CLDR 48) and `7:30\u0020PM` from Chrome 151: one narrow no-break
+* space against one ordinary one, identical on screen, different to React.
+*
+* Without this, that one character is a hydration mismatch, and a mismatch is
+* not a warning — React throws away the server's HTML and re-renders the whole
+* document on the client. That re-mounts `<html>`, which React treats as a
+* singleton and therefore strips every attribute off, including the four the
+* pre-paint script wrote. Measured on this repository's own docs site: 208 ms
+* with no theme, density, mode or pairing on the document, 6,423 elements
+* resolving to a monospace nobody selected, and 40 KB of webfont fetched for it
+* that painted zero glyphs.
+*
+* So the mismatch is declared expected, on the one element whose text can
+* legitimately differ. The server's spelling of the space is kept; nobody can
+* see which one it is.
+*
+* It needs the extra `<span>` because React Aria runs its props through
+* `filterDOMProps`, which drops `suppressHydrationWarning` before the segment's
+* own element ever sees it — and React only honours the flag on the element
+* that directly contains the differing text. Only **literal** segments are
+* wrapped: they are the separators, `aria-hidden` and not focusable, while the
+* value segments React Aria makes `contentEditable` are left exactly as they
+* were. Digits and `AM`/`PM` are spelled the same by every ICU there has been;
+* it is only ever the space between them that moves.
+*/
 function renderSegment(segment) {
 	return /* @__PURE__ */ jsx(DateSegment, {
 		segment,
-		className: segmentClasses
+		className: segmentClasses,
+		children: ({ text }) => segment.type === "literal" ? /* @__PURE__ */ jsx("span", {
+			suppressHydrationWarning: true,
+			children: text
+		}) : text
 	});
 }
 /** The `DateInput` both fields render, dressed and wired to the segment skin. */

package/dist/elements/activity-graph.d.ts

@@ -0,0 +1,40 @@
+import { ComponentProps } from "react";
+import * as HeatGraph from "heat-graph";
+//#region src/elements/activity-graph.d.ts
+/**
+ * A half-year of runs as a calendar of cells, dense where the work was.
+ *
+ * @example
+ * import { ActivityGraph } from "@cueplusplus/ui/elements";
+ *
+ * <ActivityGraph
+ *   data={data}
+ *   start={start}
+ *   end={end}
+ *   title="Agent runs"
+ *   total="1,204 in 6 months"
+ * />
+ */
+declare function ActivityGraph({ data, start, end, title, total, className, ...props }: Omit<ComponentProps<"div">, "children" | "data" | "start" | "end" | "title" | "total"> & {
+  /**
+   * Date and count pairs from the heat-graph package. Levels are classified for you;
+   * gaps are filled as empty cells.
+   */
+  data: readonly HeatGraph.DataPoint[];
+  /**
+   * First day of the window. Pass it explicitly: left unset, heat-graph draws a full
+   * year ending today, which will not match your data.
+   */
+  start: string | Date;
+  /**
+   * Last day of the window. Cells are fixed-size, so a long window scrolls
+   * horizontally rather than shrinking.
+   */
+  end: string | Date;
+  /** What is being counted. */
+  title: string;
+  /** Pre-formatted summary shown opposite the title. */
+  total: string;
+}): import("react").JSX.Element;
+//#endregion
+export { ActivityGraph };

package/dist/elements/activity-graph.js

@@ -0,0 +1,81 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { mono, paper } from "./surfaces.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+import * as HeatGraph from "heat-graph";
+//#region src/elements/activity-graph.tsx
+const LEVEL_TINT = [
+	"bg-surface-2",
+	"bg-stream/25",
+	"bg-stream/45",
+	"bg-stream/70",
+	"bg-stream"
+];
+/**
+* A half-year of runs as a calendar of cells, dense where the work was.
+*
+* @example
+* import { ActivityGraph } from "@cueplusplus/ui/elements";
+*
+* <ActivityGraph
+*   data={data}
+*   start={start}
+*   end={end}
+*   title="Agent runs"
+*   total="1,204 in 6 months"
+* />
+*/
+function ActivityGraph({ data, start, end, title, total, className, ...props }) {
+	return /* @__PURE__ */ jsxs("div", {
+		"data-slot": "activity-graph",
+		className: cn(paper, "flex w-full max-w-sm flex-col gap-3 rounded-(--radius-overlay) p-4", className),
+		...props,
+		children: [/* @__PURE__ */ jsxs("div", {
+			className: "flex items-baseline justify-between",
+			children: [/* @__PURE__ */ jsx("span", {
+				className: "text-(length:--cue-text-body) font-medium",
+				children: title
+			}), /* @__PURE__ */ jsx("span", {
+				className: cn(mono, "text-fg-subtle tabular-nums"),
+				children: total
+			})]
+		}), /* @__PURE__ */ jsxs(HeatGraph.Root, {
+			data: [...data],
+			start,
+			end,
+			weekStart: "monday",
+			className: "flex flex-col gap-2",
+			children: [/* @__PURE__ */ jsxs("div", {
+				className: "flex gap-2 overflow-x-auto",
+				children: [/* @__PURE__ */ jsx("div", {
+					className: "flex shrink-0 flex-col gap-[3px]",
+					children: /* @__PURE__ */ jsx(HeatGraph.DayLabels, { children: ({ label }) => /* @__PURE__ */ jsx("span", {
+						className: cn(mono, "text-fg-subtle flex h-[9px] items-center leading-none"),
+						children: label.row % 2 === 1 ? HeatGraph.DAY_SHORT[label.dayOfWeek] : ""
+					}) })
+				}), /* @__PURE__ */ jsx(HeatGraph.Grid, {
+					className: "gap-[3px]",
+					children: ({ cell }) => /* @__PURE__ */ jsx(HeatGraph.Cell, { className: cn("size-[9px] rounded-(--radius-control)", LEVEL_TINT[cell.level] ?? LEVEL_TINT[0]) })
+				})]
+			}), /* @__PURE__ */ jsxs("div", {
+				className: "flex items-center gap-1.5 self-end",
+				children: [
+					/* @__PURE__ */ jsx("span", {
+						className: cn(mono, "text-fg-subtle"),
+						children: "less"
+					}),
+					LEVEL_TINT.map((tint, level) => /* @__PURE__ */ jsx("span", {
+						"aria-hidden": true,
+						className: cn("size-[9px] rounded-(--radius-control)", tint)
+					}, level)),
+					/* @__PURE__ */ jsx("span", {
+						className: cn(mono, "text-fg-subtle"),
+						children: "more"
+					})
+				]
+			})]
+		})]
+	});
+}
+//#endregion
+export { ActivityGraph };

package/dist/elements/agent-card.d.ts

@@ -0,0 +1,49 @@
+import { ComponentProps } from "react";
+//#region src/elements/agent-card.d.ts
+/** One thing an agent says it can do: the verb it answers to, and the line under it. */
+interface AgentSkill {
+  /** What the skill is called. Drawn as a mono chip, and the row's key. */
+  name: string;
+  /** One line on what it does, truncated to the row rather than wrapped. */
+  description: string;
+}
+/**
+ * Who you are about to talk to: its skills, its model, and the endpoint behind it.
+ *
+ * @example
+ * import { AgentCard } from "@cueplusplus/ui/elements";
+ *
+ * <AgentCard
+ *   name="Maintainer"
+ *   description="Reproduces the report, writes the fix, opens the PR."
+ *   provider="assistant-ui"
+ *   version="1.4.0"
+ *   model="opus"
+ *   endpoint="https://agents.example.com/a2a"
+ *   skills={skills}
+ *   connected={false}
+ *   onConnect={connect}
+ * />
+ */
+declare function AgentCard({ name, description, provider, version, model, endpoint, skills, connected, onConnect, className, ...props }: Omit<ComponentProps<"div">, "children" | "name" | "description" | "provider" | "version" | "model" | "endpoint" | "skills" | "connected" | "onConnect"> & {
+  /** Display name of the agent. */
+  name: string;
+  /** What it does, in one or two sentences. */
+  description: string;
+  /** Who publishes it. */
+  provider: string;
+  /** Card version, printed next to the name. */
+  version: string;
+  /** Model the agent runs on. */
+  model: string;
+  /** Where it is reached. Truncates rather than wraps. */
+  endpoint: string;
+  /** Named capabilities the card advertises. */
+  skills: readonly AgentSkill[];
+  /** Swaps the action for a settled Connected state and disables it. */
+  connected: boolean;
+  /** Called when the agent is added. */
+  onConnect?: () => void;
+}): import("react").JSX.Element;
+//#endregion
+export { AgentCard, AgentSkill };

package/dist/elements/agent-card.js

@@ -0,0 +1,91 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { field, inkButton, mono, paper } from "./surfaces.js";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { BotIcon, CheckIcon } from "lucide-react";
+//#region src/elements/agent-card.tsx
+/**
+* Who you are about to talk to: its skills, its model, and the endpoint behind it.
+*
+* @example
+* import { AgentCard } from "@cueplusplus/ui/elements";
+*
+* <AgentCard
+*   name="Maintainer"
+*   description="Reproduces the report, writes the fix, opens the PR."
+*   provider="assistant-ui"
+*   version="1.4.0"
+*   model="opus"
+*   endpoint="https://agents.example.com/a2a"
+*   skills={skills}
+*   connected={false}
+*   onConnect={connect}
+* />
+*/
+function AgentCard({ name, description, provider, version, model, endpoint, skills, connected, onConnect, className, ...props }) {
+	return /* @__PURE__ */ jsxs("div", {
+		"data-slot": "agent-card",
+		className: cn(paper, "flex w-full max-w-sm flex-col gap-3.5 rounded-(--radius-overlay) p-4", className),
+		...props,
+		children: [
+			/* @__PURE__ */ jsxs("div", {
+				className: "flex items-start gap-3",
+				children: [/* @__PURE__ */ jsx("span", {
+					className: "bg-surface-1 text-fg-muted flex size-9 shrink-0 items-center justify-center rounded-(--radius-surface)",
+					children: /* @__PURE__ */ jsx(BotIcon, { className: "size-4" })
+				}), /* @__PURE__ */ jsxs("div", {
+					className: "flex min-w-0 flex-1 flex-col",
+					children: [/* @__PURE__ */ jsxs("span", {
+						className: "flex items-baseline gap-2",
+						children: [/* @__PURE__ */ jsx("span", {
+							className: "truncate text-(length:--cue-text-body) font-medium",
+							children: name
+						}), /* @__PURE__ */ jsxs("span", {
+							className: cn(mono, "text-fg-subtle shrink-0"),
+							children: ["v", version]
+						})]
+					}), /* @__PURE__ */ jsx("span", {
+						className: "text-fg-muted truncate text-(length:--cue-text-ui)",
+						children: provider
+					})]
+				})]
+			}),
+			/* @__PURE__ */ jsx("p", {
+				className: "text-fg-muted text-(length:--cue-text-ui) leading-relaxed",
+				children: description
+			}),
+			/* @__PURE__ */ jsx("div", {
+				className: "flex flex-col gap-1.5",
+				children: skills.map((skill) => /* @__PURE__ */ jsxs("div", {
+					className: "flex items-baseline gap-2",
+					children: [/* @__PURE__ */ jsx("span", {
+						className: cn(field, mono, "text-fg-muted shrink-0 rounded-(--radius-control) px-1.5 py-0.5"),
+						children: skill.name
+					}), /* @__PURE__ */ jsx("span", {
+						className: "text-fg-muted min-w-0 flex-1 truncate text-(length:--cue-text-ui)",
+						children: skill.description
+					})]
+				}, skill.name))
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				className: "border-border flex items-center gap-2 border-t pt-3",
+				children: [/* @__PURE__ */ jsx("span", {
+					className: cn(mono, "text-fg-subtle min-w-0 flex-1 truncate"),
+					children: endpoint
+				}), /* @__PURE__ */ jsx("span", {
+					className: cn(mono, "text-fg-subtle shrink-0"),
+					children: model
+				})]
+			}),
+			/* @__PURE__ */ jsx("button", {
+				type: "button",
+				onClick: onConnect,
+				disabled: connected,
+				className: cn(connected ? cn(field, "text-fg-muted") : cn(inkButton, "justify-center"), "flex h-8 items-center justify-center gap-1.5 rounded-full px-3.5 text-(length:--cue-text-ui) font-medium disabled:pointer-events-none"),
+				children: connected ? /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx(CheckIcon, { className: "size-3.5 text-ok" }), "Connected"] }) : "Connect"
+			})
+		]
+	});
+}
+//#endregion
+export { AgentCard };

package/dist/elements/agent-handoff.d.ts

@@ -0,0 +1,24 @@
+import { ComponentProps } from "react";
+//#region src/elements/agent-handoff.d.ts
+/**
+ * Control passing between agents, with the reason and what came along.
+ *
+ * @example
+ * import { AgentHandoff } from "@cueplusplus/ui/elements";
+ *
+ * <AgentHandoff from="Triage" to="Maintainer" reason={reason} carried={carried} settled />
+ */
+declare function AgentHandoff({ from, to, reason, carried, settled, className, ...props }: Omit<ComponentProps<"div">, "children" | "from" | "to" | "reason" | "carried" | "settled"> & {
+  /** Agent giving up control. */
+  from: string;
+  /** Agent taking it. */
+  to: string;
+  /** Why the baton moved. Without it a handoff reads as an unexplained jump. */
+  reason: string;
+  /** Context that travelled across. Pass an empty array to hide the section. */
+  carried: readonly string[];
+  /** Cools the arrow and the receiving badge once the new agent is underway. */
+  settled: boolean;
+}): import("react").JSX.Element;
+//#endregion
+export { AgentHandoff };

package/dist/elements/agent-handoff.js

@@ -0,0 +1,53 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { field } from "./surfaces.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { ArrowRightIcon, BotIcon } from "lucide-react";
+//#region src/elements/agent-handoff.tsx
+/**
+* Control passing between agents, with the reason and what came along.
+*
+* @example
+* import { AgentHandoff } from "@cueplusplus/ui/elements";
+*
+* <AgentHandoff from="Triage" to="Maintainer" reason={reason} carried={carried} settled />
+*/
+function AgentHandoff({ from, to, reason, carried, settled, className, ...props }) {
+	return /* @__PURE__ */ jsxs("div", {
+		"data-slot": "agent-handoff",
+		className: cn("flex w-full max-w-sm flex-col gap-2", className),
+		...props,
+		children: [
+			/* @__PURE__ */ jsxs("div", {
+				className: "flex items-center gap-2",
+				children: [
+					/* @__PURE__ */ jsxs("span", {
+						className: cn(field, "text-fg-muted flex items-center gap-1.5 rounded-full px-2.5 py-1 text-(length:--cue-text-ui) transition-opacity duration-500", settled && "opacity-45"),
+						children: [/* @__PURE__ */ jsx(BotIcon, { className: "size-3" }), from]
+					}),
+					/* @__PURE__ */ jsx(ArrowRightIcon, { className: cn("size-3.5 shrink-0 transition-colors duration-500", settled ? "text-fg-subtle" : "text-stream") }),
+					/* @__PURE__ */ jsxs("span", {
+						className: cn("flex items-center gap-1.5 rounded-full px-2.5 py-1 text-(length:--cue-text-ui) transition-colors duration-500", settled ? cn(field, "text-fg-muted") : "bg-stream/15 text-stream"),
+						children: [/* @__PURE__ */ jsx(BotIcon, { className: "size-3" }), to]
+					})
+				]
+			}),
+			/* @__PURE__ */ jsx("p", {
+				className: "text-fg-muted text-(length:--cue-text-ui) leading-relaxed",
+				children: reason
+			}),
+			carried.length > 0 && /* @__PURE__ */ jsxs("div", {
+				className: "flex flex-col gap-1",
+				children: [/* @__PURE__ */ jsx("span", {
+					className: cn("font-mono text-(length:--cue-text-label) tracking-tight", "text-fg-subtle"),
+					children: "carried over"
+				}), carried.map((item) => /* @__PURE__ */ jsx("span", {
+					className: "text-fg-muted border-border border-s ps-2.5 text-(length:--cue-text-ui) leading-relaxed",
+					children: item
+				}, item))]
+			})
+		]
+	});
+}
+//#endregion
+export { AgentHandoff };

package/dist/elements/agent-mode-badge.d.ts

@@ -0,0 +1,72 @@
+import { AgentMode } from "./vocabulary.js";
+import * as React from "react";
+import { useRender } from "@base-ui/react/use-render";
+//#region src/elements/agent-mode-badge.d.ts
+interface AgentModeBadgeProps extends Omit<React.ComponentPropsWithoutRef<"span">, "children"> {
+  /**
+   * How much authority the run is holding: `manual`, `auto-edit`, `plan` or
+   * `unsafe`. Stamped as `data-agent-mode`, which is what the quadruple in
+   * `@cueplusplus/ui/elements.css` is keyed on.
+   */
+  mode: AgentMode;
+  /**
+   * The product's own word for it — `Agent`, `Build`, `YOLO`, `Bypass
+   * permissions`. Defaults to `AGENT_MODE_LABELS[mode]`, and it is the reason
+   * a nine-mode product needs no more than these four rungs.
+   */
+  label?: string;
+  /**
+   * What the mode actually does, as the badge's `title`. Defaults to
+   * `AGENT_MODE_DESCRIPTIONS[mode]`. Pass `""` for no tooltip at all.
+   */
+  description?: string;
+  /**
+   * Replace the rendered element (Base UI render prop) — `render={<button
+   * type="button" onClick={cycle} />}` for a picker that cycles, which is what
+   * every product with more than two modes ships.
+   */
+  render?: useRender.RenderProp;
+}
+/**
+ * What the run is allowed to do, said in one chip and one attribute.
+ *
+ * Agent authority is the fact a person most needs from the corner of their eye
+ * and the one every catalogue leaves to prose. This is the readout: a glyph, a
+ * word, and `data-agent-mode` on the element. The attribute is the part that
+ * travels — `@cueplusplus/ui/elements.css` declares four custom properties
+ * under it, so putting the same attribute on a composer tints its focus ring,
+ * its send button and its rail from one place, and a console adds a
+ * mode-aware surface by reading a property rather than by threading a prop:
+ *
+ * ```css
+ * .composer:focus-within { border-color: var(--cue-elements-mode-icon); }
+ * .send-button { background: var(--cue-elements-mode-icon); color: var(--cue-elements-mode-background); }
+ * .turn-rail { background: var(--cue-elements-mode-border); }
+ * ```
+ *
+ * The ladder is four rungs and the mode set is open. Every product in the study
+ * paints six, seven or nine modes in exactly four accents — will it ask me, is
+ * it writing, is it only planning, are the guardrails off — so the rung is what
+ * `mode` carries and the product's own word is what `label` carries.
+ *
+ * The properties resolve against the *element that carries the attribute*, not
+ * against the page: a badge inside an `<AgentSurface skin="aui">` takes the
+ * island's palette, because the quadruple is declared on `[data-agent-mode]`
+ * rather than at `:root` where a `var()` would have been substituted before it
+ * ever reached the island.
+ *
+ * @example
+ * import { AgentModeBadge } from "@cueplusplus/ui/elements";
+ *
+ * <AgentModeBadge mode="plan" />
+ * @example
+ * // A product's own word on cue's rung, and a chip that cycles.
+ * <AgentModeBadge
+ *   mode="unsafe"
+ *   label="YOLO"
+ *   render={<button type="button" onClick={cycle} />}
+ * />
+ */
+declare const AgentModeBadge: React.ForwardRefExoticComponent<AgentModeBadgeProps & React.RefAttributes<HTMLSpanElement>>;
+//#endregion
+export { AgentModeBadge, AgentModeBadgeProps };

package/dist/elements/agent-mode-badge.js

@@ -0,0 +1,110 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { AGENT_MODE_DESCRIPTIONS, AGENT_MODE_LABELS } from "./vocabulary.js";
+import * as React from "react";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { useRender } from "@base-ui/react/use-render";
+import { HandIcon, MapIcon, PencilIcon, ShieldOffIcon } from "lucide-react";
+//#region src/elements/agent-mode-badge.tsx
+/**
+* The glyph per rung, so the ladder survives a colour-blind reader and a
+* monochrome screenshot.
+*
+* A hand for the mode that stops and asks, a pencil for the one that writes, a
+* map for the one that only reads and plans, and a shield with a line through
+* it for the one that does not stop. Colour alone cannot carry authority — this
+* is the same argument that puts a label beside it.
+*/
+const MODE_GLYPH = {
+	manual: HandIcon,
+	"auto-edit": PencilIcon,
+	plan: MapIcon,
+	unsafe: ShieldOffIcon
+};
+/**
+* The four properties the quadruple publishes, with a token behind each.
+*
+* The fallbacks are not decoration: `elements.css` is a consumer import, and
+* without it these four are undeclared. A badge that resolved to nothing would
+* be an invisible chip, so the fallback is the family's neutral — the mode is
+* then carried by the glyph and the label, which is where it has to be carried
+* anyway.
+*/
+const MODE_PAINT = {
+	backgroundColor: "var(--cue-elements-mode-background, var(--cue-surface-2))",
+	color: "var(--cue-elements-mode-text, var(--cue-fg-muted))",
+	borderColor: "var(--cue-elements-mode-border, var(--cue-border))"
+};
+/** The icon's own property, which is the one a rail and a spinner also read. */
+const MODE_ICON = { color: "var(--cue-elements-mode-icon, var(--cue-fg-subtle))" };
+/**
+* What the run is allowed to do, said in one chip and one attribute.
+*
+* Agent authority is the fact a person most needs from the corner of their eye
+* and the one every catalogue leaves to prose. This is the readout: a glyph, a
+* word, and `data-agent-mode` on the element. The attribute is the part that
+* travels — `@cueplusplus/ui/elements.css` declares four custom properties
+* under it, so putting the same attribute on a composer tints its focus ring,
+* its send button and its rail from one place, and a console adds a
+* mode-aware surface by reading a property rather than by threading a prop:
+*
+* ```css
+* .composer:focus-within { border-color: var(--cue-elements-mode-icon); }
+* .send-button { background: var(--cue-elements-mode-icon); color: var(--cue-elements-mode-background); }
+* .turn-rail { background: var(--cue-elements-mode-border); }
+* ```
+*
+* The ladder is four rungs and the mode set is open. Every product in the study
+* paints six, seven or nine modes in exactly four accents — will it ask me, is
+* it writing, is it only planning, are the guardrails off — so the rung is what
+* `mode` carries and the product's own word is what `label` carries.
+*
+* The properties resolve against the *element that carries the attribute*, not
+* against the page: a badge inside an `<AgentSurface skin="aui">` takes the
+* island's palette, because the quadruple is declared on `[data-agent-mode]`
+* rather than at `:root` where a `var()` would have been substituted before it
+* ever reached the island.
+*
+* @example
+* import { AgentModeBadge } from "@cueplusplus/ui/elements";
+*
+* <AgentModeBadge mode="plan" />
+* @example
+* // A product's own word on cue's rung, and a chip that cycles.
+* <AgentModeBadge
+*   mode="unsafe"
+*   label="YOLO"
+*   render={<button type="button" onClick={cycle} />}
+* />
+*/
+const AgentModeBadge = React.forwardRef(function AgentModeBadge({ mode, label, description, render, className, style, ...elementProps }, ref) {
+	const Glyph = MODE_GLYPH[mode];
+	const said = label ?? AGENT_MODE_LABELS[mode];
+	const explained = description ?? AGENT_MODE_DESCRIPTIONS[mode];
+	return useRender({
+		render,
+		ref,
+		defaultTagName: "span",
+		props: {
+			...elementProps,
+			"data-slot": "agent-mode-badge",
+			"data-agent-mode": mode,
+			title: explained === "" ? void 0 : explained,
+			style: {
+				...MODE_PAINT,
+				...style
+			},
+			className: cn("inline-flex shrink-0 items-center gap-1.5 rounded-full border px-2 py-0.5 text-(length:--cue-text-ui) font-medium", className),
+			children: /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx(Glyph, {
+				"aria-hidden": true,
+				className: "size-3.5 shrink-0",
+				style: MODE_ICON
+			}), /* @__PURE__ */ jsx("span", {
+				className: "min-w-0 truncate",
+				children: said
+			})] })
+		}
+	});
+});
+//#endregion
+export { AgentModeBadge };

package/dist/elements/agent-plan.d.ts

@@ -0,0 +1,24 @@
+import { ComponentProps } from "react";
+//#region src/elements/agent-plan.d.ts
+/**
+ * A checklist the agent works through, with progress you can glance.
+ *
+ * @example
+ * import { AgentPlan } from "@cueplusplus/ui/elements";
+ *
+ * <AgentPlan
+ *   steps={["Read the file", "Draft the fix", "Run tests"]}
+ *   activeIndex={1}
+ * />
+ */
+declare function AgentPlan({ steps, activeIndex, className, ...props }: Omit<ComponentProps<"div">, "children" | "steps" | "activeIndex"> & {
+  /** Checklist items the agent works through in order. */
+  steps: readonly string[];
+  /**
+   * Index of the step currently running. Values past the end mark every step done, and
+   * values before the start mark none.
+   */
+  activeIndex: number;
+}): import("react").JSX.Element;
+//#endregion
+export { AgentPlan };

package/dist/elements/agent-plan.js

@@ -0,0 +1,74 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { mono } from "./surfaces.js";
+import { pct, progressOf } from "./range.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { CheckIcon, Loader2Icon } from "lucide-react";
+//#region src/elements/agent-plan.tsx
+/**
+* A checklist the agent works through, with progress you can glance.
+*
+* @example
+* import { AgentPlan } from "@cueplusplus/ui/elements";
+*
+* <AgentPlan
+*   steps={["Read the file", "Draft the fix", "Run tests"]}
+*   activeIndex={1}
+* />
+*/
+function AgentPlan({ steps, activeIndex, className, ...props }) {
+	const total = steps.length;
+	const completed = progressOf(activeIndex, total);
+	const allDone = completed >= total;
+	const progress = pct(completed, total);
+	return /* @__PURE__ */ jsxs("div", {
+		"data-slot": "agent-plan",
+		className: cn("flex w-full max-w-sm flex-col gap-3", className),
+		...props,
+		children: [
+			/* @__PURE__ */ jsxs("div", {
+				className: "flex items-center justify-between",
+				children: [/* @__PURE__ */ jsx("span", {
+					className: "text-(length:--cue-text-body) font-medium",
+					children: "Plan"
+				}), /* @__PURE__ */ jsxs("span", {
+					className: cn(mono, "text-fg-subtle tabular-nums"),
+					children: [
+						completed,
+						" of ",
+						total
+					]
+				})]
+			}),
+			/* @__PURE__ */ jsx("div", {
+				className: "bg-surface-2 h-[3px] w-full overflow-hidden rounded-full",
+				children: /* @__PURE__ */ jsx("span", {
+					className: "bg-accent block h-full rounded-full transition-[width] duration-500",
+					style: { width: `${progress}%` }
+				})
+			}),
+			/* @__PURE__ */ jsx("ul", {
+				className: "flex flex-col gap-2.5",
+				children: steps.map((step, i) => {
+					const done = allDone || i < completed;
+					const active = !allDone && i === completed;
+					return /* @__PURE__ */ jsxs("li", {
+						className: "flex items-center gap-2.5 text-(length:--cue-text-body)",
+						children: [/* @__PURE__ */ jsx("span", {
+							className: "flex size-4 shrink-0 items-center justify-center",
+							children: done ? /* @__PURE__ */ jsx(CheckIcon, { className: "text-fg-subtle size-3.5" }) : active ? /* @__PURE__ */ jsx(Loader2Icon, { className: "text-fg size-3.5 animate-spin motion-reduce:animate-none" }) : /* @__PURE__ */ jsx("span", {
+								"aria-hidden": true,
+								className: "bg-surface-3 size-1.5 rounded-full"
+							})
+						}), /* @__PURE__ */ jsx("span", {
+							className: cn(done && "text-fg-subtle", active && "text-fg", !done && !active && "text-fg-subtle"),
+							children: step
+						})]
+					}, step);
+				})
+			})
+		]
+	});
+}
+//#endregion
+export { AgentPlan };