@cueplusplus/ui 0.2.0 → 0.5.0

package/dist/elements/tool-call.js

@@ -0,0 +1,85 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { ShimmerLabel, SwapLabel, collapsePanel, field, mono } from "./surfaces.js";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { Collapsible } from "@base-ui/react/collapsible";
+import { CheckIcon, ChevronRightIcon } from "lucide-react";
+//#region src/elements/tool-call.tsx
+/**
+* One tool invocation with its request and result tucked behind a disclosure.
+*
+* @example
+* import { ToolCall } from "@cueplusplus/ui/elements";
+*
+* <ToolCall
+*   label="Searched"
+*   activeLabel="Searching"
+*   query="composer props"
+*   request='{"q":"composer"}'
+*   result='{"hits":2}'
+*   running={false}
+*   open
+*   onOpenChange={setOpen}
+* />
+*/
+function ToolCall({ label, activeLabel, query, request, result, running, open, onOpenChange, className }) {
+	return /* @__PURE__ */ jsxs(Collapsible.Root, {
+		"data-slot": "tool-call",
+		open,
+		onOpenChange,
+		className: cn("w-full max-w-sm", className),
+		children: [/* @__PURE__ */ jsxs(Collapsible.Trigger, {
+			className: "group/trigger text-fg-muted hover:text-fg flex items-center gap-2 rounded-(--radius-control) py-1 text-(length:--cue-text-body) transition-colors outline-none focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-offset-1 focus-visible:outline-accent",
+			children: [
+				/* @__PURE__ */ jsx(ChevronRightIcon, { className: "size-3.5 shrink-0 opacity-60 transition-transform duration-200 ease-[cubic-bezier(0.32,0.72,0,1)] group-data-[panel-open]/trigger:rotate-90 motion-reduce:transition-none" }),
+				/* @__PURE__ */ jsxs(SwapLabel, {
+					active: running ? 0 : 1,
+					className: "text-start",
+					children: [/* @__PURE__ */ jsx(ShimmerLabel, {
+						active: running,
+						className: "relative inline-block leading-none",
+						children: activeLabel
+					}), /* @__PURE__ */ jsx(Fragment, { children: label })]
+				}),
+				/* @__PURE__ */ jsx("span", {
+					className: cn(mono, "bg-surface-2 text-fg-muted rounded-(--radius-control) px-1.5 py-0.5"),
+					children: query
+				}),
+				/* @__PURE__ */ jsx("span", {
+					className: "ms-auto flex w-4 items-center justify-end",
+					children: !running && /* @__PURE__ */ jsx(CheckIcon, { className: "cue-elements-fade-in cue-elements-zoom-in-90 cue-elements-animate-in size-3.5 text-ok duration-200" })
+				})
+			]
+		}), /* @__PURE__ */ jsx(Collapsible.Panel, {
+			className: cn(collapsePanel, "outline-none"),
+			children: /* @__PURE__ */ jsxs("div", {
+				className: cn(field, "mt-2 overflow-hidden rounded-(--radius-overlay) text-(length:--cue-text-ui)"),
+				children: [
+					/* @__PURE__ */ jsxs("div", {
+						className: "px-3.5 pt-2.5 pb-2",
+						children: [/* @__PURE__ */ jsx("p", {
+							className: cn(mono, "text-fg-subtle mb-1"),
+							children: "Request"
+						}), /* @__PURE__ */ jsx("p", {
+							className: "text-fg-muted font-mono",
+							children: request
+						})]
+					}),
+					/* @__PURE__ */ jsx("div", { className: "bg-surface-2 mx-3.5 h-px" }),
+					/* @__PURE__ */ jsxs("div", {
+						className: "px-3.5 pt-2 pb-2.5",
+						children: [/* @__PURE__ */ jsx("p", {
+							className: cn(mono, "text-fg-subtle mb-1"),
+							children: "Result"
+						}), /* @__PURE__ */ jsx("p", {
+							className: "text-fg",
+							children: result
+						})]
+					})
+				]
+			})
+		})]
+	});
+}
+//#endregion
+export { ToolCall };

package/dist/elements/tool-error.d.ts

@@ -0,0 +1,39 @@
+import { ComponentProps } from "react";
+//#region src/elements/tool-error.d.ts
+/**
+ * One call failed. The error, the attempt count, and a retry that doesn't restart the
+ * turn.
+ *
+ * @example
+ * import { ToolError } from "@cueplusplus/ui/elements";
+ *
+ * <ToolError
+ *   name="fetch"
+ *   target="https://api.example.com/v1/issues"
+ *   message="ETIMEDOUT after 30000ms"
+ *   attempt={2}
+ *   maxAttempts={3}
+ *   retrying={false}
+ *   onRetry={retry}
+ * />
+ */
+declare function ToolError({ name, target, message, attempt, maxAttempts, retrying, onRetry, onSkip, className, ...props }: Omit<ComponentProps<"div">, "children" | "name" | "target" | "message" | "attempt" | "maxAttempts" | "retrying" | "onRetry" | "onSkip"> & {
+  /** Tool that failed. */
+  name: string;
+  /** What it was called against. */
+  target: string;
+  /** The raw error, shown in mono rather than reworded. */
+  message: string;
+  /** Which attempt this was. */
+  attempt: number;
+  /** How many the runtime will make. */
+  maxAttempts: number;
+  /** Swaps the retry control for a spinner and disables it. */
+  retrying: boolean;
+  /** Called to run the call again without restarting the turn. */
+  onRetry?: () => void;
+  /** Called to give up on this call and let the turn continue. */
+  onSkip?: () => void;
+}): import("react").JSX.Element;
+//#endregion
+export { ToolError };

package/dist/elements/tool-error.js

@@ -0,0 +1,76 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { field, mono, paper } from "./surfaces.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { AlertCircleIcon, Loader2Icon, RotateCwIcon } from "lucide-react";
+//#region src/elements/tool-error.tsx
+/**
+* One call failed. The error, the attempt count, and a retry that doesn't restart the
+* turn.
+*
+* @example
+* import { ToolError } from "@cueplusplus/ui/elements";
+*
+* <ToolError
+*   name="fetch"
+*   target="https://api.example.com/v1/issues"
+*   message="ETIMEDOUT after 30000ms"
+*   attempt={2}
+*   maxAttempts={3}
+*   retrying={false}
+*   onRetry={retry}
+* />
+*/
+function ToolError({ name, target, message, attempt, maxAttempts, retrying, onRetry, onSkip, className, ...props }) {
+	return /* @__PURE__ */ jsxs("div", {
+		"data-slot": "tool-error",
+		className: cn(paper, "flex w-full max-w-sm flex-col gap-3 rounded-(--radius-overlay) p-3.5", className),
+		...props,
+		children: [
+			/* @__PURE__ */ jsxs("div", {
+				className: "flex items-center gap-2.5",
+				children: [
+					/* @__PURE__ */ jsx(AlertCircleIcon, { className: "size-3.5 shrink-0 text-danger" }),
+					/* @__PURE__ */ jsx("span", {
+						className: cn(mono, "text-fg-muted shrink-0"),
+						children: name
+					}),
+					/* @__PURE__ */ jsx("span", {
+						className: "text-fg-muted min-w-0 flex-1 truncate text-(length:--cue-text-body)",
+						children: target
+					}),
+					/* @__PURE__ */ jsxs("span", {
+						className: cn(mono, "text-fg-subtle shrink-0 tabular-nums"),
+						children: [
+							attempt,
+							"/",
+							maxAttempts
+						]
+					})
+				]
+			}),
+			/* @__PURE__ */ jsx("div", {
+				className: cn(field, "rounded-(--radius-surface) px-3 py-2 font-mono text-(length:--cue-text-label) leading-relaxed text-danger"),
+				children: message
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				className: "flex items-center justify-end gap-2",
+				children: [/* @__PURE__ */ jsx("button", {
+					type: "button",
+					onClick: onSkip,
+					disabled: !onSkip,
+					className: "text-fg-muted hover:bg-surface-2 hover:text-fg h-7 rounded-full px-2.5 text-(length:--cue-text-ui) font-medium transition-[background-color,color,scale] duration-150 active:scale-[0.96] disabled:pointer-events-none disabled:opacity-30",
+					children: "Skip"
+				}), /* @__PURE__ */ jsxs("button", {
+					type: "button",
+					onClick: onRetry,
+					disabled: retrying,
+					className: "text-fg-muted hover:bg-surface-2 hover:text-fg flex h-7 items-center gap-1.5 rounded-full px-2.5 text-(length:--cue-text-ui) font-medium transition-[background-color,color,scale] duration-150 active:scale-[0.96] disabled:pointer-events-none",
+					children: [retrying ? /* @__PURE__ */ jsx(Loader2Icon, { className: "size-3 animate-spin motion-reduce:animate-none" }) : /* @__PURE__ */ jsx(RotateCwIcon, { className: "size-3" }), retrying ? "Retrying" : "Retry"]
+				})]
+			})
+		]
+	});
+}
+//#endregion
+export { ToolError };

package/dist/elements/tool-group.d.ts

@@ -0,0 +1,45 @@
+import { ComponentProps } from "react";
+//#region src/elements/tool-group.d.ts
+/** Where one tool in a group got to: still running, finished, or failed. */
+type GroupedToolState = "running" | "done" | "failed";
+/** One row of a tool group: what ran, against what, and how it ended. */
+interface GroupedTool {
+  /** Stable identity for the row key. */
+  id: string;
+  /** Tool name, rendered in mono. */
+  name: string;
+  /** What the call acted on: a path, a query, an id. */
+  target: string;
+  /** Per-call state, rolled up into the header summary. */
+  state: GroupedToolState;
+  /** Printed once the call settles. Omit while running. */
+  durationMs?: number;
+}
+/**
+ * Calls that went out together, collapsed to one row until you want the detail.
+ *
+ * @example
+ * import { ToolGroup } from "@cueplusplus/ui/elements";
+ *
+ * <ToolGroup
+ *   label="Read 4 files in parallel"
+ *   tools={tools}
+ *   open={open}
+ *   onOpenChange={setOpen}
+ * />
+ */
+declare function ToolGroup({ label, tools, open, onOpenChange, className, ...props }: Omit<ComponentProps<"div">, "children" | "label" | "tools" | "open" | "onOpenChange"> & {
+  /** What the group did, as one line. */
+  label: string;
+  /**
+   * Calls issued together. The header summarizes them: progress while any run,
+   * failures if any failed, otherwise the count.
+   */
+  tools: readonly GroupedTool[];
+  /** Whether the per-call list is expanded. */
+  open: boolean;
+  /** Called when the group is expanded or collapsed. */
+  onOpenChange?: (open: boolean) => void;
+}): import("react").JSX.Element;
+//#endregion
+export { GroupedTool, GroupedToolState, ToolGroup };

package/dist/elements/tool-group.js

@@ -0,0 +1,71 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { mono, paper } from "./surfaces.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { CheckIcon, ChevronRightIcon, Loader2Icon, XIcon } from "lucide-react";
+//#region src/elements/tool-group.tsx
+/**
+* Calls that went out together, collapsed to one row until you want the detail.
+*
+* @example
+* import { ToolGroup } from "@cueplusplus/ui/elements";
+*
+* <ToolGroup
+*   label="Read 4 files in parallel"
+*   tools={tools}
+*   open={open}
+*   onOpenChange={setOpen}
+* />
+*/
+function ToolGroup({ label, tools, open, onOpenChange, className, ...props }) {
+	const running = tools.filter((tool) => tool.state === "running").length;
+	const failed = tools.filter((tool) => tool.state === "failed").length;
+	return /* @__PURE__ */ jsxs("div", {
+		"data-slot": "tool-group",
+		className: cn(paper, "flex w-full max-w-sm flex-col overflow-hidden rounded-(--radius-overlay)", className),
+		...props,
+		children: [/* @__PURE__ */ jsxs("button", {
+			type: "button",
+			"aria-expanded": open,
+			onClick: () => onOpenChange?.(!open),
+			className: "hover:bg-surface-1 flex items-center gap-2.5 px-3.5 py-2.5 text-start transition-colors",
+			children: [
+				/* @__PURE__ */ jsx(ChevronRightIcon, { className: cn("text-fg-subtle size-3 shrink-0 transition-transform duration-200 motion-reduce:transition-none", open && "rotate-90") }),
+				/* @__PURE__ */ jsx("span", {
+					className: "min-w-0 flex-1 truncate text-(length:--cue-text-body)",
+					children: label
+				}),
+				/* @__PURE__ */ jsx("span", {
+					className: cn(mono, "text-fg-subtle shrink-0 tabular-nums"),
+					children: running > 0 ? `${tools.length - running}/${tools.length}` : failed > 0 ? `${failed} failed` : `${tools.length} done`
+				}),
+				running > 0 ? /* @__PURE__ */ jsx(Loader2Icon, { className: "text-fg-subtle size-3.5 shrink-0 animate-spin motion-reduce:animate-none" }) : failed > 0 ? /* @__PURE__ */ jsx(XIcon, { className: "size-3.5 shrink-0 text-danger" }) : /* @__PURE__ */ jsx(CheckIcon, { className: "size-3.5 shrink-0 text-ok" })
+			]
+		}), open && /* @__PURE__ */ jsx("div", {
+			className: "border-border cue-elements-fade-in cue-elements-slide-in-from-top-1 cue-elements-animate-in flex flex-col border-t duration-200",
+			children: tools.map((tool) => /* @__PURE__ */ jsxs("div", {
+				className: "flex items-center gap-2.5 px-3.5 py-2",
+				children: [
+					/* @__PURE__ */ jsx("span", {
+						className: "flex size-3.5 shrink-0 items-center justify-center",
+						children: tool.state === "running" ? /* @__PURE__ */ jsx(Loader2Icon, { className: "text-fg-subtle size-3 animate-spin motion-reduce:animate-none" }) : tool.state === "failed" ? /* @__PURE__ */ jsx(XIcon, { className: "size-3 text-danger" }) : /* @__PURE__ */ jsx(CheckIcon, { className: "size-3 text-ok" })
+					}),
+					/* @__PURE__ */ jsx("span", {
+						className: cn("font-mono text-(length:--cue-text-label) tracking-tight", "text-fg-muted shrink-0"),
+						children: tool.name
+					}),
+					/* @__PURE__ */ jsx("span", {
+						className: "text-fg-muted min-w-0 flex-1 truncate text-(length:--cue-text-body)",
+						children: tool.target
+					}),
+					tool.durationMs !== void 0 && /* @__PURE__ */ jsxs("span", {
+						className: cn("font-mono text-(length:--cue-text-label) tracking-tight", "text-fg-subtle shrink-0 tabular-nums"),
+						children: [tool.durationMs, "ms"]
+					})
+				]
+			}, tool.id))
+		})]
+	});
+}
+//#endregion
+export { ToolGroup };

package/dist/elements/tool-timeline.d.ts

@@ -0,0 +1,65 @@
+import { LucideIcon } from "lucide-react";
+//#region src/elements/tool-timeline.d.ts
+/** One thing the session did, said as a verb and the thing it was done to. */
+interface TimelineStep {
+  /** What was done — `Read`, `Edited`, `Ran`. It shimmers while it is the live step. */
+  verb: string;
+  /** What it was done to, in a mono chip. Also the step's key, so it has to be distinct. */
+  chip: string;
+  /** The glyph beside the verb, as a `lucide-react` component rather than an element. */
+  icon: LucideIcon;
+}
+/** One file the session touched, with the lines it gained and lost. */
+interface TimelineStat {
+  /** The path, in a mono chip. Also the row's key. */
+  file: string;
+  /** Lines added, shown in the ok hue. Omit for a file that only lost lines. */
+  added?: number;
+  /** Lines removed, shown in the danger hue. Omit for a file that only gained them. */
+  removed?: number;
+}
+/**
+ * What a session summary is told: its steps, its labels, and the files it ended up
+ * changing.
+ */
+interface ToolTimelineProps {
+  /** Working-session verbs, chips, and icons to reveal over time. */
+  steps: readonly TimelineStep[];
+  /** How many steps from the start are currently shown. */
+  visibleSteps: number;
+  /** When true the trigger shows Working with a shimmer and elapsed timer. */
+  streaming: boolean;
+  /** Whether the collapsible timeline body is expanded. */
+  open: boolean;
+  /** Called when the user expands or collapses the timeline. */
+  onOpenChange: (open: boolean) => void;
+  /** Trigger label once streaming finishes. */
+  restingLabel: string;
+  /** Full-size live label while streaming, for example Working for 12s. */
+  activeLabel: string;
+  /** Per-file addition and removal counts listed under the steps. */
+  stats: TimelineStat[];
+  /** Extra classes merged onto the root. */
+  className?: string;
+}
+/**
+ * A whole working session summarized as verbs, targets, and file stats.
+ *
+ * @example
+ * import { FileSearchIcon } from "lucide-react";
+ * import { ToolTimeline } from "@cueplusplus/ui/elements";
+ *
+ * <ToolTimeline
+ *   steps={[{ verb: "Read", chip: "thread.tsx", icon: FileSearchIcon }]}
+ *   visibleSteps={1}
+ *   streaming
+ *   open
+ *   onOpenChange={setOpen}
+ *   restingLabel="Worked for 12s"
+ *   activeLabel="Working for 12s"
+ *   stats={[{ file: "thread.tsx", added: 4, removed: 1 }]}
+ * />
+ */
+declare function ToolTimeline({ steps, visibleSteps, streaming, open, onOpenChange, restingLabel, activeLabel, stats, className }: ToolTimelineProps): import("react").JSX.Element;
+//#endregion
+export { TimelineStat, TimelineStep, ToolTimeline, ToolTimelineProps };

package/dist/elements/tool-timeline.js

@@ -0,0 +1,88 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { ShimmerLabel, SwapLabel, collapsePanel } from "./surfaces.js";
+import { take } from "./range.js";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { Collapsible } from "@base-ui/react/collapsible";
+import { ChevronRightIcon } from "lucide-react";
+//#region src/elements/tool-timeline.tsx
+/**
+* A whole working session summarized as verbs, targets, and file stats.
+*
+* @example
+* import { FileSearchIcon } from "lucide-react";
+* import { ToolTimeline } from "@cueplusplus/ui/elements";
+*
+* <ToolTimeline
+*   steps={[{ verb: "Read", chip: "thread.tsx", icon: FileSearchIcon }]}
+*   visibleSteps={1}
+*   streaming
+*   open
+*   onOpenChange={setOpen}
+*   restingLabel="Worked for 12s"
+*   activeLabel="Working for 12s"
+*   stats={[{ file: "thread.tsx", added: 4, removed: 1 }]}
+* />
+*/
+function ToolTimeline({ steps, visibleSteps, streaming, open, onOpenChange, restingLabel, activeLabel, stats, className }) {
+	return /* @__PURE__ */ jsxs(Collapsible.Root, {
+		"data-slot": "tool-timeline",
+		open,
+		onOpenChange,
+		className: cn("w-full max-w-sm", className),
+		children: [/* @__PURE__ */ jsxs(Collapsible.Trigger, {
+			className: "group/trigger text-fg-muted hover:text-fg flex items-center gap-1.5 rounded-(--radius-control) py-1 text-(length:--cue-text-body) transition-colors outline-none focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-offset-1 focus-visible:outline-accent",
+			children: [/* @__PURE__ */ jsx(ChevronRightIcon, { className: "size-3.5 shrink-0 opacity-60 transition-transform duration-200 ease-[cubic-bezier(0.32,0.72,0,1)] group-data-[panel-open]/trigger:rotate-90 motion-reduce:transition-none" }), /* @__PURE__ */ jsxs(SwapLabel, {
+				active: streaming ? 0 : 1,
+				className: "text-start tabular-nums",
+				children: [/* @__PURE__ */ jsx(ShimmerLabel, {
+					active: streaming,
+					className: "relative inline-block leading-none",
+					children: activeLabel
+				}), /* @__PURE__ */ jsx(Fragment, { children: restingLabel })]
+			})]
+		}), /* @__PURE__ */ jsx(Collapsible.Panel, {
+			className: cn(collapsePanel, "outline-none"),
+			children: /* @__PURE__ */ jsxs("div", {
+				className: "flex flex-col gap-2.5 ps-4 pt-2.5",
+				children: [take(steps, visibleSteps).map((step, index, shown) => {
+					const Icon = step.icon;
+					const active = streaming && index === shown.length - 1;
+					return /* @__PURE__ */ jsxs("div", {
+						className: "cue-elements-fade-in cue-elements-slide-in-from-bottom-1 cue-elements-animate-in cue-elements-fill-mode-both text-fg-muted flex items-center gap-2 text-(length:--cue-text-body) duration-300",
+						children: [
+							/* @__PURE__ */ jsx(Icon, { className: "text-fg-subtle size-3.5 shrink-0" }),
+							/* @__PURE__ */ jsx(ShimmerLabel, {
+								active,
+								className: "relative inline-block leading-none",
+								children: step.verb
+							}),
+							/* @__PURE__ */ jsx("span", {
+								className: "bg-surface-2 text-fg-muted rounded-(--radius-control) px-1.5 py-0.5 font-mono text-(length:--cue-text-label)",
+								children: step.chip
+							})
+						]
+					}, step.chip);
+				}), stats.length > 0 && /* @__PURE__ */ jsx("div", {
+					className: "flex flex-wrap gap-1.5 pt-1",
+					children: stats.map((stat) => /* @__PURE__ */ jsxs("span", {
+						className: "bg-surface-2 text-fg-muted inline-flex items-center gap-1 rounded-(--radius-control) px-1.5 py-0.5 font-mono text-(length:--cue-text-label)",
+						children: [
+							/* @__PURE__ */ jsx("span", { children: stat.file }),
+							stat.added !== void 0 && /* @__PURE__ */ jsxs("span", {
+								className: "text-ok",
+								children: ["+", stat.added]
+							}),
+							stat.removed !== void 0 && /* @__PURE__ */ jsxs("span", {
+								className: "text-danger",
+								children: ["−", stat.removed]
+							})
+						]
+					}, stat.file))
+				})]
+			})
+		})]
+	});
+}
+//#endregion
+export { ToolTimeline };

package/dist/elements/trace-waterfall.d.ts

@@ -0,0 +1,37 @@
+import { ComponentProps } from "react";
+//#region src/elements/trace-waterfall.d.ts
+/** How a span ended, or that it has not: `running`, `completed`, `failed`. */
+type SpanStatus = "running" | "completed" | "failed";
+/** One bar of a trace: where it starts, how long it lasts, and how deep it nests. */
+interface TraceSpan {
+  /** Stable identity for the row key. */
+  id: string;
+  /** Span label in the left rail; truncates rather than wraps. */
+  name: string;
+  /** Nesting level. Indents the label; the bar position comes from startMs, not from this. */
+  depth: number;
+  /** Offset from the start of the trace. */
+  startMs: number;
+  /** How long the span took. A running span still needs one so its bar has width. */
+  durationMs: number;
+  /** Running pulses in blue, completed is neutral, failed is red. */
+  status: SpanStatus;
+}
+/**
+ * Every span in a run on one time axis, nested, so you can see where it actually went.
+ *
+ * @example
+ * import { TraceWaterfall } from "@cueplusplus/ui/elements";
+ *
+ * <TraceWaterfall spans={spans} totalMs={1840} visibleCount={spans.length} />
+ */
+declare function TraceWaterfall({ spans, totalMs, visibleCount, className, ...props }: Omit<ComponentProps<"div">, "children" | "spans" | "totalMs" | "visibleCount"> & {
+  /** Flat list in start order. Nesting comes from each span's depth. */
+  spans: readonly TraceSpan[];
+  /** Width of the axis. Bars are positioned against this, not against the widest span. */
+  totalMs: number;
+  /** How many spans have been reported so far. */
+  visibleCount: number;
+}): import("react").JSX.Element;
+//#endregion
+export { SpanStatus, TraceSpan, TraceWaterfall };

package/dist/elements/trace-waterfall.js

@@ -0,0 +1,69 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { mono, paper } from "./surfaces.js";
+import { pct, take } from "./range.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/elements/trace-waterfall.tsx
+const TONE = {
+	running: "bg-stream",
+	completed: "bg-surface-3",
+	failed: "bg-danger/80"
+};
+/**
+* Every span in a run on one time axis, nested, so you can see where it actually went.
+*
+* @example
+* import { TraceWaterfall } from "@cueplusplus/ui/elements";
+*
+* <TraceWaterfall spans={spans} totalMs={1840} visibleCount={spans.length} />
+*/
+function TraceWaterfall({ spans, totalMs, visibleCount, className, ...props }) {
+	const span = totalMs || 1;
+	return /* @__PURE__ */ jsxs("div", {
+		"data-slot": "trace-waterfall",
+		className: cn(paper, "flex w-full max-w-md flex-col gap-2 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: "Trace"
+			}), /* @__PURE__ */ jsxs("span", {
+				className: cn(mono, "text-fg-subtle tabular-nums"),
+				children: [totalMs, "ms"]
+			})]
+		}), /* @__PURE__ */ jsx("div", {
+			className: "flex flex-col gap-1",
+			children: take(spans, visibleCount).map((item) => {
+				const left = pct(item.startMs, span);
+				const width = Math.max(1.5, pct(item.durationMs, span));
+				return /* @__PURE__ */ jsxs("div", {
+					className: "cue-elements-fade-in cue-elements-slide-in-from-left-1 cue-elements-animate-in cue-elements-fill-mode-both grid grid-cols-[7.5rem_1fr_2.5rem] items-center gap-2 duration-300",
+					children: [
+						/* @__PURE__ */ jsx("span", {
+							className: "text-fg-muted min-w-0 truncate text-(length:--cue-text-ui)",
+							style: { paddingInlineStart: `${item.depth * .75}rem` },
+							children: item.name
+						}),
+						/* @__PURE__ */ jsx("span", {
+							className: "relative flex h-4 min-w-0 items-center",
+							children: /* @__PURE__ */ jsx("span", {
+								className: cn("absolute h-[7px] rounded-full transition-[width] duration-500 ease-out motion-reduce:transition-none", TONE[item.status], item.status === "running" && "animate-pulse"),
+								style: {
+									insetInlineStart: `${left}%`,
+									width: `${width}%`
+								}
+							})
+						}),
+						/* @__PURE__ */ jsx("span", {
+							className: cn(mono, "text-fg-subtle text-end tabular-nums"),
+							children: item.durationMs
+						})
+					]
+				}, item.id);
+			})
+		})]
+	});
+}
+//#endregion
+export { TraceWaterfall };

package/dist/elements/transcript-rules.d.ts

@@ -0,0 +1,67 @@
+import * as React from "react";
+//#region src/elements/transcript-rules.d.ts
+interface TimeBoundaryProps extends Omit<React.ComponentPropsWithoutRef<"div">, "children"> {
+  /**
+   * The label, pre-formatted: `Today`, `Yesterday`, `14 March`. This family
+   * does no date arithmetic and owns no locale — the caller knows which one the
+   * console is in, and `DaySeparator` next door takes its days the same way.
+   */
+  label: string;
+  /**
+   * The machine-readable instant, rendering the label inside a `<time>`. Worth
+   * giving: it is what lets a test, a scraper or a deep link find the boundary
+   * without parsing the words a human reads.
+   */
+  dateTime?: string;
+}
+/**
+ * The rule that says the day changed: a label centred between two hairlines.
+ *
+ * One row, placed by the caller. That is the difference between this and
+ * `DaySeparator`, which takes a whole message list and inserts its own rules:
+ * a transcript assembled from a row union — the shape every shipping agent UI
+ * converged on — needs the boundary as a *member of that union*, not as a
+ * component that owns the list around it.
+ *
+ * It is a `role="separator"` carrying its label as an accessible name, and the
+ * text inside it is `aria-hidden`. A reader hears "Today, separator" once
+ * rather than twice, and the hairlines are never announced at all.
+ *
+ * @example
+ * import { TimeBoundary } from "@cueplusplus/ui/elements";
+ *
+ * <TimeBoundary label="Today" dateTime="2026-08-22" />
+ */
+declare const TimeBoundary: React.ForwardRefExoticComponent<TimeBoundaryProps & React.RefAttributes<HTMLDivElement>>;
+interface UnreadDividerProps extends Omit<React.ComponentPropsWithoutRef<"div">, "children"> {
+  /**
+   * What the rule says. `New` by default — one word, because the row is a place
+   * marker and not an announcement, and because the sentence a reader wants is
+   * the one below the rule.
+   */
+  label?: string;
+}
+/**
+ * The rule that says "you have read down to here": an accented line with its
+ * label at the end.
+ *
+ * The second row of Cursor's union that no catalogue ships, and the one with a
+ * rule of its own that is easy to get wrong: it marks where the reader *was*,
+ * so it does not move while they read. A divider that chased the last-seen
+ * message would vanish the moment it appeared, which is why this component
+ * takes no messages, no counts and no scroll position — the caller decides
+ * where it goes and when it leaves, and the row is only ever the mark.
+ *
+ * Accented rather than neutral, and asymmetric rather than centred, so it can
+ * never be mistaken for a {@link TimeBoundary} two rows above it.
+ *
+ * @example
+ * import { UnreadDivider } from "@cueplusplus/ui/elements";
+ *
+ * <UnreadDivider />
+ * @example
+ * <UnreadDivider label="New since you left" />
+ */
+declare const UnreadDivider: React.ForwardRefExoticComponent<UnreadDividerProps & React.RefAttributes<HTMLDivElement>>;
+//#endregion
+export { TimeBoundary, TimeBoundaryProps, UnreadDivider, UnreadDividerProps };