@cueplusplus/ui 0.3.0 → 0.5.0

package/dist/elements/index.js

@@ -0,0 +1,115 @@
+import { ShimmerLabel, SwapLabel, codeScroll, codeSurface, collapsePanel, field, fieldInteractive, floating, ghostButton, iconSwap, iconSwapIn, iconSwapOut, inkButton, labelSwap, labelSwapIn, labelSwapOut, live, mono, paper, pressable } from "./surfaces.js";
+import { ActivityGraph } from "./activity-graph.js";
+import { AgentCard } from "./agent-card.js";
+import { AgentHandoff } from "./agent-handoff.js";
+import { AGENT_MODES, AGENT_MODE_DESCRIPTIONS, AGENT_MODE_LABELS, ANNOUNCEMENTS, CLAMP_LABELS, COMPACTION_LABELS, COMPACTION_STATES, CONTEXT_CATEGORY_LABELS, CONTEXT_LABELS, CONTEXT_STAT_LABELS, PERMISSION_LABELS, PERMISSION_SCOPE_LABELS, QUEUE_LABELS, REVERT_LABELS, REVERT_SCOPES, REVERT_SCOPE_DESCRIPTIONS, REVERT_SCOPE_LABELS, RISK_LABELS, SECURITY_RISKS, TAIL_ACTIONS, TURN_ACTION_LABELS, VERB_TRIADS, VERDICT_LABELS, verbFor } from "./vocabulary.js";
+import { AgentModeBadge } from "./agent-mode-badge.js";
+import { at, clamp, indexIn, pct, progressOf, take } from "./range.js";
+import { AgentPlan } from "./agent-plan.js";
+import { AgentStatus } from "./agent-status.js";
+import { AgentSurface } from "./agent-surface.js";
+import { AnimatedNumber, formatCompactNumber } from "./animated-number.js";
+import { ApprovalCard } from "./approval-card.js";
+import { ArtifactCard } from "./artifact-card.js";
+import { BackgroundInbox } from "./background-inbox.js";
+import { CanvasSplit, CanvasSplitBody, CanvasSplitDocument, CanvasSplitHeader, CanvasSplitLine, CanvasSplitMessage, CanvasSplitThread } from "./canvas-split.js";
+import { Chart } from "./chart.js";
+import { ChatPanel, ChatPanelAssistantMessage, ChatPanelComposer, ChatPanelMessages, ChatPanelTyping, ChatPanelUserMessage } from "./chat-panel.js";
+import { CheckpointHistory } from "./checkpoint-history.js";
+import { Clamp } from "./clamp.js";
+import { CodeDiff } from "./code-diff.js";
+import { CodeRunner } from "./code-runner.js";
+import { ElementsCommandPalette } from "./command-palette.js";
+import { CompactionRow } from "./compaction-row.js";
+import { ComparisonCard } from "./comparison-card.js";
+import { ComposerActions, ComposerAttachButton, ComposerAttachmentChip, ComposerAttachments, ComposerBar, ComposerCommandItem, ComposerContext, ComposerInput, ComposerMenu, ComposerMenuItem, ComposerModelItem, ComposerModelTrigger, ComposerPersonItem, ComposerSend, ComposerToolbar, ComposerVoice, ComposerVoiceButton, ElementsComposer, applyMention, useMentionMatches, useSlashMatches } from "./composer.js";
+import { ComputerUse } from "./computer-use.js";
+import { ConfidenceMarker } from "./confidence-marker.js";
+import { ConnectionState } from "./connection-state.js";
+import { ContextBreakdown } from "./context-breakdown.js";
+import { ContextUsage } from "./context-usage.js";
+import { ConversationSearch } from "./conversation-search.js";
+import { CostMeter } from "./cost-meter.js";
+import { ElementsDataTable } from "./data-table.js";
+import { DaySeparator } from "./day-separator.js";
+import { Diagram } from "./diagram.js";
+import { DocumentReference } from "./document-reference.js";
+import { DraftRestore } from "./draft-restore.js";
+import { EditMessage } from "./edit-message.js";
+import { ElicitationForm } from "./elicitation-form.js";
+import { ChatEmptyState, EmptyStateComposer, EmptyStateGreeting, EmptyStateSuggestion, EmptyStateSuggestions } from "./empty-state.js";
+import { EndOfTurnSummary, formatChangeSummary } from "./end-of-turn-summary.js";
+import { ErrorState } from "./error-state.js";
+import { FeedbackDialog } from "./feedback-dialog.js";
+import { FileTree } from "./file-tree.js";
+import { FlowGraph } from "./flow-graph.js";
+import { GuardrailNotice } from "./guardrail-notice.js";
+import { ImageGeneration } from "./image-generation.js";
+import { InlineCitation } from "./inline-citation.js";
+import { JobProgress } from "./job-progress.js";
+import { LauncherBubble } from "./launcher-bubble.js";
+import { LiveRegionAnnouncer, useAnnouncerPresent } from "./live-region-announcer.js";
+import { GenerationLoader } from "./loading-state.js";
+import { MapAnswer } from "./map-answer.js";
+import { Frac, MathBlock, Sub, Sup } from "./math-block.js";
+import { McpServerPanel } from "./mcp-server-panel.js";
+import { MemoryChips } from "./memory-chips.js";
+import { MessageActions } from "./message-actions.js";
+import { MessageAttachments } from "./message-attachment.js";
+import { MessageBranches } from "./message-branches.js";
+import { MessagePair } from "./message-pair.js";
+import { MessageQueue } from "./message-queue.js";
+import { MessageTiming } from "./message-timing.js";
+import { MobileComposer } from "./mobile-composer.js";
+import { ModelPicker } from "./model-picker.js";
+import { NumberTicker } from "./number-ticker.js";
+import { Onboarding } from "./onboarding.js";
+import { PermissionGrant } from "./permission-grant.js";
+import { PermissionScopes, formatAlwaysAllow } from "./permission-scopes.js";
+import { PromptLibrary } from "./prompt-library.js";
+import { QueueDock, formatQueueSummary } from "./queue-dock.js";
+import { QuotaBanner } from "./quota-banner.js";
+import { QuoteReply } from "./quote-reply.js";
+import { ReadAloud } from "./read-aloud.js";
+import { ReasoningEffort } from "./reasoning-effort.js";
+import { ReasoningPanel } from "./reasoning-panel.js";
+import { RecommendationCard } from "./recommendation-card.js";
+import { RegenerateMenu } from "./regenerate-menu.js";
+import { ResearchReport } from "./research-report.js";
+import { RetrievalChunks } from "./retrieval-chunks.js";
+import { RevertDock, formatRevertSummary } from "./revert-dock.js";
+import { ReviewableDiff } from "./reviewable-diff.js";
+import { RiskBadge } from "./risk-badge.js";
+import { ScheduleCard } from "./schedule-card.js";
+import { ScoreBreakdown } from "./score-breakdown.js";
+import { ScrollAnchor } from "./scroll-anchor.js";
+import { SettingsPanel } from "./settings-panel.js";
+import { SharedConversation } from "./shared-conversation.js";
+import { Sources } from "./sources.js";
+import { SpeakerIdentity } from "./speaker-identity.js";
+import { SpecSheet } from "./spec-sheet.js";
+import { StoppedRun } from "./stopped-run.js";
+import { StreamingText } from "./streaming-text.js";
+import { SubagentList } from "./subagent-list.js";
+import { Suggestions } from "./suggestions.js";
+import { TailStatus } from "./tail-status.js";
+import { TerminalBlock } from "./terminal-block.js";
+import { ThinkingIndicator } from "./thinking-indicator.js";
+import { ThreadList } from "./thread-list.js";
+import { ThreadSearch } from "./thread-search.js";
+import { ElementsTimeline } from "./timeline.js";
+import { TodoList } from "./todo-list.js";
+import { ToolCall } from "./tool-call.js";
+import { ToolError } from "./tool-error.js";
+import { ToolGroup } from "./tool-group.js";
+import { ToolTimeline } from "./tool-timeline.js";
+import { TraceWaterfall } from "./trace-waterfall.js";
+import { TimeBoundary, UnreadDivider } from "./transcript-rules.js";
+import { TurnFooter } from "./turn-footer.js";
+import { TypingIndicator } from "./typing-indicator.js";
+import { VerdictRow, verdictStars } from "./verdict-row.js";
+import { VoiceConversation } from "./voice-conversation.js";
+import { WebPreview } from "./web-preview.js";
+import { WebSearch } from "./web-search.js";
+import { WorkCollapse, formatWorkDuration, formatWorkLabel } from "./work-collapse.js";
+export { AGENT_MODES, AGENT_MODE_DESCRIPTIONS, AGENT_MODE_LABELS, ANNOUNCEMENTS, ActivityGraph, AgentCard, AgentHandoff, AgentModeBadge, AgentPlan, AgentStatus, AgentSurface, AnimatedNumber, ApprovalCard, ArtifactCard, BackgroundInbox, CLAMP_LABELS, COMPACTION_LABELS, COMPACTION_STATES, CONTEXT_CATEGORY_LABELS, CONTEXT_LABELS, CONTEXT_STAT_LABELS, CanvasSplit, CanvasSplitBody, CanvasSplitDocument, CanvasSplitHeader, CanvasSplitLine, CanvasSplitMessage, CanvasSplitThread, Chart, ChatEmptyState, ChatPanel, ChatPanelAssistantMessage, ChatPanelComposer, ChatPanelMessages, ChatPanelTyping, ChatPanelUserMessage, CheckpointHistory, Clamp, CodeDiff, CodeRunner, CompactionRow, ComparisonCard, ComposerActions, ComposerAttachButton, ComposerAttachmentChip, ComposerAttachments, ComposerBar, ComposerCommandItem, ComposerContext, ComposerInput, ComposerMenu, ComposerMenuItem, ComposerModelItem, ComposerModelTrigger, ComposerPersonItem, ComposerSend, ComposerToolbar, ComposerVoice, ComposerVoiceButton, ComputerUse, ConfidenceMarker, ConnectionState, ContextBreakdown, ContextUsage, ConversationSearch, CostMeter, DaySeparator, Diagram, DocumentReference, DraftRestore, EditMessage, ElementsCommandPalette, ElementsComposer, ElementsDataTable, ElementsTimeline, ElicitationForm, EmptyStateComposer, EmptyStateGreeting, EmptyStateSuggestion, EmptyStateSuggestions, EndOfTurnSummary, ErrorState, FeedbackDialog, FileTree, FlowGraph, Frac, GenerationLoader, GuardrailNotice, ImageGeneration, InlineCitation, JobProgress, LauncherBubble, LiveRegionAnnouncer, MapAnswer, MathBlock, McpServerPanel, MemoryChips, MessageActions, MessageAttachments, MessageBranches, MessagePair, MessageQueue, MessageTiming, MobileComposer, ModelPicker, NumberTicker, Onboarding, PERMISSION_LABELS, PERMISSION_SCOPE_LABELS, PermissionGrant, PermissionScopes, PromptLibrary, QUEUE_LABELS, QueueDock, QuotaBanner, QuoteReply, REVERT_LABELS, REVERT_SCOPES, REVERT_SCOPE_DESCRIPTIONS, REVERT_SCOPE_LABELS, RISK_LABELS, ReadAloud, ReasoningEffort, ReasoningPanel, RecommendationCard, RegenerateMenu, ResearchReport, RetrievalChunks, RevertDock, ReviewableDiff, RiskBadge, SECURITY_RISKS, ScheduleCard, ScoreBreakdown, ScrollAnchor, SettingsPanel, SharedConversation, ShimmerLabel, Sources, SpeakerIdentity, SpecSheet, StoppedRun, StreamingText, Sub, SubagentList, Suggestions, Sup, SwapLabel, TAIL_ACTIONS, TURN_ACTION_LABELS, TailStatus, TerminalBlock, ThinkingIndicator, ThreadList, ThreadSearch, TimeBoundary, TodoList, ToolCall, ToolError, ToolGroup, ToolTimeline, TraceWaterfall, TurnFooter, TypingIndicator, UnreadDivider, VERB_TRIADS, VERDICT_LABELS, VerdictRow, VoiceConversation, WebPreview, WebSearch, WorkCollapse, applyMention, at, clamp, codeScroll, codeSurface, collapsePanel, field, fieldInteractive, floating, formatAlwaysAllow, formatChangeSummary, formatCompactNumber, formatQueueSummary, formatRevertSummary, formatWorkDuration, formatWorkLabel, ghostButton, iconSwap, iconSwapIn, iconSwapOut, indexIn, inkButton, labelSwap, labelSwapIn, labelSwapOut, live, mono, paper, pct, pressable, progressOf, take, useAnnouncerPresent, useMentionMatches, useSlashMatches, verbFor, verdictStars };

package/dist/elements/inline-citation.d.ts

@@ -0,0 +1,43 @@
+import { ComponentProps } from "react";
+//#region src/elements/inline-citation.d.ts
+/**
+ * A source behind one marker in a sentence, with the passage its hover card shows.
+ * Named apart from `sources.tsx`'s `Source` because the family cannot publish two.
+ */
+interface CitationSource {
+  /** The site, as a bare host. Its first letter is the preview card's monogram. */
+  domain: string;
+  /** The page's own title, set as the preview card's heading. */
+  title: string;
+  /** The passage the claim rests on, at the length a 16rem card can hold. */
+  snippet: string;
+}
+interface InlineCitationProps extends Omit<ComponentProps<"p">, "children"> {
+  /** Sources attached to the numbered reference markers in the sentence. */
+  sources: CitationSource[];
+  /** Which citation preview is open, or null when none is open. */
+  openIndex: number | null;
+  /** Called when a citation marker opens or closes its preview. */
+  onOpenIndexChange: (index: number | null) => void;
+}
+/**
+ * Numbered references inside a sentence, each with a hover preview of its source.
+ *
+ * @example
+ * import { InlineCitation } from "@cueplusplus/ui/elements";
+ *
+ * <InlineCitation
+ *   sources={[
+ *     {
+ *       domain: "docs.example.com",
+ *       title: "Optimistic updates",
+ *       snippet: "Confirm writes after paint.",
+ *     },
+ *   ]}
+ *   openIndex={0}
+ *   onOpenIndexChange={setOpenIndex}
+ * />
+ */
+declare function InlineCitation({ sources, openIndex, onOpenIndexChange, className, ...props }: InlineCitationProps): import("react").JSX.Element;
+//#endregion
+export { CitationSource, InlineCitation, InlineCitationProps };

package/dist/elements/inline-citation.js

@@ -0,0 +1,93 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { useCuePortalProps } from "../system/portal.js";
+import { floating, mono } from "./surfaces.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { PreviewCard } from "@base-ui/react/preview-card";
+//#region src/elements/inline-citation.tsx
+function Citation({ index, source, open, onOpenChange }) {
+	const portalProps = useCuePortalProps();
+	return /* @__PURE__ */ jsxs(PreviewCard.Root, {
+		open,
+		onOpenChange,
+		children: [/* @__PURE__ */ jsx(PreviewCard.Trigger, {
+			delay: 0,
+			render: /* @__PURE__ */ jsx("button", { type: "button" }),
+			className: cn("mx-0.5 inline-flex h-4 min-w-4 translate-y-[-2px] cursor-default items-center justify-center rounded-(--radius-control) px-1 align-middle font-mono text-(length:--cue-text-micro) font-medium tabular-nums transition-colors", open ? "bg-accent text-accent-fg" : "bg-surface-2 text-fg-muted hover:text-fg"),
+			children: index + 1
+		}), /* @__PURE__ */ jsx(PreviewCard.Portal, {
+			...portalProps,
+			children: /* @__PURE__ */ jsx(PreviewCard.Positioner, {
+				side: "top",
+				sideOffset: 8,
+				children: /* @__PURE__ */ jsxs(PreviewCard.Popup, {
+					className: cn(floating, "z-50 w-64 origin-(--transform-origin) rounded-(--radius-overlay) p-3.5 outline-none", "transition-[opacity,scale] duration-200 ease-[cubic-bezier(0.23,1,0.32,1)] motion-reduce:transition-none", "data-[starting-style]:scale-[0.97] data-[starting-style]:opacity-0", "data-[ending-style]:scale-[0.97] data-[ending-style]:opacity-0"),
+					children: [
+						/* @__PURE__ */ jsxs("div", {
+							className: "flex items-center gap-1.5",
+							children: [/* @__PURE__ */ jsx("span", {
+								className: "bg-surface-2 text-fg-muted flex size-4 items-center justify-center rounded-(--radius-control) text-(length:--cue-text-micro) font-medium",
+								children: source.domain[0]?.toUpperCase()
+							}), /* @__PURE__ */ jsx("span", {
+								className: cn(mono, "text-fg-subtle"),
+								children: source.domain
+							})]
+						}),
+						/* @__PURE__ */ jsx("p", {
+							className: "mt-2 text-(length:--cue-text-body) leading-snug font-medium",
+							children: source.title
+						}),
+						/* @__PURE__ */ jsx("p", {
+							className: "text-fg-muted mt-1 text-(length:--cue-text-body) leading-relaxed",
+							children: source.snippet
+						})
+					]
+				})
+			})
+		})]
+	});
+}
+/**
+* Numbered references inside a sentence, each with a hover preview of its source.
+*
+* @example
+* import { InlineCitation } from "@cueplusplus/ui/elements";
+*
+* <InlineCitation
+*   sources={[
+*     {
+*       domain: "docs.example.com",
+*       title: "Optimistic updates",
+*       snippet: "Confirm writes after paint.",
+*     },
+*   ]}
+*   openIndex={0}
+*   onOpenIndexChange={setOpenIndex}
+* />
+*/
+function InlineCitation({ sources, openIndex, onOpenIndexChange, className, ...props }) {
+	return /* @__PURE__ */ jsxs("p", {
+		"data-slot": "inline-citation",
+		className: cn("text-fg max-w-sm text-(length:--cue-text-body) leading-relaxed", className),
+		...props,
+		children: [
+			"Optimistic updates keep the thread responsive while the server confirms the write",
+			sources[0] && /* @__PURE__ */ jsx(Citation, {
+				index: 0,
+				source: sources[0],
+				open: openIndex === 0,
+				onOpenChange: (open) => onOpenIndexChange(open ? 0 : null)
+			}),
+			". The store already exposes a consistent snapshot for every subscriber",
+			sources[1] && /* @__PURE__ */ jsx(Citation, {
+				index: 1,
+				source: sources[1],
+				open: openIndex === 1,
+				onOpenChange: (open) => onOpenIndexChange(open ? 1 : null)
+			}),
+			", so no extra reconciliation pass is needed."
+		]
+	});
+}
+//#endregion
+export { InlineCitation };

package/dist/elements/job-progress.d.ts

@@ -0,0 +1,49 @@
+import { ComponentProps } from "react";
+//#region src/elements/job-progress.d.ts
+/** One named stage of a long job, and how much of the whole it accounts for. */
+interface JobStage {
+  /** What the stage is called. Shown in the stage row, and the row's key. */
+  name: string;
+  /**
+   * How much of the job this stage is worth. The weights are summed and the bar is
+   * filled from them, so a job whose stages are not equal reads honestly — no unit is
+   * implied and they need not add to anything in particular.
+   */
+  weight: number;
+}
+/**
+ * Work measured in minutes: weighted stages, an ETA, and a way out.
+ *
+ * @example
+ * import { JobProgress } from "@cueplusplus/ui/elements";
+ *
+ * <JobProgress
+ *   title="Verify the fix on CI"
+ *   stages={stages}
+ *   stageIndex={1}
+ *   stageProgress={0.6}
+ *   eta="about 3 min"
+ * />
+ */
+declare function JobProgress({ title, stages, stageIndex, stageProgress, eta, onCancel, className, ...props }: Omit<ComponentProps<"div">, "children" | "title" | "stages" | "stageIndex" | "stageProgress" | "eta" | "onCancel"> & {
+  /** What the job is doing. */
+  title: string;
+  /**
+   * Stages with relative weights, so a long install does not read the same as a fast
+   * clone.
+   */
+  stages: readonly JobStage[];
+  /**
+   * Which stage is running. Passing stages.length marks the job finished, and the bar
+   * never runs past its track.
+   */
+  stageIndex: number;
+  /** Progress inside the current stage, 0 to 1. */
+  stageProgress: number;
+  /** Pre-formatted estimate. Replaced by done once finished. */
+  eta: string;
+  /** Called to stop the job. Hidden once it finishes. */
+  onCancel?: () => void;
+}): import("react").JSX.Element;
+//#endregion
+export { JobProgress, JobStage };

package/dist/elements/job-progress.js

@@ -0,0 +1,74 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { mono, paper } from "./surfaces.js";
+import { clamp, pct, progressOf, take } from "./range.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { CheckIcon, Loader2Icon, XIcon } from "lucide-react";
+//#region src/elements/job-progress.tsx
+/**
+* Work measured in minutes: weighted stages, an ETA, and a way out.
+*
+* @example
+* import { JobProgress } from "@cueplusplus/ui/elements";
+*
+* <JobProgress
+*   title="Verify the fix on CI"
+*   stages={stages}
+*   stageIndex={1}
+*   stageProgress={0.6}
+*   eta="about 3 min"
+* />
+*/
+function JobProgress({ title, stages, stageIndex, stageProgress, eta, onCancel, className, ...props }) {
+	const stage = progressOf(stageIndex, stages.length);
+	const progress = clamp(stageProgress, 0, 1);
+	const totalWeight = stages.reduce((sum, item) => sum + item.weight, 0) || 1;
+	const completed = take(stages, stage).reduce((sum, item) => sum + item.weight, 0);
+	const current = stages[stage];
+	const overall = pct(completed + (current ? current.weight * progress : 0), totalWeight);
+	const finished = stage >= stages.length;
+	return /* @__PURE__ */ jsxs("div", {
+		"data-slot": "job-progress",
+		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: [
+					finished ? /* @__PURE__ */ jsx(CheckIcon, { className: "size-3.5 shrink-0 text-ok" }) : /* @__PURE__ */ jsx(Loader2Icon, { className: "text-fg-subtle size-3.5 shrink-0 animate-spin motion-reduce:animate-none" }),
+					/* @__PURE__ */ jsx("span", {
+						className: "min-w-0 flex-1 truncate text-(length:--cue-text-body) font-medium",
+						children: title
+					}),
+					/* @__PURE__ */ jsx("span", {
+						className: cn(mono, "text-fg-subtle shrink-0 tabular-nums"),
+						children: finished ? "done" : eta
+					}),
+					!finished && /* @__PURE__ */ jsx("button", {
+						type: "button",
+						"aria-label": "Cancel the job",
+						onClick: onCancel,
+						className: cn("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", "size-6 shrink-0"),
+						children: /* @__PURE__ */ jsx(XIcon, { className: "size-3.5" })
+					})
+				]
+			}),
+			/* @__PURE__ */ jsx("span", {
+				className: "bg-surface-2 h-1 w-full overflow-hidden rounded-full",
+				children: /* @__PURE__ */ jsx("span", {
+					className: cn("block h-full rounded-full transition-[width] duration-500 ease-out motion-reduce:transition-none", finished ? "bg-ok" : "bg-stream"),
+					style: { width: `${overall}%` }
+				})
+			}),
+			/* @__PURE__ */ jsx("div", {
+				className: "flex flex-wrap gap-x-3 gap-y-1",
+				children: stages.map((item, i) => /* @__PURE__ */ jsx("span", {
+					className: cn(mono, i < stage ? "text-fg-subtle" : i === stage ? "text-fg" : "text-fg-subtle"),
+					children: item.name
+				}, item.name))
+			})
+		]
+	});
+}
+//#endregion
+export { JobProgress };

package/dist/elements/launcher-bubble.d.ts

@@ -0,0 +1,34 @@
+import { ComponentProps } from "react";
+//#region src/elements/launcher-bubble.d.ts
+/**
+ * The floating entry point, and the panel it opens into.
+ *
+ * @example
+ * import { LauncherBubble } from "@cueplusplus/ui/elements";
+ *
+ * <LauncherBubble
+ *   open={open}
+ *   unread={2}
+ *   greeting="Need a hand?"
+ *   prompts={prompts}
+ *   onToggle={toggle}
+ * />
+ */
+declare function LauncherBubble({ open, unread, greeting, prompts, onToggle, onPick, onStart, className, ...props }: Omit<ComponentProps<"div">, "children" | "open" | "unread" | "greeting" | "prompts" | "onToggle" | "onPick" | "onStart"> & {
+  /** Whether the panel is showing. The trigger icon crossfades either way. */
+  open: boolean;
+  /** Badge count on the closed bubble. Hidden at zero and while open. */
+  unread: number;
+  /** Opening line in the panel. */
+  greeting: string;
+  /** Ways in, so the first message does not have to be invented. */
+  prompts: readonly string[];
+  /** Called when the bubble is pressed. */
+  onToggle?: () => void;
+  /** Called when a starter prompt is chosen. */
+  onPick?: (prompt: string) => void;
+  /** Called from the Start a conversation action, for opening an empty thread. */
+  onStart?: () => void;
+}): import("react").JSX.Element;
+//#endregion
+export { LauncherBubble };

package/dist/elements/launcher-bubble.js

@@ -0,0 +1,72 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { inkButton } from "./surfaces.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { MessageCircleIcon, XIcon } from "lucide-react";
+//#region src/elements/launcher-bubble.tsx
+/**
+* The floating entry point, and the panel it opens into.
+*
+* @example
+* import { LauncherBubble } from "@cueplusplus/ui/elements";
+*
+* <LauncherBubble
+*   open={open}
+*   unread={2}
+*   greeting="Need a hand?"
+*   prompts={prompts}
+*   onToggle={toggle}
+* />
+*/
+function LauncherBubble({ open, unread, greeting, prompts, onToggle, onPick, onStart, className, ...props }) {
+	return /* @__PURE__ */ jsxs("div", {
+		"data-slot": "launcher-bubble",
+		className: cn("flex w-full max-w-[19rem] flex-col items-end gap-2.5", className),
+		...props,
+		children: [open && /* @__PURE__ */ jsxs("div", {
+			className: cn("bg-surface-2 border border-border-overlay", "cue-elements-fade-in cue-elements-zoom-in-95 cue-elements-slide-in-from-bottom-2 cue-elements-animate-in flex w-full flex-col gap-3 rounded-(--radius-overlay) p-4 duration-200"),
+			children: [
+				/* @__PURE__ */ jsxs("div", {
+					className: "flex flex-col gap-1",
+					children: [/* @__PURE__ */ jsx("span", {
+						className: "text-(length:--cue-text-body) font-medium",
+						children: greeting
+					}), /* @__PURE__ */ jsx("span", {
+						className: cn("font-mono text-(length:--cue-text-label) tracking-tight", "text-fg-subtle"),
+						children: "typically replies in a minute"
+					})]
+				}),
+				/* @__PURE__ */ jsx("div", {
+					className: "flex flex-col gap-1.5",
+					children: prompts.map((prompt) => /* @__PURE__ */ jsx("button", {
+						type: "button",
+						onClick: () => onPick?.(prompt),
+						className: cn("bg-fg/[0.06]", "hover:bg-surface-2 text-fg-muted rounded-(--radius-surface) px-3 py-2 text-start text-(length:--cue-text-body) transition-colors"),
+						children: prompt
+					}, prompt))
+				}),
+				/* @__PURE__ */ jsx("button", {
+					type: "button",
+					onClick: onStart,
+					className: cn("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", "flex h-8 items-center justify-center rounded-full text-(length:--cue-text-ui) font-medium"),
+					children: "Start a conversation"
+				})
+			]
+		}), /* @__PURE__ */ jsxs("button", {
+			type: "button",
+			"aria-expanded": open,
+			"aria-label": open ? "Close the assistant" : "Open the assistant",
+			onClick: onToggle,
+			className: cn(inkButton, "relative flex size-12 shrink-0 items-center justify-center rounded-full"),
+			children: [/* @__PURE__ */ jsxs("span", {
+				className: "grid",
+				children: [/* @__PURE__ */ jsx(MessageCircleIcon, { className: cn("size-5 transition-[opacity,rotate] duration-200 [grid-area:1/1]", open && "rotate-90 opacity-0") }), /* @__PURE__ */ jsx(XIcon, { className: cn("size-5 transition-[opacity,rotate] duration-200 [grid-area:1/1]", !open && "-rotate-90 opacity-0") })]
+			}), unread > 0 && !open && /* @__PURE__ */ jsx("span", {
+				className: cn("font-mono text-(length:--cue-text-label) tracking-tight", "bg-bg text-fg absolute -top-0.5 -right-0.5 flex size-4 items-center justify-center rounded-full tabular-nums"),
+				children: unread
+			})]
+		})]
+	});
+}
+//#endregion
+export { LauncherBubble };

package/dist/elements/live-region-announcer.d.ts

@@ -0,0 +1,130 @@
+import * as React from "react";
+//#region src/elements/live-region-announcer.d.ts
+/**
+ * Whether a {@link LiveRegionAnnouncer} is mounted and will do the speaking.
+ *
+ * The hook behind this family's one-speaker rule: an announcer and a
+ * `TailStatus` in the same console would otherwise narrate the same run twice,
+ * so the row asks this and goes quiet. Exported because a console with a status
+ * row of its own owes a reader the same courtesy — ask before becoming a second
+ * live region.
+ *
+ * @returns `true` while at least one announcer is mounted anywhere in the page.
+ * @example
+ * const spokenFor = useAnnouncerPresent();
+ * <div role={spokenFor ? undefined : "status"}>{action}</div>
+ */
+declare function useAnnouncerPresent(): boolean;
+interface LiveRegionAnnouncerProps extends Omit<React.ComponentPropsWithoutRef<"div">, "children"> {
+  /**
+   * The log of things worth saying, oldest first. Everything that arrives at
+   * the end of it after the announcer last looked is queued and read out in
+   * order.
+   *
+   * An **append-only** list: the announcer remembers how much of it it has
+   * seen, so a list that is trimmed at the head loses the announcements that
+   * were trimmed with it. Keep the run's log growing, or remount the announcer
+   * with a new `key` when you start a new one.
+   */
+  messages: readonly string[];
+  /**
+   * Milliseconds between announcements. Defaults to `400`, the reference's own
+   * spacing, which is roughly how long a short phrase takes to speak.
+   *
+   * This is the whole point of the component: a polite announcement that
+   * arrives while another is being spoken replaces it, so an unspaced queue is
+   * a queue most of which is never heard.
+   */
+  spacing?: number;
+  /**
+   * How many announcements may wait at once. Defaults to `5`, and the **oldest**
+   * are dropped past it — five deep behind a busy run, the newest is the true
+   * one and the backlog is history.
+   */
+  depth?: number;
+  /**
+   * Hold everything without dropping it: a modal is open, or the surface is
+   * behind something a reader is working in. The queue drains from where it
+   * stopped when this goes back to `false`.
+   *
+   * A prop rather than an internal ref-count of open overlays, deliberately:
+   * this library has its own portal and overlay contract, and an announcer with
+   * a second opinion about what is on screen would be wrong exactly when it
+   * mattered.
+   */
+  paused?: boolean;
+  /**
+   * Announce the messages that are already in the list at mount. Defaults to
+   * `false` — the reference's "skip the first observation" guard, and the
+   * reason restoring a session does not read the whole transcript aloud.
+   *
+   * The pause rules still hold over it: a backlog handed to an announcer that
+   * mounts into a hidden tab, or with `paused` already set, waits there rather
+   * than spending its first line. Restoring a session into a background tab is
+   * the case, and it is the one the rules exist for.
+   */
+  announceOnMount?: boolean;
+}
+/**
+ * One polite region, and a queue that makes it audible.
+ *
+ * The element in this family with no visual design at all, and the one that
+ * decides whether the rest of it can be used without a screen. An agent
+ * transcript is a stream of state changes, and the naive wiring — an
+ * `aria-live` region bound to the current status — announces almost none of
+ * them: polite announcements replace each other, so a region updated four times
+ * a second speaks once and swallows the rest.
+ *
+ * So this is a queue with four rules, all of them the reference's:
+ *
+ * - **Spacing.** One announcement every `spacing` milliseconds, so each is
+ *   spoken instead of overwritten.
+ * - **Depth, oldest dropped.** A backlog behind a busy run is history; the
+ *   newest five are what a reader needs.
+ * - **Paused while the page is hidden**, so a background tab does not read a
+ *   run out over whatever the reader is actually doing, and paused on demand
+ *   through `paused` while a modal has their attention. Both are in force from
+ *   the first render rather than the first effect, so an announcer mounted into
+ *   a hidden tab with a backlog does not spend a line of it learning where it
+ *   is.
+ * - **The trailing space.** A screen reader ignores a live region set to the
+ *   text it already holds; the same message twice is announced twice by
+ *   appending a space to the second, which changes the string without changing
+ *   a word of it.
+ *
+ * The region itself is mounted empty and stays mounted. A live region added to
+ * the document at the same moment as its text is a region most assistive
+ * technologies never announce, which is the most common way this fails in
+ * practice.
+ *
+ * What to say is the caller's: {@link ANNOUNCEMENTS} carries the nine
+ * transitions the study found announced, as templates a console can extend or
+ * translate.
+ *
+ * **It is the surface's one speaker.** `TailStatus` is a `role="status"` too,
+ * and a console that mounts both — which is the ordinary shape of an agent
+ * console — would have every state read out twice. So mounting this hands the
+ * speaking to it: a `TailStatus` anywhere on the page notices (through
+ * {@link useAnnouncerPresent}) and renders as an ordinary row, keeping its words
+ * on the screen and taking them out of the accessibility tree. Feed this the
+ * transitions that row would have narrated, or set `announce` on the row to
+ * decide the other way.
+ *
+ * @example
+ * import { ANNOUNCEMENTS, LiveRegionAnnouncer } from "@cueplusplus/ui/elements";
+ *
+ * // One per surface, mounted for the life of the transcript.
+ * <LiveRegionAnnouncer messages={log} paused={dialogOpen} />
+ * @example
+ * // Composed with the transcript's live row: the row draws, this one speaks.
+ * <>
+ *   <TailStatus action={TAIL_ACTIONS.searchingCode} detail="composer.tsx" />
+ *   <LiveRegionAnnouncer messages={log} />
+ * </>
+ * @example
+ * // The log is a caller's append-only list of what happened.
+ * setLog((was) => [...was, ANNOUNCEMENTS.working]);
+ */
+declare const LiveRegionAnnouncer: React.ForwardRefExoticComponent<LiveRegionAnnouncerProps & React.RefAttributes<HTMLDivElement>>;
+//#endregion
+export { LiveRegionAnnouncer, LiveRegionAnnouncerProps, useAnnouncerPresent };