@cueplusplus/ui 0.13.0

package/dist/elements/streaming-text.js

@@ -0,0 +1,45 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { take } from "./range.js";
+import { useMemo } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/elements/streaming-text.tsx
+/**
+* Tokens arrive softly: the newest words land in blue and settle into ink.
+*
+* @example
+* import { StreamingText } from "@cueplusplus/ui/elements";
+*
+* <StreamingText
+*   segments={[{ text: "Hello world" }, { text: "thread.tsx", mono: true }]}
+*   count={3}
+*   streaming
+* />
+*/
+function StreamingText({ segments, count, streaming, className, ...props }) {
+	const words = useMemo(() => segments.flatMap((segment) => segment.text.split(" ").map((word) => ({
+		word,
+		mono: segment.mono ?? false
+	}))), [segments]);
+	const shown = take(words, count);
+	return /* @__PURE__ */ jsxs("p", {
+		"data-slot": "streaming-text",
+		className: cn("min-h-[8.5rem] max-w-sm text-(length:--cue-text-body) leading-(--cue-leading-ui) text-pretty", className),
+		...props,
+		children: [shown.map(({ word, mono: isMono }, i) => {
+			const fresh = streaming && shown.length - 1 - i < 2;
+			return /* @__PURE__ */ jsxs("span", {
+				className: "cue-elements-fade-in cue-elements-animate-in cue-elements-fill-mode-both duration-500 motion-reduce:animate-none",
+				children: [/* @__PURE__ */ jsx("span", {
+					className: cn("transition-colors duration-700 motion-reduce:transition-none", fresh && "text-stream", isMono && "bg-surface-2 rounded-(--radius-control) px-1.5 py-0.5 font-mono text-[0.85em]"),
+					children: word
+				}), " "]
+			}, i);
+		}), streaming && shown.length > 0 && /* @__PURE__ */ jsx("span", {
+			"aria-hidden": true,
+			className: "-mb-0.5 ml-0.5 inline-block h-4 w-0.5 animate-pulse rounded-full bg-stream"
+		})]
+	});
+}
+//#endregion
+export { StreamingText };

package/dist/elements/subagent-list.d.ts

@@ -0,0 +1,37 @@
+import { ComponentProps } from "react";
+//#region src/elements/subagent-list.d.ts
+/** One delegated agent: who it is and what it runs on. */
+interface SubagentItem {
+  /** The subagent's name, as the transcript refers to it. */
+  name: string;
+  /** The model it runs on, shown in mono beside the name. */
+  model: string;
+}
+/**
+ * Parallel workers with their own progress, models, and completions.
+ *
+ * @example
+ * import { SubagentList } from "@cueplusplus/ui/elements";
+ *
+ * <SubagentList
+ *   agents={[{ name: "Researcher", model: "Sonnet" }]}
+ *   completedCount={0}
+ *   progress={[40]}
+ *   showSummary={false}
+ *   summaryAgent={{ name: "Summarizer", model: "Haiku" }}
+ * />
+ */
+declare function SubagentList({ agents, completedCount, progress, showSummary, summaryAgent, className, ...props }: Omit<ComponentProps<"div">, "children" | "agents" | "completedCount" | "progress" | "showSummary" | "summaryAgent"> & {
+  /** Parallel workers shown as cards with name and model. */
+  agents: readonly SubagentItem[];
+  /** How many agents from the start are marked complete. */
+  completedCount: number;
+  /** Per-agent progress widths used while a worker is still running. */
+  progress: readonly number[];
+  /** When true the summary agent card is revealed under the list. */
+  showSummary: boolean;
+  /** Agent shown in the summary card once showSummary is true. */
+  summaryAgent: SubagentItem;
+}): import("react").JSX.Element;
+//#endregion
+export { SubagentItem, SubagentList };

package/dist/elements/subagent-list.js

@@ -0,0 +1,79 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { mono, paper } from "./surfaces.js";
+import { pct } from "./range.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { CheckIcon, Loader2Icon } from "lucide-react";
+//#region src/elements/subagent-list.tsx
+/**
+* Parallel workers with their own progress, models, and completions.
+*
+* @example
+* import { SubagentList } from "@cueplusplus/ui/elements";
+*
+* <SubagentList
+*   agents={[{ name: "Researcher", model: "Sonnet" }]}
+*   completedCount={0}
+*   progress={[40]}
+*   showSummary={false}
+*   summaryAgent={{ name: "Summarizer", model: "Haiku" }}
+* />
+*/
+function SubagentList({ agents, completedCount, progress, showSummary, summaryAgent, className, ...props }) {
+	return /* @__PURE__ */ jsxs("div", {
+		"data-slot": "subagent-list",
+		className: cn("flex min-h-[14.5rem] w-full max-w-xs flex-col gap-2", className),
+		...props,
+		children: [agents.map((agent, index) => {
+			const done = index < completedCount;
+			const width = progress[index] ?? 0;
+			return /* @__PURE__ */ jsxs("div", {
+				className: cn(paper, "flex flex-col gap-2 rounded-(--radius-overlay) px-3.5 py-2.5"),
+				children: [/* @__PURE__ */ jsxs("div", {
+					className: "flex items-center gap-2",
+					children: [
+						done ? /* @__PURE__ */ jsx(CheckIcon, { className: "cue-elements-fade-in cue-elements-zoom-in-90 cue-elements-animate-in size-3.5 shrink-0 text-ok duration-200" }) : /* @__PURE__ */ jsx(Loader2Icon, { className: "text-fg-subtle size-3.5 shrink-0 animate-spin motion-reduce:animate-none" }),
+						/* @__PURE__ */ jsx("span", {
+							className: "flex-1 truncate text-(length:--cue-text-body)",
+							children: agent.name
+						}),
+						/* @__PURE__ */ jsx("span", {
+							className: cn(mono, "text-fg-subtle"),
+							children: agent.model
+						})
+					]
+				}), /* @__PURE__ */ jsx("span", {
+					className: "bg-surface-2 h-[3px] w-full overflow-hidden rounded-full",
+					children: /* @__PURE__ */ jsx("span", {
+						className: cn("block h-full rounded-full transition-[width] duration-700", done ? "bg-ok/70" : "bg-accent"),
+						style: { width: `${pct(width, 100)}%` }
+					})
+				})]
+			}, agent.name);
+		}), showSummary && /* @__PURE__ */ jsxs("div", {
+			className: cn("bg-surface-1 border border-border", "cue-elements-fade-in cue-elements-slide-in-from-bottom-2 cue-elements-animate-in flex flex-col gap-2 rounded-(--radius-overlay) px-3.5 py-2.5 duration-300"),
+			children: [/* @__PURE__ */ jsxs("div", {
+				className: "flex items-center gap-2",
+				children: [
+					/* @__PURE__ */ jsx(Loader2Icon, { className: "text-fg-subtle size-3.5 shrink-0 animate-spin motion-reduce:animate-none" }),
+					/* @__PURE__ */ jsx("span", {
+						className: "flex-1 truncate text-(length:--cue-text-body)",
+						children: summaryAgent.name
+					}),
+					/* @__PURE__ */ jsx("span", {
+						className: cn("font-mono text-(length:--cue-text-label) tracking-tight", "text-fg-subtle"),
+						children: summaryAgent.model
+					})
+				]
+			}), /* @__PURE__ */ jsx("span", {
+				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-700",
+					style: { width: "42%" }
+				})
+			})]
+		})]
+	});
+}
+//#endregion
+export { SubagentList };

package/dist/elements/suggestions.d.ts

@@ -0,0 +1,30 @@
+import { ComponentProps } from "react";
+//#region src/elements/suggestions.d.ts
+interface SuggestionsProps extends Omit<ComponentProps<"div">, "children"> {
+  /** Follow-up prompt pills rendered in order. */
+  suggestions: readonly string[];
+  /** The pill currently pressed, or null when none is selected. */
+  selectedSuggestion: string | null;
+  /** Identity key that remounts the row so the stagger entrance can replay. */
+  cycle: number;
+  /** Called when a suggestion pill is pressed. */
+  onSuggestion: (suggestion: string) => void;
+  /** pills wraps suggestions into a centered row; list stacks them as full-width rows. */
+  variant?: "pills" | "list";
+}
+/**
+ * Prompt pills that stagger in after a reply and invite the next turn.
+ *
+ * @example
+ * import { Suggestions } from "@cueplusplus/ui/elements";
+ *
+ * <Suggestions
+ *   suggestions={["Explain more", "Show an example"]}
+ *   selectedSuggestion={null}
+ *   cycle={0}
+ *   onSuggestion={setSelected}
+ * />
+ */
+declare function Suggestions({ suggestions, selectedSuggestion, cycle, onSuggestion, variant, className, ...props }: SuggestionsProps): import("react").JSX.Element;
+//#endregion
+export { Suggestions, SuggestionsProps };

package/dist/elements/suggestions.js

@@ -0,0 +1,36 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { paper } from "./surfaces.js";
+import { jsx } from "react/jsx-runtime";
+//#region src/elements/suggestions.tsx
+/**
+* Prompt pills that stagger in after a reply and invite the next turn.
+*
+* @example
+* import { Suggestions } from "@cueplusplus/ui/elements";
+*
+* <Suggestions
+*   suggestions={["Explain more", "Show an example"]}
+*   selectedSuggestion={null}
+*   cycle={0}
+*   onSuggestion={setSelected}
+* />
+*/
+function Suggestions({ suggestions, selectedSuggestion, cycle, onSuggestion, variant = "pills", className, ...props }) {
+	const list = variant === "list";
+	return /* @__PURE__ */ jsx("div", {
+		"data-slot": "suggestions",
+		className: cn(list ? "flex w-full max-w-sm flex-col gap-2" : "flex max-w-md flex-wrap justify-center gap-2", className),
+		...props,
+		children: suggestions.map((suggestion, index) => /* @__PURE__ */ jsx("button", {
+			type: "button",
+			"aria-pressed": selectedSuggestion === suggestion,
+			onClick: () => onSuggestion(suggestion),
+			className: cn(paper, "cue-elements-fade-in cue-elements-slide-in-from-bottom-2 cue-elements-animate-in cue-elements-fill-mode-both flex cursor-pointer items-center text-(length:--cue-text-body) transition-transform duration-300 hover:-translate-y-px active:scale-[0.96] motion-reduce:animate-none", list ? "w-full rounded-(--radius-overlay) px-4 py-2.5 text-start" : "rounded-full px-4 py-2", selectedSuggestion === suggestion && "bg-accent text-accent-fg"),
+			style: { animationDelay: `${index * 70}ms` },
+			children: suggestion
+		}, suggestion))
+	}, cycle);
+}
+//#endregion
+export { Suggestions };

package/dist/elements/surfaces.d.ts

@@ -0,0 +1,85 @@
+import { ComponentProps, ReactNode } from "react";
+//#region src/elements/surfaces.d.ts
+/** A card's ground: the first raised surface, with the standard hairline. */
+declare const paper = "bg-surface-1 border border-border";
+/** The same card, one rung up, for anything that floats over the page. */
+declare const floating = "bg-surface-2 border border-border-overlay";
+/** The recessed fill: a request box, a code slab, a composer row. */
+declare const field = "bg-fg/[0.06]";
+/** {@link field} for something clickable. */
+declare const fieldInteractive = "bg-fg/[0.06] transition-colors hover:bg-fg/[0.09]";
+/** The press affordance: a 4% squash on pointer-down, stilled under reduced motion. */
+declare const pressable = "transition-transform duration-150 ease-[cubic-bezier(0.23,1,0.32,1)] active:scale-[0.96] motion-reduce:transition-none";
+/** A round chromeless icon button, with the ring cue puts on everything focusable. */
+declare const ghostButton = "flex items-center justify-center rounded-full text-fg-muted outline-none transition-[background-color,color,scale] duration-150 hover:bg-surface-2 hover:text-fg active:scale-[0.96] focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-offset-1 focus-visible:outline-accent motion-reduce:transition-none";
+/** The inverse fill: accent ground, accent ink — the one loud button in a panel. */
+declare const inkButton = "bg-accent text-accent-fg transition-[background-color,scale] duration-150 ease-[cubic-bezier(0.23,1,0.32,1)] hover:bg-accent-hover active:scale-[0.96] motion-reduce:transition-none";
+/** The stacked layer of an icon crossfade. Both layers share one grid cell. */
+declare const iconSwap = "[grid-area:1/1] transition-[opacity,scale,filter] duration-200 ease-[cubic-bezier(0.2,0,0,1)] motion-reduce:transition-none";
+/** The icon that is showing. */
+declare const iconSwapIn = "scale-100 opacity-100 blur-none";
+/** The icon that is leaving: shrunk, blurred and gone. */
+declare const iconSwapOut = "scale-[0.25] opacity-0 blur-[4px]";
+/** The stacked layer of a label crossfade, measured by {@link SwapLabel}. */
+declare const labelSwap = "col-start-1 row-start-1 flex w-max items-center gap-1.5 leading-none transition-[opacity,filter] duration-300 ease-[cubic-bezier(0.23,1,0.32,1)] motion-reduce:transition-none";
+/** The label that is showing. */
+declare const labelSwapIn = "opacity-100 blur-none";
+/** The label that is leaving, and which must not be selectable while it goes. */
+declare const labelSwapOut = "pointer-events-none select-none opacity-0 blur-[2px]";
+/**
+ * The disclosure panel's motion, written against Base UI's collapsible.
+ *
+ * `--collapsible-panel-height` and the starting/ending style attributes are Base
+ * UI's; Radix sets neither, which is why the four collapsible elements are
+ * wired to the peer this package already requires rather than to the one
+ * upstream's registry asks for.
+ */
+declare const collapsePanel = "h-(--collapsible-panel-height) overflow-hidden transition-[height] duration-200 ease-[cubic-bezier(0.32,0.72,0,1)] data-[ending-style]:h-0 data-[starting-style]:h-0 motion-reduce:transition-none";
+/** The streaming hue: what is happening right now, rather than what has happened. */
+declare const live = "text-stream";
+/** The metadata typeface: mono, one rung down, tight. Used about a hundred times. */
+declare const mono = "font-mono text-(length:--cue-text-label) tracking-tight";
+/**
+ * Scroll region for content that keeps its own whitespace. `whitespace-pre` in
+ * a bounded box clips a long line with no way to reach it, so the rows scroll
+ * instead.
+ *
+ * `codeSurface` wraps all the rows as one block, and the rows are its children.
+ * It cannot go on each row: `min-width: 100%` resolves against the scroll
+ * container's visible width rather than its scroll width, so a per-row width
+ * leaves every row except the longest ending its background at the fold.
+ */
+declare const codeScroll = "overflow-x-auto";
+/** The block inside {@link codeScroll} that all the rows share. */
+declare const codeSurface = "w-max min-w-full";
+/**
+ * A label that sweeps while something is still happening.
+ *
+ * The sweep is `.cue-elements-shimmer`, declared with its keyframes in
+ * `@cueplusplus/ui/elements.css`; without that stylesheet the label simply
+ * sits still, which is also what it does under `prefers-reduced-motion`.
+ */
+declare function ShimmerLabel({ active, className, ...props }: ComponentProps<"span"> & {
+  /** Whether the sweep is running. Defaults to `true`. */
+  active?: boolean;
+}): import("react").JSX.Element;
+/**
+ * Two labels stacked in one cell, with the box's width animating between them.
+ *
+ * A `ResizeObserver` measures the layer that is showing, because the crossfade
+ * is only half the effect — a "Searching…" that becomes "Searched" has to make
+ * the row shrink, and neither layer can size the box while both are in it.
+ *
+ * The layer that is leaving is `aria-hidden`, so the outgoing text is neither
+ * announced nor copied into a selection.
+ */
+declare function SwapLabel({ active, children, className }: {
+  /** Which of the two children is showing. */
+  active: 0 | 1;
+  /** Exactly two labels: the resting one and the active one. */
+  children: [ReactNode, ReactNode];
+  /** Extra classes for the measured box. */
+  className?: string;
+}): import("react").JSX.Element;
+//#endregion
+export { ShimmerLabel, SwapLabel, codeScroll, codeSurface, collapsePanel, field, fieldInteractive, floating, ghostButton, iconSwap, iconSwapIn, iconSwapOut, inkButton, labelSwap, labelSwapIn, labelSwapOut, live, mono, paper, pressable };

package/dist/elements/surfaces.js

@@ -0,0 +1,108 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { useLayoutEffect, useRef, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/elements/surfaces.tsx
+/** A card's ground: the first raised surface, with the standard hairline. */
+const paper = "bg-surface-1 border border-border";
+/** The same card, one rung up, for anything that floats over the page. */
+const floating = "bg-surface-2 border border-border-overlay";
+/** The recessed fill: a request box, a code slab, a composer row. */
+const field = "bg-fg/[0.06]";
+/** {@link field} for something clickable. */
+const fieldInteractive = "bg-fg/[0.06] transition-colors hover:bg-fg/[0.09]";
+/** The press affordance: a 4% squash on pointer-down, stilled under reduced motion. */
+const pressable = "transition-transform duration-150 ease-[cubic-bezier(0.23,1,0.32,1)] active:scale-[0.96] motion-reduce:transition-none";
+/** A round chromeless icon button, with the ring cue puts on everything focusable. */
+const ghostButton = "flex items-center justify-center rounded-full text-fg-muted outline-none transition-[background-color,color,scale] duration-150 hover:bg-surface-2 hover:text-fg active:scale-[0.96] focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-offset-1 focus-visible:outline-accent motion-reduce:transition-none";
+/** The inverse fill: accent ground, accent ink — the one loud button in a panel. */
+const inkButton = "bg-accent text-accent-fg transition-[background-color,scale] duration-150 ease-[cubic-bezier(0.23,1,0.32,1)] hover:bg-accent-hover active:scale-[0.96] motion-reduce:transition-none";
+/** The stacked layer of an icon crossfade. Both layers share one grid cell. */
+const iconSwap = "[grid-area:1/1] transition-[opacity,scale,filter] duration-200 ease-[cubic-bezier(0.2,0,0,1)] motion-reduce:transition-none";
+/** The icon that is showing. */
+const iconSwapIn = "scale-100 opacity-100 blur-none";
+/** The icon that is leaving: shrunk, blurred and gone. */
+const iconSwapOut = "scale-[0.25] opacity-0 blur-[4px]";
+/** The stacked layer of a label crossfade, measured by {@link SwapLabel}. */
+const labelSwap = "col-start-1 row-start-1 flex w-max items-center gap-1.5 leading-none transition-[opacity,filter] duration-300 ease-[cubic-bezier(0.23,1,0.32,1)] motion-reduce:transition-none";
+/** The label that is showing. */
+const labelSwapIn = "opacity-100 blur-none";
+/** The label that is leaving, and which must not be selectable while it goes. */
+const labelSwapOut = "pointer-events-none select-none opacity-0 blur-[2px]";
+/**
+* The disclosure panel's motion, written against Base UI's collapsible.
+*
+* `--collapsible-panel-height` and the starting/ending style attributes are Base
+* UI's; Radix sets neither, which is why the four collapsible elements are
+* wired to the peer this package already requires rather than to the one
+* upstream's registry asks for.
+*/
+const collapsePanel = "h-(--collapsible-panel-height) overflow-hidden transition-[height] duration-200 ease-[cubic-bezier(0.32,0.72,0,1)] data-[ending-style]:h-0 data-[starting-style]:h-0 motion-reduce:transition-none";
+/** The streaming hue: what is happening right now, rather than what has happened. */
+const live = "text-stream";
+/** The metadata typeface: mono, one rung down, tight. Used about a hundred times. */
+const mono = "font-mono text-(length:--cue-text-label) tracking-tight";
+/**
+* Scroll region for content that keeps its own whitespace. `whitespace-pre` in
+* a bounded box clips a long line with no way to reach it, so the rows scroll
+* instead.
+*
+* `codeSurface` wraps all the rows as one block, and the rows are its children.
+* It cannot go on each row: `min-width: 100%` resolves against the scroll
+* container's visible width rather than its scroll width, so a per-row width
+* leaves every row except the longest ending its background at the fold.
+*/
+const codeScroll = "overflow-x-auto";
+/** The block inside {@link codeScroll} that all the rows share. */
+const codeSurface = "w-max min-w-full";
+/**
+* A label that sweeps while something is still happening.
+*
+* The sweep is `.cue-elements-shimmer`, declared with its keyframes in
+* `@cueplusplus/ui/elements.css`; without that stylesheet the label simply
+* sits still, which is also what it does under `prefers-reduced-motion`.
+*/
+function ShimmerLabel({ active = true, className, ...props }) {
+	return /* @__PURE__ */ jsx("span", {
+		"data-slot": "shimmer-label",
+		className: cn(active && "cue-elements-shimmer motion-reduce:animate-none", className),
+		...props
+	});
+}
+/**
+* Two labels stacked in one cell, with the box's width animating between them.
+*
+* A `ResizeObserver` measures the layer that is showing, because the crossfade
+* is only half the effect — a "Searching…" that becomes "Searched" has to make
+* the row shrink, and neither layer can size the box while both are in it.
+*
+* The layer that is leaving is `aria-hidden`, so the outgoing text is neither
+* announced nor copied into a selection.
+*/
+function SwapLabel({ active, children, className }) {
+	const restingRef = useRef(null);
+	const activeRef = useRef(null);
+	const [width, setWidth] = useState(null);
+	useLayoutEffect(() => {
+		const target = (active === 0 ? restingRef : activeRef).current;
+		if (!target) return void 0;
+		const measure = () => setWidth(Math.ceil(target.getBoundingClientRect().width));
+		measure();
+		const observer = new ResizeObserver(measure);
+		observer.observe(target);
+		return () => observer.disconnect();
+	}, [active]);
+	return /* @__PURE__ */ jsx("span", {
+		"data-slot": "swap-label",
+		style: width === null ? void 0 : { width },
+		className: cn("grid overflow-x-clip transition-[width] duration-300 ease-[cubic-bezier(0.23,1,0.32,1)] motion-reduce:transition-none", className),
+		children: children.map((layer, index) => /* @__PURE__ */ jsx("span", {
+			ref: index === 0 ? restingRef : activeRef,
+			"aria-hidden": active !== index,
+			className: cn(labelSwap, active === index ? labelSwapIn : labelSwapOut),
+			children: layer
+		}, index))
+	});
+}
+//#endregion
+export { ShimmerLabel, SwapLabel, codeScroll, codeSurface, collapsePanel, field, fieldInteractive, floating, ghostButton, iconSwap, iconSwapIn, iconSwapOut, inkButton, labelSwap, labelSwapIn, labelSwapOut, live, mono, paper, pressable };

package/dist/elements/tail-status.d.ts

@@ -0,0 +1,131 @@
+import * as React from "react";
+//#region src/elements/tail-status.d.ts
+/**
+ * How loudly the foot of the transcript is speaking.
+ *
+ * The attribute is Cursor's — it stamps `data-priority` on this row and on no
+ * other — and the two values are cue's smallest honest reading of it: a row is
+ * either narration a reader may ignore, or a line they are meant to act on.
+ * Nothing else in this family paints from it, so a console that wants a third
+ * level can add one in CSS against the same attribute.
+ */
+type TailPriority = "normal" | "attention";
+interface TailStatusProps extends Omit<React.ComponentPropsWithoutRef<"div">, "children"> {
+  /**
+   * What is happening, in two or three words: `Running commands`,
+   * `Searching the codebase`. `TAIL_ACTIONS` is the shipped vocabulary and this
+   * prop is a plain string, so a product with its own verbs is not stuck with
+   * these ten.
+   */
+  action: string;
+  /**
+   * The thing the action is happening to — a path, a query, a topic. Truncates
+   * on its own so the action never has to; a sidebar transcript is 280px wide
+   * and a status line that elides its verb has said nothing.
+   */
+  detail?: string;
+  /**
+   * Whether the action is still going. `true` by default, because this row is
+   * the live one; turn it off for `Idle`, `Interrupted` and `Aborted`, which
+   * stops the sweep and empties the spinner's slot without moving the text.
+   */
+  active?: boolean;
+  /**
+   * Whether a new `action` animates into the row that is already there, or
+   * simply replaces the text.
+   *
+   * Cursor's flag, and the reason it needs one: a narration line that changes
+   * every few hundred milliseconds should read as one row being updated, while
+   * a line that means something *different* should read as a new row. `true`
+   * (the default) keys the label on its own text so each new action fades in
+   * where the last one was; `false` leaves it unkeyed, and the words change
+   * with no motion at all. A reduced-motion reader gets the second behaviour
+   * either way.
+   */
+  updatesInPlace?: boolean;
+  /** How loudly this row is speaking. See {@link TailPriority}. */
+  priority?: TailPriority;
+  /**
+   * Stop the run. The inline control exists only when this is given — Cursor's
+   * rule, and the right one: a Cancel that cannot cancel is worse than no
+   * Cancel.
+   */
+  onCancel?: () => void;
+  /**
+   * What the stop control is called. `Cancel` is Cursor's word; opencode uses
+   * `Interrupt` and `Stop` for the same button.
+   */
+  cancelLabel?: string;
+  /**
+   * Whether this row is a live region — whether a screen reader is told each
+   * time the action changes.
+   *
+   * **Answers itself by default, and that default is the interesting part.**
+   * Left alone the row speaks when it is the only thing that can, and goes
+   * quiet the moment a {@link LiveRegionAnnouncer} is mounted anywhere on the
+   * page: the announcer's table covers the same transitions this row narrates,
+   * so a console with both — the ordinary composition — would otherwise have
+   * every state read out twice, out of step, because the two regions update at
+   * different moments.
+   *
+   * The row is the one that defers because the announcer is the better speaker:
+   * it is a queue, spaced and depth-limited and paused while the page is hidden
+   * or a modal has the reader, and it is mounted empty and left mounted, which
+   * is the only way a live region is reliably announced. This row changes
+   * several times a second and comes and goes with the run.
+   *
+   * Set it explicitly to overrule that — `true` for a console whose announcer
+   * is fed something other than these actions, `false` for one that narrates
+   * the foot of the transcript some other way. An explicit answer always wins.
+   */
+  announce?: boolean;
+}
+/**
+ * The live row at the foot of a transcript: what the run is doing, right now.
+ *
+ * The one row every shipping agent UI has and no component catalogue ships. It
+ * is not a spinner and not a toast — it is a transcript row with
+ * `role="status"`, which is what makes it the *only* element in this family a
+ * screen reader is told about without being asked. Everything else here is
+ * drawn and left alone; this one announces itself politely each time the action
+ * changes, which is exactly the behaviour a person who cannot see the spinner
+ * needs and exactly the behaviour that becomes unbearable if it is used for
+ * anything else. One per transcript, at the foot, and nowhere else.
+ *
+ * **Unless something better is speaking.** {@link LiveRegionAnnouncer} is this
+ * family's other live region, and its table of transitions covers what this row
+ * narrates; a console that mounts both would have the run read out twice. So
+ * mounting an announcer takes the speech away from this row automatically — the
+ * words stay on the screen, the `role="status"` goes, and `data-announces` says
+ * which of the two it is doing. {@link TailStatusProps.announce} overrules it in
+ * either direction.
+ *
+ * The action and the detail are separate props rather than one composed string
+ * because they truncate differently: the action is short and must survive, the
+ * detail is a path and must not push it off the row.
+ *
+ * State is a prop, as everywhere in this family. The row holds no timer, counts
+ * nothing, and does not know whether the run is healthy — `active` says whether
+ * the sweep runs, `action` says what it says, and the caller changes both.
+ *
+ * @example
+ * import { TailStatus, TAIL_ACTIONS } from "@cueplusplus/ui/elements";
+ *
+ * <TailStatus
+ *   action={TAIL_ACTIONS.searchingCode}
+ *   detail="composer.tsx"
+ *   onCancel={stop}
+ * />
+ * @example
+ * // Settled: no sweep, no spinner, and the text changes without motion.
+ * <TailStatus action={TAIL_ACTIONS.interrupted} active={false} updatesInPlace={false} />
+ * @example
+ * // Composed with the announcer: this row draws the state, the queue speaks it.
+ * <>
+ *   <TailStatus action={TAIL_ACTIONS.running} detail="pnpm test" />
+ *   <LiveRegionAnnouncer messages={log} />
+ * </>
+ */
+declare const TailStatus: React.ForwardRefExoticComponent<TailStatusProps & React.RefAttributes<HTMLDivElement>>;
+//#endregion
+export { TailPriority, TailStatus, TailStatusProps };

package/dist/elements/tail-status.js

@@ -0,0 +1,94 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { ShimmerLabel, ghostButton, mono } from "./surfaces.js";
+import { useAnnouncerPresent } from "./live-region-announcer.js";
+import * as React from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { Loader2Icon } from "lucide-react";
+//#region src/elements/tail-status.tsx
+/**
+* The live row at the foot of a transcript: what the run is doing, right now.
+*
+* The one row every shipping agent UI has and no component catalogue ships. It
+* is not a spinner and not a toast — it is a transcript row with
+* `role="status"`, which is what makes it the *only* element in this family a
+* screen reader is told about without being asked. Everything else here is
+* drawn and left alone; this one announces itself politely each time the action
+* changes, which is exactly the behaviour a person who cannot see the spinner
+* needs and exactly the behaviour that becomes unbearable if it is used for
+* anything else. One per transcript, at the foot, and nowhere else.
+*
+* **Unless something better is speaking.** {@link LiveRegionAnnouncer} is this
+* family's other live region, and its table of transitions covers what this row
+* narrates; a console that mounts both would have the run read out twice. So
+* mounting an announcer takes the speech away from this row automatically — the
+* words stay on the screen, the `role="status"` goes, and `data-announces` says
+* which of the two it is doing. {@link TailStatusProps.announce} overrules it in
+* either direction.
+*
+* The action and the detail are separate props rather than one composed string
+* because they truncate differently: the action is short and must survive, the
+* detail is a path and must not push it off the row.
+*
+* State is a prop, as everywhere in this family. The row holds no timer, counts
+* nothing, and does not know whether the run is healthy — `active` says whether
+* the sweep runs, `action` says what it says, and the caller changes both.
+*
+* @example
+* import { TailStatus, TAIL_ACTIONS } from "@cueplusplus/ui/elements";
+*
+* <TailStatus
+*   action={TAIL_ACTIONS.searchingCode}
+*   detail="composer.tsx"
+*   onCancel={stop}
+* />
+* @example
+* // Settled: no sweep, no spinner, and the text changes without motion.
+* <TailStatus action={TAIL_ACTIONS.interrupted} active={false} updatesInPlace={false} />
+* @example
+* // Composed with the announcer: this row draws the state, the queue speaks it.
+* <>
+*   <TailStatus action={TAIL_ACTIONS.running} detail="pnpm test" />
+*   <LiveRegionAnnouncer messages={log} />
+* </>
+*/
+const TailStatus = React.forwardRef(function TailStatus({ action, detail, active = true, updatesInPlace = true, priority = "normal", onCancel, cancelLabel = "Cancel", announce, className, ...elementProps }, ref) {
+	const spokenFor = useAnnouncerPresent();
+	const announces = announce ?? !spokenFor;
+	return /* @__PURE__ */ jsxs("div", {
+		ref,
+		role: announces ? "status" : void 0,
+		"data-slot": "tail-status",
+		"data-announces": String(announces),
+		"data-priority": priority,
+		"data-updates-in-place": String(updatesInPlace),
+		className: cn("flex w-full items-center gap-2.5 py-1.5", className),
+		...elementProps,
+		children: [
+			/* @__PURE__ */ jsx("span", {
+				"aria-hidden": true,
+				className: "flex size-3.5 shrink-0 items-center justify-center",
+				children: active ? /* @__PURE__ */ jsx(Loader2Icon, { className: "size-3.5 animate-spin text-stream motion-reduce:animate-none" }) : null
+			}),
+			/* @__PURE__ */ jsxs("span", {
+				className: cn("flex min-w-0 flex-1 items-baseline gap-1.5 text-(length:--cue-text-ui)", updatesInPlace && "cue-elements-fade-in cue-elements-animate-in duration-200 motion-reduce:animate-none"),
+				children: [/* @__PURE__ */ jsx(ShimmerLabel, {
+					active,
+					className: cn("shrink-0", priority === "attention" ? "text-fg" : "text-fg-muted"),
+					children: action
+				}), detail === void 0 ? null : /* @__PURE__ */ jsx("span", {
+					className: cn(mono, "text-fg-subtle min-w-0 truncate"),
+					children: detail
+				})]
+			}, updatesInPlace ? action : void 0),
+			onCancel === void 0 ? null : /* @__PURE__ */ jsx("button", {
+				type: "button",
+				onClick: onCancel,
+				className: cn(ghostButton, mono, "shrink-0 rounded-(--radius-control) px-2 py-1 uppercase"),
+				children: cancelLabel
+			})
+		]
+	});
+});
+//#endregion
+export { TailStatus };