@cueplusplus/ui 0.13.0

package/dist/elements/reviewable-diff.js

@@ -0,0 +1,110 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { codeScroll, codeSurface, inkButton, mono, paper } from "./surfaces.js";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { CheckIcon, XIcon } from "lucide-react";
+//#region src/elements/reviewable-diff.tsx
+const GUTTER = {
+	context: "",
+	added: "+",
+	removed: "−"
+};
+/**
+* The same diff, but each hunk is a decision: keep it, discard it, apply what
+* survived.
+*
+* @example
+* import { ReviewableDiff } from "@cueplusplus/ui/elements";
+*
+* <ReviewableDiff
+*   filename="composer.tsx"
+*   hunks={hunks}
+*   onKeep={(id) => decide(id, "kept")}
+*   onDiscard={(id) => decide(id, "discarded")}
+*   onApply={commit}
+* />
+*/
+function ReviewableDiff({ filename, hunks, onKeep, onDiscard, onApply, className, ...props }) {
+	const kept = hunks.filter((hunk) => hunk.decision === "kept").length;
+	const pending = hunks.filter((hunk) => hunk.decision === "pending").length;
+	return /* @__PURE__ */ jsxs("div", {
+		"data-slot": "reviewable-diff",
+		className: cn(paper, "flex w-full max-w-md flex-col overflow-hidden rounded-(--radius-overlay)", className),
+		...props,
+		children: [
+			/* @__PURE__ */ jsxs("div", {
+				className: "flex items-center justify-between px-4 pt-3 pb-2",
+				children: [/* @__PURE__ */ jsx("span", {
+					className: "font-mono text-(length:--cue-text-ui)",
+					children: filename
+				}), /* @__PURE__ */ jsxs("span", {
+					className: cn(mono, "text-fg-subtle tabular-nums"),
+					children: [
+						kept,
+						" of ",
+						hunks.length,
+						" kept"
+					]
+				})]
+			}),
+			/* @__PURE__ */ jsx("div", {
+				className: "flex flex-col",
+				children: hunks.map((hunk) => /* @__PURE__ */ jsxs("div", {
+					className: cn("border-border border-t transition-opacity duration-300", hunk.decision === "discarded" && "opacity-40"),
+					children: [/* @__PURE__ */ jsxs("div", {
+						className: "flex items-center gap-2 px-4 py-1.5",
+						children: [/* @__PURE__ */ jsx("span", {
+							className: cn(mono, "text-fg-subtle"),
+							children: hunk.range
+						}), /* @__PURE__ */ jsx("span", {
+							className: "ms-auto flex items-center gap-1",
+							children: hunk.decision === "pending" ? /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsxs("button", {
+								type: "button",
+								"aria-label": `Discard hunk ${hunk.range}`,
+								onClick: () => onDiscard?.(hunk.id),
+								className: "text-fg-muted hover:bg-surface-2 hover:text-fg flex h-6 items-center gap-1 rounded-full px-2 text-(length:--cue-text-label) font-medium transition-[background-color,color,scale] duration-150 active:scale-[0.96]",
+								children: [/* @__PURE__ */ jsx(XIcon, { className: "size-3" }), "Discard"]
+							}), /* @__PURE__ */ jsxs("button", {
+								type: "button",
+								"aria-label": `Keep hunk ${hunk.range}`,
+								onClick: () => onKeep?.(hunk.id),
+								className: "flex h-6 items-center gap-1 rounded-full bg-ok/12 px-2 text-(length:--cue-text-label) font-medium text-ok transition-[background-color,scale] duration-150 hover:bg-ok/20 active:scale-[0.96]",
+								children: [/* @__PURE__ */ jsx(CheckIcon, { className: "size-3" }), "Keep"]
+							})] }) : /* @__PURE__ */ jsx("span", {
+								className: cn(mono, "cue-elements-fade-in cue-elements-animate-in duration-300", hunk.decision === "kept" ? "text-ok" : "text-fg-subtle"),
+								children: hunk.decision
+							})
+						})]
+					}), /* @__PURE__ */ jsx("div", {
+						className: cn(codeScroll, "pb-1.5 font-mono text-(length:--cue-text-ui)"),
+						children: /* @__PURE__ */ jsx("div", {
+							className: codeSurface,
+							children: hunk.lines.map((line, i) => /* @__PURE__ */ jsxs("div", {
+								className: cn("flex px-4 py-0.5 leading-(--cue-leading-ui) whitespace-pre", line.kind === "context" && "text-fg-subtle", line.kind === "added" && "bg-ok/10 text-ok", line.kind === "removed" && "bg-danger/10 text-danger"),
+								children: [/* @__PURE__ */ jsx("span", {
+									className: "w-4 shrink-0 select-none",
+									children: GUTTER[line.kind]
+								}), /* @__PURE__ */ jsx("span", { children: line.text })]
+							}, `${hunk.id}-${i}`))
+						})
+					})]
+				}, hunk.id))
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				className: "border-border flex items-center justify-between border-t px-4 py-2.5",
+				children: [/* @__PURE__ */ jsx("span", {
+					className: cn(mono, "text-fg-subtle"),
+					children: pending > 0 ? `${pending} left to review` : "All reviewed"
+				}), /* @__PURE__ */ jsxs("button", {
+					type: "button",
+					disabled: pending > 0,
+					onClick: onApply,
+					className: cn(inkButton, "flex h-7 items-center rounded-full px-3 text-(length:--cue-text-ui) font-medium disabled:pointer-events-none disabled:opacity-30"),
+					children: ["Apply ", kept]
+				})]
+			})
+		]
+	});
+}
+//#endregion
+export { ReviewableDiff };

package/dist/elements/risk-badge.d.ts

@@ -0,0 +1,52 @@
+import { SecurityRisk } from "./vocabulary.js";
+import * as React from "react";
+//#region src/elements/risk-badge.d.ts
+interface RiskBadgeProps extends Omit<React.ComponentPropsWithoutRef<"span">, "children"> {
+  /**
+   * What the runtime says this call could do: `unknown`, `low`, `medium` or
+   * `high`. Stamped as `data-risk`, and as `data-color` for the tone, so a
+   * console can restyle the row from the attribute rather than from a prop.
+   */
+  risk: SecurityRisk;
+  /**
+   * What it is called. Defaults to `RISK_LABELS[risk]` — `High risk`, not
+   * `HIGH`, because the badge sits inline beside a duration and a diff stat and
+   * a bare adjective there is a number about something.
+   */
+  label?: string;
+  /**
+   * Why, in the words the products that guess at risk already use: `outside
+   * your workspace`, `protected file`, `arbitrary network access`. Drawn beside
+   * the label, truncating before the label does.
+   */
+  reason?: string;
+}
+/**
+ * How dangerous this call is, said out loud instead of implied.
+ *
+ * One of the two elements the field study found nobody shipping. Every agent UI
+ * knows which of its tools are frightening — that is what the approval buckets
+ * are — but the knowledge lives in the taxonomy rather than on the row, so a
+ * `curl` to an arbitrary host and a `cat` of a local file look alike until you
+ * read them. A runtime that scores its own actions can put the score on the
+ * row, and one element renders it for every tool that will ever exist.
+ *
+ * `unknown` is a first-class value and it is the default answer for a runtime
+ * with no scorer. The alternative — omitting the badge, or falling back to
+ * `low` — is how a UI ends up implying that unscored means safe.
+ *
+ * Colour is never alone: each risk has its own glyph and its own words, so the
+ * badge survives a colour-blind reader, a monochrome screenshot and a theme
+ * whose danger hue is somebody's brand red.
+ *
+ * @example
+ * import { RiskBadge } from "@cueplusplus/ui/elements";
+ *
+ * <RiskBadge risk="high" reason="arbitrary network access" />
+ * @example
+ * // The honest answer from a runtime that does not score its actions.
+ * <RiskBadge risk="unknown" />
+ */
+declare const RiskBadge: React.ForwardRefExoticComponent<RiskBadgeProps & React.RefAttributes<HTMLSpanElement>>;
+//#endregion
+export { RiskBadge, RiskBadgeProps };

package/dist/elements/risk-badge.js

@@ -0,0 +1,91 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { RISK_LABELS } from "./vocabulary.js";
+import * as React from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { CircleHelpIcon, OctagonAlertIcon, ShieldAlertIcon, ShieldCheckIcon } from "lucide-react";
+//#region src/elements/risk-badge.tsx
+/**
+* What each risk paints, and the glyph that carries it without colour.
+*
+* Four rows rather than three: `unknown` is a real answer, and it is drawn in
+* the family's neutral rather than in the low-risk green, because a runtime
+* that does not score its actions must not be made to look like one that scored
+* them all safe.
+*
+* The paint is written in the alpha form the whole group uses — `bg-danger/10`,
+* not `bg-danger-soft` — so it composites at the point of use and follows an
+* `AgentSurface` island. The derived `*-soft` tokens cannot.
+*/
+const RISK_PAINT = {
+	unknown: {
+		tone: "border-border bg-fg/[0.06] text-fg-subtle",
+		glyph: CircleHelpIcon
+	},
+	low: {
+		tone: "border-ok/30 bg-ok/10 text-ok",
+		glyph: ShieldCheckIcon
+	},
+	medium: {
+		tone: "border-warn/30 bg-warn/10 text-warn",
+		glyph: ShieldAlertIcon
+	},
+	high: {
+		tone: "border-danger/40 bg-danger/15 text-danger",
+		glyph: OctagonAlertIcon
+	}
+};
+/**
+* How dangerous this call is, said out loud instead of implied.
+*
+* One of the two elements the field study found nobody shipping. Every agent UI
+* knows which of its tools are frightening — that is what the approval buckets
+* are — but the knowledge lives in the taxonomy rather than on the row, so a
+* `curl` to an arbitrary host and a `cat` of a local file look alike until you
+* read them. A runtime that scores its own actions can put the score on the
+* row, and one element renders it for every tool that will ever exist.
+*
+* `unknown` is a first-class value and it is the default answer for a runtime
+* with no scorer. The alternative — omitting the badge, or falling back to
+* `low` — is how a UI ends up implying that unscored means safe.
+*
+* Colour is never alone: each risk has its own glyph and its own words, so the
+* badge survives a colour-blind reader, a monochrome screenshot and a theme
+* whose danger hue is somebody's brand red.
+*
+* @example
+* import { RiskBadge } from "@cueplusplus/ui/elements";
+*
+* <RiskBadge risk="high" reason="arbitrary network access" />
+* @example
+* // The honest answer from a runtime that does not score its actions.
+* <RiskBadge risk="unknown" />
+*/
+const RiskBadge = React.forwardRef(function RiskBadge({ risk, label, reason, className, ...elementProps }, ref) {
+	const { tone, glyph: Glyph } = RISK_PAINT[risk];
+	return /* @__PURE__ */ jsxs("span", {
+		ref,
+		"data-slot": "risk-badge",
+		"data-risk": risk,
+		"data-color": risk,
+		className: cn("inline-flex min-w-0 shrink items-center gap-1.5 rounded-full border px-2 py-0.5 text-(length:--cue-text-ui)", tone, className),
+		...elementProps,
+		children: [
+			/* @__PURE__ */ jsx(Glyph, {
+				"aria-hidden": true,
+				className: "size-3.5 shrink-0"
+			}),
+			/* @__PURE__ */ jsx("span", {
+				className: "shrink-0 font-medium",
+				children: label ?? RISK_LABELS[risk]
+			}),
+			reason === void 0 ? null : /* @__PURE__ */ jsxs("span", {
+				"data-slot": "risk-badge-reason",
+				className: "min-w-0 truncate opacity-80",
+				children: ["· ", reason]
+			})
+		]
+	});
+});
+//#endregion
+export { RiskBadge };

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

@@ -0,0 +1,42 @@
+import { ComponentProps } from "react";
+//#region src/elements/schedule-card.d.ts
+/** One past run of a schedule: when it went, and whether it worked. */
+interface ScheduleRun {
+  /** Identifies the run, and keys its row. */
+  id: string;
+  /** When it ran, already phrased — `Today 09:00`, `2h ago`. This element parses no dates. */
+  at: string;
+  /** Whether it succeeded, which decides the row's glyph and the word that ends it. */
+  ok: boolean;
+}
+/**
+ * A run that repeats on its own, with its cadence and how it has been doing.
+ *
+ * @example
+ * import { ScheduleCard } from "@cueplusplus/ui/elements";
+ *
+ * <ScheduleCard
+ *   name="Triage the issue queue"
+ *   cadence="every day at 06:00"
+ *   nextRun="Tomorrow, 06:00"
+ *   enabled
+ *   history={history}
+ *   onToggle={toggle}
+ * />
+ */
+declare function ScheduleCard({ name, cadence, nextRun, enabled, history, onToggle, className, ...props }: Omit<ComponentProps<"div">, "children" | "name" | "cadence" | "nextRun" | "enabled" | "history" | "onToggle"> & {
+  /** What the scheduled run does. */
+  name: string;
+  /** Human-readable recurrence, not a cron string. */
+  cadence: string;
+  /** When it fires next. Replaced by paused when disabled. */
+  nextRun: string;
+  /** Whether the schedule is live. */
+  enabled: boolean;
+  /** Recent runs, so a silently failing schedule is visible. */
+  history: readonly ScheduleRun[];
+  /** Called when the schedule is paused or resumed. */
+  onToggle?: () => void;
+}): import("react").JSX.Element;
+//#endregion
+export { ScheduleCard, ScheduleRun };

package/dist/elements/schedule-card.js

@@ -0,0 +1,90 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { field, mono, paper } from "./surfaces.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { CheckIcon, ClockIcon, XIcon } from "lucide-react";
+//#region src/elements/schedule-card.tsx
+/**
+* A run that repeats on its own, with its cadence and how it has been doing.
+*
+* @example
+* import { ScheduleCard } from "@cueplusplus/ui/elements";
+*
+* <ScheduleCard
+*   name="Triage the issue queue"
+*   cadence="every day at 06:00"
+*   nextRun="Tomorrow, 06:00"
+*   enabled
+*   history={history}
+*   onToggle={toggle}
+* />
+*/
+function ScheduleCard({ name, cadence, nextRun, enabled, history, onToggle, className, ...props }) {
+	return /* @__PURE__ */ jsxs("div", {
+		"data-slot": "schedule-card",
+		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-center gap-2.5",
+				children: [
+					/* @__PURE__ */ jsx("span", {
+						className: "bg-surface-1 text-fg-muted flex size-7 shrink-0 items-center justify-center rounded-(--radius-surface)",
+						children: /* @__PURE__ */ jsx(ClockIcon, { className: "size-3.5" })
+					}),
+					/* @__PURE__ */ jsxs("div", {
+						className: "flex min-w-0 flex-1 flex-col",
+						children: [/* @__PURE__ */ jsx("span", {
+							className: "truncate text-(length:--cue-text-body) font-medium",
+							children: name
+						}), /* @__PURE__ */ jsx("span", {
+							className: cn(mono, "text-fg-subtle"),
+							children: cadence
+						})]
+					}),
+					/* @__PURE__ */ jsx("button", {
+						type: "button",
+						role: "switch",
+						"aria-checked": enabled,
+						"aria-label": `${enabled ? "Pause" : "Resume"} ${name}`,
+						onClick: onToggle,
+						className: cn("flex h-5 w-9 shrink-0 items-center rounded-full p-0.5 transition-colors duration-200", enabled ? "bg-accent" : "bg-surface-3"),
+						children: /* @__PURE__ */ jsx("span", { className: cn("bg-bg size-4 rounded-full transition-transform duration-200 motion-reduce:transition-none", enabled && "translate-x-4") })
+					})
+				]
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				className: cn(field, "flex items-baseline gap-2 rounded-(--radius-surface) px-3 py-2", !enabled && "opacity-45"),
+				children: [/* @__PURE__ */ jsx("span", {
+					className: cn(mono, "text-fg-subtle"),
+					children: "next"
+				}), /* @__PURE__ */ jsx("span", {
+					className: "text-fg-muted text-(length:--cue-text-body)",
+					children: enabled ? nextRun : "paused"
+				})]
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				className: "flex flex-col gap-1",
+				children: [/* @__PURE__ */ jsx("span", {
+					className: cn(mono, "text-fg-subtle"),
+					children: "recent runs"
+				}), history.map((run) => /* @__PURE__ */ jsxs("div", {
+					className: "flex items-baseline gap-2",
+					children: [
+						run.ok ? /* @__PURE__ */ jsx(CheckIcon, { className: "size-3 shrink-0 translate-y-0.5 text-ok" }) : /* @__PURE__ */ jsx(XIcon, { className: "size-3 shrink-0 translate-y-0.5 text-danger" }),
+						/* @__PURE__ */ jsx("span", {
+							className: "text-fg-muted min-w-0 flex-1 truncate text-(length:--cue-text-ui)",
+							children: run.at
+						}),
+						/* @__PURE__ */ jsx("span", {
+							className: cn(mono, "text-fg-subtle shrink-0"),
+							children: run.ok ? "ok" : "failed"
+						})
+					]
+				}, run.id))]
+			})
+		]
+	});
+}
+//#endregion
+export { ScheduleCard };

package/dist/elements/score-breakdown.d.ts

@@ -0,0 +1,47 @@
+import { ComponentProps } from "react";
+//#region src/elements/score-breakdown.d.ts
+/**
+ * One line of the arithmetic behind a verdict: what was judged, how well, and how much
+ * it counted.
+ */
+interface ScoreCriterion {
+  /** What is being scored. Truncates rather than wraps. */
+  label: string;
+  /**
+   * Score for this criterion, on the same scale as outOf. Its bar is drawn against
+   * outOf, so the two cannot drift apart.
+   */
+  score: number;
+  /** How much it counted toward the total. */
+  weight: number;
+  /** Why it scored that way. Worth writing for anything below full marks. */
+  note?: string;
+}
+/**
+ * A verdict with its arithmetic shown: criteria, weights, and what pulled it down.
+ *
+ * @example
+ * import { ScoreBreakdown } from "@cueplusplus/ui/elements";
+ *
+ * <ScoreBreakdown
+ *   verdict="approve"
+ *   total={4.2}
+ *   outOf={5}
+ *   criteria={criteria}
+ *   visibleCount={3}
+ * />
+ */
+declare function ScoreBreakdown({ verdict, total, outOf, criteria, visibleCount, className, ...props }: Omit<ComponentProps<"div">, "children" | "verdict" | "total" | "outOf" | "criteria" | "visibleCount"> & {
+  /** The decision in a word. Its tint follows total over outOf. */
+  verdict: string;
+  /** The composite score. */
+  total: number;
+  /** Maximum possible, for the headline and for every criterion bar. */
+  outOf: number;
+  /** What produced the number, so the verdict can be argued with. */
+  criteria: readonly ScoreCriterion[];
+  /** How many criteria have been scored. */
+  visibleCount: number;
+}): import("react").JSX.Element;
+//#endregion
+export { ScoreBreakdown, ScoreCriterion };

package/dist/elements/score-breakdown.js

@@ -0,0 +1,82 @@
+"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/score-breakdown.tsx
+/**
+* A verdict with its arithmetic shown: criteria, weights, and what pulled it down.
+*
+* @example
+* import { ScoreBreakdown } from "@cueplusplus/ui/elements";
+*
+* <ScoreBreakdown
+*   verdict="approve"
+*   total={4.2}
+*   outOf={5}
+*   criteria={criteria}
+*   visibleCount={3}
+* />
+*/
+function ScoreBreakdown({ verdict, total, outOf, criteria, visibleCount, className, ...props }) {
+	const ratio = outOf === 0 ? 0 : total / outOf;
+	return /* @__PURE__ */ jsxs("div", {
+		"data-slot": "score-breakdown",
+		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 gap-2",
+			children: [
+				/* @__PURE__ */ jsx("span", {
+					className: "text-(length:--cue-text-title) font-medium tracking-tight tabular-nums",
+					children: total.toFixed(1)
+				}),
+				/* @__PURE__ */ jsxs("span", {
+					className: cn(mono, "text-fg-subtle tabular-nums"),
+					children: ["/ ", outOf]
+				}),
+				/* @__PURE__ */ jsx("span", {
+					className: cn("ms-auto rounded-full px-2 py-0.5 text-(length:--cue-text-ui) font-medium", ratio >= .75 ? "bg-ok/12 text-ok" : ratio >= .5 ? "bg-warn/12 text-warn" : "bg-danger/12 text-danger"),
+					children: verdict
+				})
+			]
+		}), /* @__PURE__ */ jsx("div", {
+			className: "flex flex-col gap-2",
+			children: take(criteria, visibleCount).map((criterion) => /* @__PURE__ */ jsxs("div", {
+				className: "cue-elements-fade-in cue-elements-slide-in-from-bottom-1 cue-elements-animate-in cue-elements-fill-mode-both flex flex-col gap-1 duration-300",
+				children: [
+					/* @__PURE__ */ jsxs("div", {
+						className: "flex items-baseline gap-2",
+						children: [
+							/* @__PURE__ */ jsx("span", {
+								className: "text-fg-muted min-w-0 flex-1 truncate text-(length:--cue-text-body)",
+								children: criterion.label
+							}),
+							/* @__PURE__ */ jsxs("span", {
+								className: cn(mono, "text-fg-subtle shrink-0"),
+								children: ["×", criterion.weight]
+							}),
+							/* @__PURE__ */ jsx("span", {
+								className: cn(mono, "text-fg-muted shrink-0 tabular-nums"),
+								children: criterion.score.toFixed(1)
+							})
+						]
+					}),
+					/* @__PURE__ */ jsx("span", {
+						className: "bg-surface-2 h-[3px] w-full overflow-hidden rounded-full",
+						children: /* @__PURE__ */ jsx("span", {
+							className: "block h-full rounded-full bg-stream transition-[width] duration-500 motion-reduce:transition-none",
+							style: { width: `${pct(criterion.score, outOf)}%` }
+						})
+					}),
+					criterion.note && /* @__PURE__ */ jsx("span", {
+						className: "text-fg-subtle text-(length:--cue-text-ui) leading-(--cue-leading-ui) break-words",
+						children: criterion.note
+					})
+				]
+			}, criterion.label))
+		})]
+	});
+}
+//#endregion
+export { ScoreBreakdown };

package/dist/elements/scroll-anchor.d.ts

@@ -0,0 +1,32 @@
+import { ComponentProps } from "react";
+//#region src/elements/scroll-anchor.d.ts
+/** One turn in the transcript this element scrolls: who said it, and what. */
+interface ScrollAnchorMessage {
+  /** Who is speaking. The user's turns take the recessed field ground and sit right. */
+  role: "user" | "assistant";
+  /** The turn itself, as plain text. */
+  text: string;
+}
+/**
+ * Streaming never steals your scroll position; a pill offers the way back down.
+ *
+ * @example
+ * import { ScrollAnchor } from "@cueplusplus/ui/elements";
+ *
+ * <ScrollAnchor
+ *   messages={[
+ *     { role: "user", text: "Keep scrolling pinned?" },
+ *     { role: "assistant", text: "Only when you are already at the bottom." },
+ *   ]}
+ * />
+ */
+declare function ScrollAnchor({ messages, paused, onSettled, className, ...props }: Omit<ComponentProps<"div">, "children" | "messages" | "paused" | "onSettled"> & {
+  /** Conversation messages appended over time inside the scroll viewport. */
+  messages: ScrollAnchorMessage[];
+  /** Freezes the scene where it is; replay happens by remounting. */
+  paused?: boolean;
+  /** Called once every message has landed and the viewport is pinned. */
+  onSettled?: () => void;
+}): import("react").JSX.Element;
+//#endregion
+export { ScrollAnchor, ScrollAnchorMessage };

package/dist/elements/scroll-anchor.js

@@ -0,0 +1,123 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { usePrefersReducedMotion } from "../instruments/_motion.js";
+import { field, paper } from "./surfaces.js";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { ArrowDownIcon } from "lucide-react";
+//#region src/elements/scroll-anchor.tsx
+const INITIAL_COUNT = 3;
+const APPEND_MS = 1300;
+/**
+* Streaming never steals your scroll position; a pill offers the way back down.
+*
+* @example
+* import { ScrollAnchor } from "@cueplusplus/ui/elements";
+*
+* <ScrollAnchor
+*   messages={[
+*     { role: "user", text: "Keep scrolling pinned?" },
+*     { role: "assistant", text: "Only when you are already at the bottom." },
+*   ]}
+* />
+*/
+function ScrollAnchor({ messages, paused = false, onSettled, className, ...props }) {
+	const reduced = usePrefersReducedMotion();
+	const viewportRef = useRef(null);
+	const [count, setCount] = useState(INITIAL_COUNT);
+	const [pinned, setPinned] = useState(true);
+	const [seenCount, setSeenCount] = useState(INITIAL_COUNT);
+	const settled = count >= messages.length;
+	useEffect(() => {
+		if (paused || settled) return;
+		if (reduced) {
+			setCount(messages.length);
+			return;
+		}
+		const id = setInterval(() => {
+			setCount((current) => {
+				if (current >= messages.length) return current;
+				return current + 1;
+			});
+		}, APPEND_MS);
+		return () => clearInterval(id);
+	}, [
+		messages.length,
+		reduced,
+		paused,
+		settled
+	]);
+	useEffect(() => {
+		if (count >= messages.length && pinned) onSettled?.();
+	}, [
+		count,
+		pinned,
+		messages.length,
+		onSettled
+	]);
+	useEffect(() => {
+		if (count === 4) {
+			setPinned(false);
+			const viewport = viewportRef.current;
+			if (viewport) viewport.scrollTo({ top: 0 });
+		}
+	}, [count]);
+	useEffect(() => {
+		const viewport = viewportRef.current;
+		if (!viewport) return;
+		if (pinned) {
+			viewport.scrollTo({ top: viewport.scrollHeight });
+			setSeenCount(count);
+		}
+	}, [count, pinned]);
+	const jump = useCallback(() => {
+		const viewport = viewportRef.current;
+		if (viewport) viewport.scrollTo({ top: viewport.scrollHeight });
+		setPinned(true);
+		setSeenCount(count);
+	}, [count]);
+	useEffect(() => {
+		if (paused || pinned || count - seenCount < 2) return;
+		const id = setTimeout(jump, 2400);
+		return () => clearTimeout(id);
+	}, [
+		paused,
+		pinned,
+		count,
+		seenCount,
+		jump
+	]);
+	const newCount = count - seenCount;
+	return /* @__PURE__ */ jsxs("div", {
+		"data-slot": "scroll-anchor",
+		className: cn(paper, "relative h-64 w-full max-w-sm overflow-hidden rounded-(--radius-overlay)", className),
+		...props,
+		children: [
+			/* @__PURE__ */ jsx("div", {
+				ref: viewportRef,
+				className: "flex h-full flex-col gap-2.5 overflow-y-hidden scroll-smooth motion-reduce:scroll-auto p-4",
+				children: messages.slice(0, count).map((message, i) => /* @__PURE__ */ jsx("div", {
+					className: cn("cue-elements-fade-in cue-elements-slide-in-from-bottom-1 cue-elements-animate-in max-w-[85%] text-(length:--cue-text-ui) leading-(--cue-leading-ui) duration-300 motion-reduce:animate-none", message.role === "user" ? cn(field, "self-end rounded-(--radius-overlay) px-3 py-1.5") : "text-fg-muted self-start"),
+					children: message.text
+				}, i))
+			}),
+			/* @__PURE__ */ jsx("div", {
+				"aria-hidden": true,
+				className: "from-surface-1 pointer-events-none absolute inset-x-0 top-0 h-6 bg-gradient-to-b to-transparent"
+			}),
+			!pinned && newCount > 0 && /* @__PURE__ */ jsxs("button", {
+				type: "button",
+				onClick: jump,
+				className: cn("bg-surface-2 border border-border-overlay", "cue-elements-fade-in cue-elements-slide-in-from-bottom-2 cue-elements-animate-in absolute inset-x-0 bottom-3 mx-auto flex w-fit items-center gap-1.5 rounded-full px-3.5 py-1.5 text-(length:--cue-text-ui) transition-transform duration-200 hover:-translate-y-px"),
+				children: [
+					/* @__PURE__ */ jsx(ArrowDownIcon, { className: "size-3 opacity-60" }),
+					newCount,
+					" new ",
+					newCount === 1 ? "message" : "messages"
+				]
+			})
+		]
+	});
+}
+//#endregion
+export { ScrollAnchor };