From e703f7af2adc181eacb3fecedacada5eb71d2872 Mon Sep 17 00:00:00 2001
From: Haley Park <haleypark.design@gmail.com>
Date: Wed, 12 Aug 2026 14:38:50 -0700
Subject: [PATCH] style(desktop): refine session chat layout (#13205)

* style(ui): refine chat message surfaces and actions

* feat(desktop): refine session transcript layout

* style(desktop): refine conversation composer

* style(ui): format chat theme changes
---
 .../webview/components/ui/combobox.tsx        |   4 +-
 .../webview/components/ui/dropdown-menu.tsx   |  14 +-
 .../components/views/chat/chat-input-bar.tsx  |  63 ++--
 .../views/chat/chat-messages.test.tsx         |  22 +-
 .../components/views/chat/chat-messages.tsx   | 324 +++++++++---------
 .../views/chat/messages/message-bubble.tsx    |  17 +-
 .../components/views/chat/session-content.tsx |  21 ++
 .../components/views/chat/welcome-chat.tsx    |   5 +-
 .../ui/components/agent-chat/agent-chat.css   |  71 ++--
 .../ui/components/agent-chat/index.tsx        |  13 +-
 .../ui/stories/agent-chat.stories.tsx         | 109 +++++-
 sdk/packages/ui/theme/scoped-tokens.css       |   2 +
 sdk/packages/ui/theme/tokens.css              |   2 +
 13 files changed, 417 insertions(+), 250 deletions(-)
 create mode 100644 apps/examples/desktop-app/webview/components/views/chat/session-content.tsx

diff --git a/apps/examples/desktop-app/webview/components/ui/combobox.tsx b/apps/examples/desktop-app/webview/components/ui/combobox.tsx
index adfa7fa8d3..8254958ce1 100644
--- a/apps/examples/desktop-app/webview/components/ui/combobox.tsx
+++ b/apps/examples/desktop-app/webview/components/ui/combobox.tsx
@@ -113,7 +113,7 @@ function ComboboxContent({
 			>
 				<ComboboxPrimitive.Popup
 					className={cn(
-						"bg-popover text-popover-foreground data-open:animate-in data-closed:animate-out data-closed:fade-out-0 data-open:fade-in-0 data-closed:zoom-out-95 data-open:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 ring-foreground/10 *:data-[slot=input-group]:bg-input/30 *:data-[slot=input-group]:border-input/30 group/combobox-content relative max-h-96 w-(--anchor-width) max-w-(--available-width) min-w-[calc(var(--anchor-width)+--spacing(7))] origin-(--transform-origin) overflow-hidden rounded-md shadow-md ring-1 duration-100 data-[chips=true]:min-w-(--anchor-width) *:data-[slot=input-group]:m-1 *:data-[slot=input-group]:mb-0 *:data-[slot=input-group]:h-8 *:data-[slot=input-group]:shadow-none",
+						"bg-popover text-popover-foreground data-open:animate-in data-closed:animate-out data-closed:fade-out-0 data-open:fade-in-0 data-closed:zoom-out-95 data-open:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 ring-foreground/10 *:data-[slot=input-group]:bg-input/30 *:data-[slot=input-group]:border-input/30 group/combobox-content relative max-h-96 w-(--anchor-width) max-w-(--available-width) min-w-[calc(var(--anchor-width)+(--spacing(7)))] origin-(--transform-origin) overflow-hidden rounded-md shadow-md ring-1 duration-100 data-[chips=true]:min-w-(--anchor-width) *:data-[slot=input-group]:m-1 *:data-[slot=input-group]:mb-0 *:data-[slot=input-group]:h-8 *:data-[slot=input-group]:shadow-none",
 						className,
 					)}
 					data-chips={!!anchor}
@@ -129,7 +129,7 @@ function ComboboxList({ className, ...props }: ComboboxPrimitive.List.Props) {
 	return (
 		<ComboboxPrimitive.List
 			className={cn(
-				"max-h-[min(calc(--spacing(96)---spacing(9)),calc(var(--available-height)---spacing(9)))] scroll-py-1 overflow-y-auto p-1 data-empty:p-0",
+				"max-h-[min(calc(--spacing(96)-(--spacing(9))),calc(var(--available-height)-(--spacing(9))))] scroll-py-1 overflow-y-auto p-1 data-empty:p-0",
 				className,
 			)}
 			data-slot="combobox-list"
diff --git a/apps/examples/desktop-app/webview/components/ui/dropdown-menu.tsx b/apps/examples/desktop-app/webview/components/ui/dropdown-menu.tsx
index 06cfcd7817..71651ff4cd 100644
--- a/apps/examples/desktop-app/webview/components/ui/dropdown-menu.tsx
+++ b/apps/examples/desktop-app/webview/components/ui/dropdown-menu.tsx
@@ -42,7 +42,7 @@ function DropdownMenuContent({
 				data-slot="dropdown-menu-content"
 				sideOffset={sideOffset}
 				className={cn(
-					"bg-popover text-popover-foreground data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 z-50 max-h-(--radix-dropdown-menu-content-available-height) min-w-[8rem] origin-(--radix-dropdown-menu-content-transform-origin) overflow-x-hidden overflow-y-auto rounded-md border p-1 shadow-md",
+					"bg-popover text-popover-foreground data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 z-50 max-h-(--radix-dropdown-menu-content-available-height) min-w-32 origin-(--radix-dropdown-menu-content-transform-origin) overflow-x-hidden overflow-y-auto rounded-md border p-1 shadow-md",
 					className,
 				)}
 				{...props}
@@ -74,7 +74,7 @@ function DropdownMenuItem({
 			data-inset={inset}
 			data-variant={variant}
 			className={cn(
-				"focus:bg-surface-hover focus:text-foreground data-[variant=destructive]:text-destructive data-[variant=destructive]:focus:bg-destructive/10 dark:data-[variant=destructive]:focus:bg-destructive/20 data-[variant=destructive]:focus:text-destructive data-[variant=destructive]:*:[svg]:!text-destructive [&_svg:not([class*='text-'])]:text-muted-foreground relative flex cursor-default items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-hidden select-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 data-[inset]:pl-8 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+				"focus:bg-surface-hover focus:text-foreground data-[variant=destructive]:text-destructive data-[variant=destructive]:focus:bg-destructive/10 dark:data-[variant=destructive]:focus:bg-destructive/20 data-[variant=destructive]:focus:text-destructive data-[variant=destructive]:*:[svg]:text-destructive! [&_svg:not([class*='text-'])]:text-muted-foreground relative flex cursor-default items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-hidden select-none data-disabled:pointer-events-none data-disabled:opacity-50 data-inset:pl-8 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
 				className,
 			)}
 			{...props}
@@ -92,7 +92,7 @@ function DropdownMenuCheckboxItem({
 		<DropdownMenuPrimitive.CheckboxItem
 			data-slot="dropdown-menu-checkbox-item"
 			className={cn(
-				"focus:bg-surface-hover focus:text-foreground relative flex cursor-default items-center gap-2 rounded-sm py-1.5 pr-2 pl-8 text-sm outline-hidden select-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+				"focus:bg-surface-hover focus:text-foreground relative flex cursor-default items-center gap-2 rounded-sm py-1.5 pr-2 pl-8 text-sm outline-hidden select-none data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
 				className,
 			)}
 			checked={checked}
@@ -128,7 +128,7 @@ function DropdownMenuRadioItem({
 		<DropdownMenuPrimitive.RadioItem
 			data-slot="dropdown-menu-radio-item"
 			className={cn(
-				"focus:bg-surface-hover focus:text-foreground relative flex cursor-default items-center gap-2 rounded-sm py-1.5 pr-2 pl-8 text-sm outline-hidden select-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+				"focus:bg-surface-hover focus:text-foreground relative flex cursor-default items-center gap-2 rounded-sm py-1.5 pr-2 pl-8 text-sm outline-hidden select-none data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
 				className,
 			)}
 			{...props}
@@ -155,7 +155,7 @@ function DropdownMenuLabel({
 			data-slot="dropdown-menu-label"
 			data-inset={inset}
 			className={cn(
-				"px-2 py-1.5 text-sm font-medium data-[inset]:pl-8",
+				"px-2 py-1.5 text-sm font-medium data-inset:pl-8",
 				className,
 			)}
 			{...props}
@@ -211,7 +211,7 @@ function DropdownMenuSubTrigger({
 			data-slot="dropdown-menu-sub-trigger"
 			data-inset={inset}
 			className={cn(
-				"focus:bg-surface-hover focus:text-foreground data-[state=open]:bg-surface-hover data-[state=open]:text-foreground [&_svg:not([class*='text-'])]:text-muted-foreground flex cursor-default items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-hidden select-none data-[inset]:pl-8 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+				"focus:bg-surface-hover focus:text-foreground data-[state=open]:bg-surface-hover data-[state=open]:text-foreground [&_svg:not([class*='text-'])]:text-muted-foreground flex cursor-default items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-hidden select-none data-inset:pl-8 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
 				className,
 			)}
 			{...props}
@@ -230,7 +230,7 @@ function DropdownMenuSubContent({
 		<DropdownMenuPrimitive.SubContent
 			data-slot="dropdown-menu-sub-content"
 			className={cn(
-				"bg-popover text-popover-foreground data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 z-50 min-w-[8rem] origin-(--radix-dropdown-menu-content-transform-origin) overflow-hidden rounded-md border p-1 shadow-lg",
+				"bg-popover text-popover-foreground data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 z-50 min-w-32 origin-(--radix-dropdown-menu-content-transform-origin) overflow-hidden rounded-md border p-1 shadow-lg",
 				className,
 			)}
 			{...props}
diff --git a/apps/examples/desktop-app/webview/components/views/chat/chat-input-bar.tsx b/apps/examples/desktop-app/webview/components/views/chat/chat-input-bar.tsx
index fe5e8fe9d7..cb022788c8 100644
--- a/apps/examples/desktop-app/webview/components/views/chat/chat-input-bar.tsx
+++ b/apps/examples/desktop-app/webview/components/views/chat/chat-input-bar.tsx
@@ -141,9 +141,8 @@ const EFFORT_LEVELS: ReasoningEffortOption[] = [
 	{ label: "High", value: "high" },
 	{ label: "Extra", value: "xhigh" },
 ];
-// The composer keeps a steady two-line height whether or not it has focus —
-// resizing on blur made the bottom of the conversation jump around.
-const PROMPT_INPUT_ROWS = 2;
+const PROMPT_INPUT_COLLAPSED_ROWS = 1;
+const PROMPT_INPUT_EXPANDED_ROWS = 2;
 const PROMPT_INPUT_MAX_ROWS = 5;
 const PROMPT_INPUT_LINE_HEIGHT_REM = 1.25;
 
@@ -378,6 +377,7 @@ function ChatInputBarImpl({
 	}, [onSend, promptInput, setPromptInput]);
 	const fileInputRef = useRef<HTMLInputElement | null>(null);
 	const promptInputRef = useRef<HTMLTextAreaElement | null>(null);
+	const [promptInputFocused, setPromptInputFocused] = useState(false);
 	const [cursorIndex, setCursorIndex] = useState(() => promptInput.length);
 	// Mention/slash detection is derived synchronously from the input +
 	// cursor. Deriving (rather than syncing through effects) keeps a keystroke
@@ -429,7 +429,10 @@ function ChatInputBarImpl({
 			: !hasExplicitReasoningSelection && modelSupportsReasoning === false
 				? "None"
 				: (EFFORT_LEVELS[effortIndex]?.label ?? "Reasoning");
-	const promptInputRows = PROMPT_INPUT_ROWS;
+	const promptInputRows =
+		variant === "welcome" || promptInputFocused
+			? PROMPT_INPUT_EXPANDED_ROWS
+			: PROMPT_INPUT_COLLAPSED_ROWS;
 	const handleEffortChange = useCallback(
 		(value: string) => {
 			if (modelSupportsReasoning !== true) {
@@ -656,12 +659,17 @@ function ChatInputBarImpl({
 			className={cn(
 				"bg-card",
 				variant === "welcome"
-					? "overflow-visible rounded-xl border border-border/90 bg-card/90 shadow-[0_24px_80px_-56px_color-mix(in_oklab,var(--primary)_72%,transparent)] backdrop-blur-md"
-					: "border-t border-border bg-card/95 backdrop-blur-sm",
+					? "overflow-visible rounded-xl border border-border/90 bg-surface-1/40 shadow-[0_24px_80px_-56px_color-mix(in_oklab,var(--primary)_72%,transparent)] backdrop-blur-md"
+					: "overflow-visible rounded-xl border border-border bg-surface-2 backdrop-blur-sm focus-within:border-primary/50 focus-within:ring-1 focus-within:ring-primary/20",
 			)}
 		>
 			{/* Input area */}
-			<div className={cn("px-4 py-3", variant === "welcome" && "pb-2 pt-4")}>
+			<div
+				className={cn(
+					"px-4 py-3",
+					variant === "welcome" ? "pb-2 pt-4" : "py-4",
+				)}
+			>
 				<AgentPromptQueue
 					items={displayPromptsInQueue}
 					onEdit={onEditPromptInQueue}
@@ -754,14 +762,25 @@ function ChatInputBarImpl({
 							)}
 						</div>
 					)}
+					{/* biome-ignore lint/a11y/noStaticElementInteractions: Empty composer space forwards pointer focus to the nested textarea; keyboard users focus the textarea directly. */}
 					<div
 						className={cn(
-							// Focus feedback lands instantly — no transition — so the
-							// border reads as state, not animation.
 							"flex items-end gap-2 rounded-lg border border-border bg-background px-3 py-2.5 focus-within:border-primary/50 focus-within:ring-1 focus-within:ring-primary/20",
-							variant === "welcome" &&
-								"min-h-16 rounded-none border-0 bg-transparent px-0 py-0 focus-within:ring-0",
+							variant === "welcome"
+								? "min-h-16 rounded-none border-0 bg-transparent px-0 py-0 focus-within:ring-0"
+								: "min-h-24 items-start rounded-none border-0 bg-transparent px-0 py-0 focus-within:border-transparent focus-within:ring-0",
 						)}
+						onMouseDown={(event) => {
+							const target = event.target;
+							if (
+								target instanceof HTMLElement &&
+								target.closest("button, input, textarea")
+							) {
+								return;
+							}
+							event.preventDefault();
+							promptInputRef.current?.focus();
+						}}
 					>
 						<textarea
 							aria-activedescendant={
@@ -796,6 +815,8 @@ function ChatInputBarImpl({
 									e.currentTarget.selectionStart ?? promptInput.length,
 								)
 							}
+							onBlur={() => setPromptInputFocused(false)}
+							onFocus={() => setPromptInputFocused(true)}
 							onPaste={(e) => {
 								const images = imageFilesFromClipboard(e.clipboardData);
 								if (images.length > 0) {
@@ -898,7 +919,12 @@ function ChatInputBarImpl({
 							}}
 							value={promptInput}
 						/>
-						<div className="flex shrink-0 items-center gap-2">
+						<div
+							className={cn(
+								"flex shrink-0 items-center gap-2",
+								variant === "conversation" && "self-end",
+							)}
+						>
 							{canAbort && (
 								<button
 									aria-label="Stop agent"
@@ -956,7 +982,7 @@ function ChatInputBarImpl({
 			</div>
 
 			{/* Composer settings */}
-			<div className="flex min-w-0 items-center  justify-between gap-x-3 gap-y-2 border-t border-border px-2 py-2 text-sm text-muted-foreground">
+			<div className="flex min-w-0 items-center justify-between gap-x-3 gap-y-2 rounded-b-xl border-t border-border bg-muted/20 px-2 py-2 text-sm text-muted-foreground">
 				<div className="flex min-w-0 flex-auto flex-wrap items-center gap-2 max-[560px]:flex-nowrap">
 					<button
 						aria-label="Attach files"
@@ -1527,10 +1553,7 @@ function TokenUsageRing({ usage }: { usage: TokenUsage }) {
 							strokeWidth="4"
 						/>
 						<circle
-							className={cn(
-								"transition-[stroke,stroke-dashoffset] duration-200",
-								ringColorClass,
-							)}
+							className={cn("", ringColorClass)}
 							cx="11"
 							cy="11"
 							fill="none"
@@ -1560,13 +1583,13 @@ function TokenUsageRing({ usage }: { usage: TokenUsage }) {
 					<div className="mt-2 flex h-1 overflow-hidden rounded-full bg-muted">
 						<div
 							aria-hidden="true"
-							className="h-full shrink-0 bg-primary transition-[width] duration-200"
+							className="h-full shrink-0 bg-primary transition-[width] duration-120"
 							data-token-kind="uncached-input"
 							style={{ width: segmentWidth(uncachedInputTokens) }}
 						/>
 						<div
 							aria-hidden="true"
-							className="h-full shrink-0 bg-primary/60 transition-[background,width] duration-200"
+							className="h-full shrink-0 bg-primary/60 transition-[background,width] duration-120"
 							data-token-kind="cached-input"
 							style={{
 								backgroundImage:
@@ -1576,7 +1599,7 @@ function TokenUsageRing({ usage }: { usage: TokenUsage }) {
 						/>
 						<div
 							aria-hidden="true"
-							className="h-full shrink-0 bg-blue-500 transition-[background,width] duration-200"
+							className="h-full shrink-0 bg-blue-500 transition-[background,width] duration-120"
 							data-token-kind="output"
 							style={{
 								backgroundImage:
diff --git a/apps/examples/desktop-app/webview/components/views/chat/chat-messages.test.tsx b/apps/examples/desktop-app/webview/components/views/chat/chat-messages.test.tsx
index c251b861e4..73e80e1fa9 100644
--- a/apps/examples/desktop-app/webview/components/views/chat/chat-messages.test.tsx
+++ b/apps/examples/desktop-app/webview/components/views/chat/chat-messages.test.tsx
@@ -613,8 +613,9 @@ describe("ChatMessages tool disclosures", () => {
 		const messageList = message?.parentElement;
 		const content = message?.querySelector(".cline-chat-message-content");
 
-		// The list and the content column each own their spacing via gap-2...
-		expect(messageList?.classList.contains("gap-2")).toBe(true);
+		// The list owns conversation spacing via gap-8, while the content column
+		// keeps the tighter gap-2 spacing between blocks within one message.
+		expect(messageList?.classList.contains("gap-8")).toBe(true);
 		expect(content?.classList.contains("flex")).toBe(true);
 		expect(content?.classList.contains("flex-col")).toBe(true);
 		expect(content?.classList.contains("gap-2")).toBe(true);
@@ -666,19 +667,12 @@ describe("ChatMessages tool disclosures", () => {
 		);
 
 		expect(userMessage?.classList.contains("relative")).toBe(true);
-		expect(userActions?.classList.contains("absolute")).toBe(true);
-		expect(userActions?.classList.contains("right-0")).toBe(true);
-		expect(userActions?.classList.contains("top-full")).toBe(true);
-		expect(userActions?.classList.contains("pt-2")).toBe(true);
+		expect(userActions?.getAttribute("data-side")).toBe("end");
 		expect(assistantMessage?.classList.contains("relative")).toBe(true);
-		expect(assistantActions?.classList.contains("absolute")).toBe(true);
-		expect(assistantActions?.classList.contains("left-0")).toBe(true);
-		expect(assistantActions?.classList.contains("top-full")).toBe(true);
-		expect(assistantActions?.classList.contains("pt-2")).toBe(true);
+		expect(assistantActions?.getAttribute("data-side")).toBe("start");
 		expect(assistantActions?.getAttribute("data-visible")).toBe("true");
 		const userAction = userActions?.querySelector(".cline-chat-message-action");
-		expect(userAction?.classList.contains("min-w-0")).toBe(true);
-		expect(userAction?.classList.contains("p-0")).toBe(true);
+		expect(userAction?.getAttribute("data-slot")).toBe("icon-button");
 		const assistantActionButtons = [
 			...(assistantActions?.querySelectorAll(".cline-chat-message-action") ??
 				[]),
@@ -686,9 +680,7 @@ describe("ChatMessages tool disclosures", () => {
 		expect(assistantActionButtons).toHaveLength(2);
 		expect(
 			assistantActionButtons.every(
-				(action) =>
-					action.classList.contains("min-w-0") &&
-					action.classList.contains("p-0"),
+				(action) => action.getAttribute("data-slot") === "icon-button",
 			),
 		).toBe(true);
 		expect(userActions?.querySelector("time")?.getAttribute("datetime")).toBe(
diff --git a/apps/examples/desktop-app/webview/components/views/chat/chat-messages.tsx b/apps/examples/desktop-app/webview/components/views/chat/chat-messages.tsx
index 38153606a8..4d9a34420c 100644
--- a/apps/examples/desktop-app/webview/components/views/chat/chat-messages.tsx
+++ b/apps/examples/desktop-app/webview/components/views/chat/chat-messages.tsx
@@ -42,6 +42,7 @@ import {
 } from "./messages/tool-approval-panel";
 import { ToolMessageBlock } from "./messages/tool-message-block";
 import { buildToolPresentation } from "./messages/tool-summaries";
+import { SessionContent } from "./session-content";
 
 type ChatMessagesProps = {
 	sessionId: string | null;
@@ -476,173 +477,186 @@ function ChatMessagesImpl({
 			>
 				<ConversationContent
 					className={cn(
-						"relative mx-auto min-h-full w-full min-w-0 max-w-full",
-						showIdleDetails ? "p-0" : "px-6 pt-6 pb-14",
+						"min-h-full w-full min-w-0",
+						showIdleDetails ? "p-0" : "px-6",
 					)}
 				>
-					{showIdleDetails ? null : (
-						<div className="flex min-h-full w-full min-w-0 flex-col gap-2">
-							{renderItems.map((item) => {
-								if (item.type === "tools") {
+					<SessionContent
+						className={cn(
+							"relative min-h-full",
+							showIdleDetails ? "p-0" : "pt-6 pb-20",
+						)}
+					>
+						{showIdleDetails ? null : (
+							<div className="flex min-h-full w-full min-w-0 flex-col gap-8">
+								{renderItems.map((item) => {
+									if (item.type === "tools") {
+										return (
+											<ToolMessageBlock
+												key={`tools_${item.messages[0]?.id ?? "empty"}`}
+												messages={item.messages}
+											/>
+										);
+									}
+									const { agentRole, message, reasoningMessages } = item;
+									const firstReasoningMessage = reasoningMessages[0];
+									const lastReasoningMessage = reasoningMessages.at(-1);
+									const reasoningContent = reasoningMessages
+										.map((reasoningMessage) =>
+											reasoningMessage.reasoning?.trim(),
+										)
+										.filter((content): content is string => Boolean(content))
+										.join("\n\n");
 									return (
-										<ToolMessageBlock
-											key={`tools_${item.messages[0]?.id ?? "empty"}`}
-											messages={item.messages}
+										<MessageBubble
+											agentRole={agentRole}
+											isLastAssistantMessage={
+												message.role === "assistant" &&
+												lastConversationMessage === message
+											}
+											isStreaming={streamingMessageId === message.id}
+											key={message.id}
+											message={message}
+											runCount={userRunCountByMessage.get(message)}
+											onExpandImage={handleExpandImage}
+											onCopyMessage={handleCopyMessage}
+											onEditMessage={
+												onEditMessage ? requestEditMessage : undefined
+											}
+											editDisabled={
+												!onEditMessage ||
+												status === "starting" ||
+												status === "running" ||
+												status === "stopping" ||
+												isSessionSwitching ||
+												sessionVersioningPending
+											}
+											editError={editErrors[message.id]}
+											editPending={editingMessageId === message.id}
+											onRestoreCheckpoint={
+												onRestoreCheckpoint
+													? requestRestoreCheckpoint
+													: undefined
+											}
+											restoreDisabled={
+												!onRestoreCheckpoint ||
+												status === "starting" ||
+												status === "running" ||
+												status === "stopping" ||
+												isSessionSwitching ||
+												sessionVersioningPending
+											}
+											restoreError={checkpointErrors[message.id]}
+											restorePending={
+												checkpointActions[message.id] === "undoing"
+											}
+											wasCopied={copiedMessageId === message.id}
+											onForkSession={
+												onForkSession ? handleForkSession : undefined
+											}
+											forkDisabled={
+												status === "starting" ||
+												status === "running" ||
+												status === "stopping" ||
+												isSessionSwitching ||
+												sessionVersioningPending
+											}
+											forkPending={forkingMessageId === message.id}
+											forkError={forkErrors[message.id]}
+											reasoningContent={reasoningContent}
+											reasoningRedacted={reasoningMessages.some(
+												(reasoningMessage) =>
+													reasoningMessage.reasoningRedacted === true,
+											)}
+											thoughtDurationMilliseconds={
+												firstReasoningMessage && lastReasoningMessage
+													? getThoughtDurationMilliseconds(
+															previousTimestampByMessage.get(
+																firstReasoningMessage,
+															),
+															lastReasoningMessage.createdAt,
+														)
+													: undefined
+											}
 										/>
 									);
-								}
-								const { agentRole, message, reasoningMessages } = item;
-								const firstReasoningMessage = reasoningMessages[0];
-								const lastReasoningMessage = reasoningMessages.at(-1);
-								const reasoningContent = reasoningMessages
-									.map((reasoningMessage) => reasoningMessage.reasoning?.trim())
-									.filter((content): content is string => Boolean(content))
-									.join("\n\n");
-								return (
-									<MessageBubble
-										agentRole={agentRole}
-										isLastAssistantMessage={
-											message.role === "assistant" &&
-											lastConversationMessage === message
+								})}
+								{pendingToolApprovals.length > 0 ? (
+									<ToolApprovalPanel
+										items={pendingToolApprovals}
+										onApprove={(requestId) =>
+											handleToolApprovalDecision(
+												requestId,
+												"approving",
+												onApproveToolApproval,
+											)
 										}
-										isStreaming={streamingMessageId === message.id}
-										key={message.id}
-										message={message}
-										runCount={userRunCountByMessage.get(message)}
-										onExpandImage={handleExpandImage}
-										onCopyMessage={handleCopyMessage}
-										onEditMessage={
-											onEditMessage ? requestEditMessage : undefined
-										}
-										editDisabled={
-											!onEditMessage ||
-											status === "starting" ||
-											status === "running" ||
-											status === "stopping" ||
-											isSessionSwitching ||
-											sessionVersioningPending
-										}
-										editError={editErrors[message.id]}
-										editPending={editingMessageId === message.id}
-										onRestoreCheckpoint={
-											onRestoreCheckpoint ? requestRestoreCheckpoint : undefined
-										}
-										restoreDisabled={
-											!onRestoreCheckpoint ||
-											status === "starting" ||
-											status === "running" ||
-											status === "stopping" ||
-											isSessionSwitching ||
-											sessionVersioningPending
-										}
-										restoreError={checkpointErrors[message.id]}
-										restorePending={checkpointActions[message.id] === "undoing"}
-										wasCopied={copiedMessageId === message.id}
-										onForkSession={
-											onForkSession ? handleForkSession : undefined
-										}
-										forkDisabled={
-											status === "starting" ||
-											status === "running" ||
-											status === "stopping" ||
-											isSessionSwitching ||
-											sessionVersioningPending
-										}
-										forkPending={forkingMessageId === message.id}
-										forkError={forkErrors[message.id]}
-										reasoningContent={reasoningContent}
-										reasoningRedacted={reasoningMessages.some(
-											(reasoningMessage) =>
-												reasoningMessage.reasoningRedacted === true,
-										)}
-										thoughtDurationMilliseconds={
-											firstReasoningMessage && lastReasoningMessage
-												? getThoughtDurationMilliseconds(
-														previousTimestampByMessage.get(
-															firstReasoningMessage,
-														),
-														lastReasoningMessage.createdAt,
-													)
-												: undefined
+										onReject={(requestId) =>
+											handleToolApprovalDecision(
+												requestId,
+												"rejecting",
+												onRejectToolApproval,
+											)
 										}
+										pendingActions={toolApprovalActions}
+										requestErrors={toolApprovalErrors}
 									/>
-								);
-							})}
-							{pendingToolApprovals.length > 0 ? (
-								<ToolApprovalPanel
-									items={pendingToolApprovals}
-									onApprove={(requestId) =>
-										handleToolApprovalDecision(
-											requestId,
-											"approving",
-											onApproveToolApproval,
-										)
-									}
-									onReject={(requestId) =>
-										handleToolApprovalDecision(
-											requestId,
-											"rejecting",
-											onRejectToolApproval,
-										)
-									}
-									pendingActions={toolApprovalActions}
-									requestErrors={toolApprovalErrors}
-								/>
-							) : null}
-							{askQuestionItems.length > 0 ? (
-								<AgentAskQuestion
-									errors={askQuestionErrors}
-									items={askQuestionItems}
-									onAnswer={handleAskQuestionAnswer}
-									pendingAnswers={askQuestionActions}
-								/>
-							) : null}
-						</div>
-					)}
-					{showSwitchTransition ? (
-						hasMessages ? (
-							<div className="pointer-events-none absolute right-6 top-6 z-20 rounded-full border border-border/70 bg-background/90 px-3 py-1.5 text-xs text-muted-foreground shadow-sm backdrop-blur-[1px]">
-								<div className="flex items-center gap-1.5">
-									<Loader2 className="h-3.5 w-3.5 animate-spin" />
-									Switching session...
-								</div>
+								) : null}
+								{askQuestionItems.length > 0 ? (
+									<AgentAskQuestion
+										errors={askQuestionErrors}
+										items={askQuestionItems}
+										onAnswer={handleAskQuestionAnswer}
+										pendingAnswers={askQuestionActions}
+									/>
+								) : null}
 							</div>
-						) : (
-							<div className="rounded-xl border border-border/70 bg-card p-4">
-								<div className="mb-3 flex items-center gap-2 text-sm text-muted-foreground">
-									<Loader2 className="h-4 w-4 animate-spin" />
-									Loading session...
+						)}
+						{showSwitchTransition ? (
+							hasMessages ? (
+								<div className="pointer-events-none absolute right-6 top-6 z-20 rounded-full border border-border/70 bg-background/90 px-3 py-1.5 text-xs text-muted-foreground shadow-sm backdrop-blur-[1px]">
+									<div className="flex items-center gap-1.5">
+										<Loader2 className="h-3.5 w-3.5 animate-spin" />
+										Switching session...
+									</div>
 								</div>
-								<div className="space-y-3">
-									<div className="h-4 w-2/5 animate-pulse rounded bg-muted/70" />
-									<div className="h-4 w-4/5 animate-pulse rounded bg-muted/70" />
-									<div className="h-4 w-3/5 animate-pulse rounded bg-muted/70" />
+							) : (
+								<div className="rounded-xl border border-border/70 bg-card p-4">
+									<div className="mb-3 flex items-center gap-2 text-sm text-muted-foreground">
+										<Loader2 className="h-4 w-4 animate-spin" />
+										Loading session...
+									</div>
+									<div className="space-y-3">
+										<div className="h-4 w-2/5 animate-pulse rounded bg-muted/70" />
+										<div className="h-4 w-4/5 animate-pulse rounded bg-muted/70" />
+										<div className="h-4 w-3/5 animate-pulse rounded bg-muted/70" />
+									</div>
 								</div>
+							)
+						) : null}
+						{(status === "starting" || isAwaitingFirstOutput) &&
+						!isSessionSwitching ? (
+							<div className="flex min-h-7 items-center gap-2 py-1 text-sm font-medium text-muted-foreground">
+								<Loader2 className="size-4 animate-spin" />
+								<span className={STREAMING_TITLE_CLASS}>Thinking...</span>
 							</div>
-						)
-					) : null}
-					{(status === "starting" || isAwaitingFirstOutput) &&
-					!isSessionSwitching ? (
-						<div className="flex min-h-7 items-center gap-2 py-1 text-sm font-medium text-muted-foreground">
-							<Loader2 className="size-4 animate-spin" />
-							<span className={STREAMING_TITLE_CLASS}>Thinking...</span>
-						</div>
-					) : null}
-					{chatTransportState !== "connected" && !shouldShowErrorBanner ? (
-						<div className="mt-4 flex items-center gap-2 text-xs text-muted-foreground">
-							<Loader2 className="h-3.5 w-3.5 animate-spin" />
-							{chatTransportState === "reconnecting"
-								? "Reconnecting chat..."
-								: chatTransportState === "unavailable"
-									? "Chat backend unavailable"
-									: "Connecting chat..."}
-						</div>
-					) : null}
-					{shouldShowErrorBanner ? (
-						<div className="cline-chat-selectable mt-4 rounded-md border border-destructive/40 bg-destructive/10 p-3 text-sm text-destructive">
-							{error}
-						</div>
-					) : null}
+						) : null}
+						{chatTransportState !== "connected" && !shouldShowErrorBanner ? (
+							<div className="mt-4 flex items-center gap-2 text-xs text-muted-foreground">
+								<Loader2 className="h-3.5 w-3.5 animate-spin" />
+								{chatTransportState === "reconnecting"
+									? "Reconnecting chat..."
+									: chatTransportState === "unavailable"
+										? "Chat backend unavailable"
+										: "Connecting chat..."}
+							</div>
+						) : null}
+						{shouldShowErrorBanner ? (
+							<div className="cline-chat-selectable mt-4 rounded-md border border-destructive/40 bg-destructive/10 p-3 text-sm text-destructive">
+								{error}
+							</div>
+						) : null}
+					</SessionContent>
 				</ConversationContent>
 			</ConversationViewport>
 			<ConversationScrollButton />
diff --git a/apps/examples/desktop-app/webview/components/views/chat/messages/message-bubble.tsx b/apps/examples/desktop-app/webview/components/views/chat/messages/message-bubble.tsx
index 2a2dd13031..b0a3e261fd 100644
--- a/apps/examples/desktop-app/webview/components/views/chat/messages/message-bubble.tsx
+++ b/apps/examples/desktop-app/webview/components/views/chat/messages/message-bubble.tsx
@@ -126,7 +126,7 @@ export const MessageBubble = memo(function MessageBubble({
 		</time>
 	) : null;
 
-	// Spacing between blocks comes solely from the conversation list's `gap-2`
+	// Spacing between blocks comes solely from the conversation list's `gap-8`
 	// and this content column's `gap-2`; blocks must not add their own margins.
 	return (
 		<AgentMessage className="relative flex flex-col gap-2" from={agentRole}>
@@ -173,13 +173,9 @@ export const MessageBubble = memo(function MessageBubble({
 
 			{shouldRenderUserActions ? (
 				<>
-					<MessageActions
-						className="absolute right-0 top-full z-10 pt-2"
-						visible={keepUserActionsVisible}
-					>
+					<MessageActions side="end" visible={keepUserActionsVisible}>
 						{onCopyMessage ? (
 							<MessageAction
-								className="min-w-0 p-0 text-muted-foreground/70 hover:text-foreground"
 								label={wasCopied ? "Copied user message" : "Copy user message"}
 								onClick={() => void onCopyMessage(message.id, message.content)}
 								title={wasCopied ? "Copied" : "Copy message"}
@@ -193,7 +189,6 @@ export const MessageBubble = memo(function MessageBubble({
 						) : null}
 						{onEditMessage && runCount && displayContent.trim() ? (
 							<MessageAction
-								className="min-w-0 p-0 text-muted-foreground/70 hover:text-foreground"
 								disabled={editDisabled || editPending}
 								label="Edit user message"
 								onClick={() =>
@@ -210,7 +205,6 @@ export const MessageBubble = memo(function MessageBubble({
 						) : null}
 						{checkpoint ? (
 							<MessageAction
-								className="min-w-0 p-0 text-muted-foreground/70 hover:text-foreground"
 								disabled={restoreDisabled || restorePending}
 								label="Restore checkpoint"
 								onClick={() =>
@@ -241,13 +235,9 @@ export const MessageBubble = memo(function MessageBubble({
 			) : null}
 
 			{shouldRenderAssistantActions ? (
-				<MessageActions
-					className="absolute left-0 top-full z-10 pt-2"
-					visible={keepAssistantActionsVisible}
-				>
+				<MessageActions side="start" visible={keepAssistantActionsVisible}>
 					{onCopyMessage ? (
 						<MessageAction
-							className="min-w-0 p-0 text-muted-foreground/70 hover:text-foreground"
 							label={
 								wasCopied
 									? "Copied assistant message"
@@ -265,7 +255,6 @@ export const MessageBubble = memo(function MessageBubble({
 					) : null}
 					{onForkSession ? (
 						<MessageAction
-							className="min-w-0 p-0 text-muted-foreground/70 hover:text-foreground"
 							disabled={forkDisabled || forkPending}
 							label="Fork session"
 							onClick={() => void onForkSession(message.id)}
diff --git a/apps/examples/desktop-app/webview/components/views/chat/session-content.tsx b/apps/examples/desktop-app/webview/components/views/chat/session-content.tsx
new file mode 100644
index 0000000000..b1158e964a
--- /dev/null
+++ b/apps/examples/desktop-app/webview/components/views/chat/session-content.tsx
@@ -0,0 +1,21 @@
+import type { ReactNode } from "react";
+import { cn } from "@/lib/utils";
+
+export function SessionContent({
+	children,
+	className,
+}: {
+	children: ReactNode;
+	className?: string;
+}) {
+	return (
+		<div
+			className={cn(
+				"mx-auto w-full min-w-0 max-w-(--breakpoint-lg)",
+				className,
+			)}
+		>
+			{children}
+		</div>
+	);
+}
diff --git a/apps/examples/desktop-app/webview/components/views/chat/welcome-chat.tsx b/apps/examples/desktop-app/webview/components/views/chat/welcome-chat.tsx
index be56d4ee35..7f6c10a745 100644
--- a/apps/examples/desktop-app/webview/components/views/chat/welcome-chat.tsx
+++ b/apps/examples/desktop-app/webview/components/views/chat/welcome-chat.tsx
@@ -11,6 +11,7 @@ import type { ReactNode } from "react";
 import { useEffect, useMemo } from "react";
 import { useWorkspace } from "@/contexts/workspace-context";
 import { cn } from "@/lib/utils";
+import { SessionContent } from "./session-content";
 import { WelcomeWorkspaceControls } from "./welcome-workspace-controls";
 
 /** Code-centric starters, shown only when the folder is a git repository. */
@@ -210,10 +211,10 @@ export function WelcomeScreen({
 					{active && notice ? notice : null}
 
 					<div
-						className={active ? "mt-4 w-full" : "z-20 shrink-0"}
+						className={active ? "mt-4 w-full" : "z-20 shrink-0 px-6 pb-6"}
 						key="persistent-composer"
 					>
-						{composer}
+						{active ? composer : <SessionContent>{composer}</SessionContent>}
 					</div>
 
 					{active ? (
diff --git a/sdk/packages/ui/components/agent-chat/agent-chat.css b/sdk/packages/ui/components/agent-chat/agent-chat.css
index 5d61e6ced7..66b72b34e3 100644
--- a/sdk/packages/ui/components/agent-chat/agent-chat.css
+++ b/sdk/packages/ui/components/agent-chat/agent-chat.css
@@ -87,6 +87,7 @@
 	}
 
 	.cline-chat-message {
+		position: relative;
 		display: flex;
 		width: 100%;
 		min-width: 0;
@@ -97,6 +98,18 @@
 		overflow-wrap: anywhere;
 	}
 
+	/* Invisible hover bridge across only the gap before the absolutely-positioned
+	 * actions. Keeping it narrow avoids intercepting pointer events intended for
+	 * the following message. */
+	.cline-chat-message::after {
+		content: "";
+		position: absolute;
+		top: 100%;
+		left: 0;
+		right: 0;
+		height: 0.4rem;
+	}
+
 	.cline-chat-message[data-role="user"] {
 		align-items: flex-end;
 	}
@@ -109,14 +122,14 @@
 		color: var(--foreground);
 	}
 
-	/* User bubbles sit on the brand surface so the person's words read as the
-	 * strongest element in the transcript rather than blending into cards. */
+	/* User bubbles use the card surface with a subtle edge so they remain
+	 * distinct from the transcript without overpowering assistant content. */
 	.cline-chat-message[data-role="user"] > .cline-chat-message-content {
 		max-width: 85%;
-		padding: 0.5rem;
-		border-radius: calc(var(--radius) - 4px);
-		background: var(--brand-violet-surface, var(--primary));
-		color: var(--brand-violet-surface-foreground, var(--primary-foreground));
+		padding: 0.6rem 0.8rem;
+		border-radius: calc(var(--radius));
+		background: var(--card-surface);
+		border: 1px solid var(--neutral-a3);
 	}
 
 	.cline-chat-message[data-role="error"] > .cline-chat-message-content {
@@ -135,12 +148,27 @@
 	/* Actions appear and vanish instantly — a fade on hover chrome reads as
 	 * lag, not polish. */
 	.cline-chat-message-actions {
+		position: absolute;
+		top: 100%;
+		z-index: 10;
 		display: flex;
 		min-height: 1.5rem;
 		align-items: center;
-		gap: 0.25rem;
 		pointer-events: none;
 		opacity: 0;
+		margin-top: 0.1rem;
+	}
+
+	.cline-chat-message-actions[data-side="start"] {
+		left: 0;
+	}
+
+	.cline-chat-message-actions[data-side="end"] {
+		right: 0;
+	}
+
+	.cline-chat-message[data-role="assistant"] > .cline-chat-message-actions {
+		margin-top: 0.25rem;
 	}
 
 	.cline-chat-message:hover > .cline-chat-message-actions,
@@ -154,30 +182,22 @@
 	}
 
 	.cline-chat-message-action {
-		display: inline-flex;
-		min-width: 1.5rem;
-		height: 1.5rem;
-		align-items: center;
-		justify-content: center;
-		gap: 0.375rem;
-		padding: 0 0.5rem;
-		border: 0;
-		border-radius: calc(var(--radius) - 4px);
-		background: transparent;
-		color: var(--muted-foreground);
+		width: 1.75rem;
+		height: 1.75rem;
+		min-width: 1.75rem;
+		padding: 0;
+		aspect-ratio: 1;
 		font: inherit;
 		font-size: var(--text-xs);
-		cursor: pointer;
 	}
 
-	.cline-chat-message-action:hover {
-		background: var(--accent);
-		color: var(--foreground);
+	.cline-chat-message-action > svg {
+		width: 0.875rem;
+		height: 0.875rem;
 	}
 
-	.cline-chat-message-action:disabled {
-		cursor: not-allowed;
-		opacity: 0.5;
+	.cline-chat-message-actions > time {
+		margin-inline-start: 0.25rem;
 	}
 
 	.cline-chat-reasoning {
@@ -221,7 +241,6 @@
 
 	.cline-chat-disclosure-icon {
 		flex: 0 0 auto;
-		transition: transform 150ms ease;
 	}
 
 	[aria-expanded="true"] > .cline-chat-disclosure-icon {
diff --git a/sdk/packages/ui/components/agent-chat/index.tsx b/sdk/packages/ui/components/agent-chat/index.tsx
index 56074f2965..29caf69fff 100644
--- a/sdk/packages/ui/components/agent-chat/index.tsx
+++ b/sdk/packages/ui/components/agent-chat/index.tsx
@@ -18,6 +18,7 @@ import {
 	useRef,
 	useState,
 } from "react";
+import { IconButton } from "../button.js";
 
 const STICK_TO_BOTTOM_THRESHOLD_PX = 24;
 const SCROLL_BUTTON_THRESHOLD_PX = 120;
@@ -81,8 +82,7 @@ export const Conversation = forwardRef<HTMLDivElement, ConversationProps>(
 			if (!viewport) return;
 			const distance =
 				viewport.scrollHeight - viewport.scrollTop - viewport.clientHeight;
-			const scrolledUp =
-				viewport.scrollTop < lastObservedScrollTop.current - 1;
+			const scrolledUp = viewport.scrollTop < lastObservedScrollTop.current - 1;
 			lastObservedScrollTop.current = viewport.scrollTop;
 			if (isProgrammaticScroll.current) {
 				if (viewport.scrollTop + 1 < lastProgrammaticScrollTop.current) {
@@ -398,17 +398,20 @@ export const MessageContent = ({
 );
 
 export type MessageActionsProps = HTMLAttributes<HTMLDivElement> & {
+	side?: "start" | "end";
 	visible?: boolean;
 };
 
 export const MessageActions = ({
 	className,
+	side,
 	visible = false,
 	...props
 }: MessageActionsProps) => (
 	<div
 		{...props}
 		className={classNames("cline-chat-message-actions", className)}
+		data-side={side}
 		data-visible={visible || undefined}
 	/>
 );
@@ -426,11 +429,13 @@ export const MessageAction = ({
 	label,
 	...props
 }: MessageActionProps) => (
-	<button
+	<IconButton
 		{...props}
 		aria-label={ariaLabel ?? label}
 		className={classNames("cline-chat-message-action", className)}
-		type="button"
+		variant="ghost"
+		tone="neutral"
+		size="xs"
 	/>
 );
 
diff --git a/sdk/packages/ui/stories/agent-chat.stories.tsx b/sdk/packages/ui/stories/agent-chat.stories.tsx
index 21bb7901bc..a27f09131c 100644
--- a/sdk/packages/ui/stories/agent-chat.stories.tsx
+++ b/sdk/packages/ui/stories/agent-chat.stories.tsx
@@ -54,6 +54,88 @@ function EditIcon() {
 	return <span aria-hidden="true">✎</span>;
 }
 
+function CopyIcon() {
+	return (
+		<svg
+			aria-hidden="true"
+			fill="none"
+			stroke="currentColor"
+			strokeLinecap="round"
+			strokeLinejoin="round"
+			strokeWidth="2"
+			viewBox="0 0 24 24"
+		>
+			<rect height="14" rx="2" ry="2" width="14" x="8" y="8" />
+			<path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2" />
+		</svg>
+	);
+}
+
+function PencilIcon() {
+	return (
+		<svg
+			aria-hidden="true"
+			fill="none"
+			stroke="currentColor"
+			strokeLinecap="round"
+			strokeLinejoin="round"
+			strokeWidth="2"
+			viewBox="0 0 24 24"
+		>
+			<path d="M12 20h9" />
+			<path d="M16.5 3.5a2.1 2.1 0 0 1 3 3L7 19l-4 1 1-4Z" />
+		</svg>
+	);
+}
+
+function UndoIcon() {
+	return (
+		<svg
+			aria-hidden="true"
+			fill="none"
+			stroke="currentColor"
+			strokeLinecap="round"
+			strokeLinejoin="round"
+			strokeWidth="2"
+			viewBox="0 0 24 24"
+		>
+			<path d="M9 14 4 9l5-5" />
+			<path d="M4 9h10.5a5.5 5.5 0 0 1 0 11H11" />
+		</svg>
+	);
+}
+
+function ForkIcon() {
+	return (
+		<svg
+			aria-hidden="true"
+			className="rotate-90"
+			fill="none"
+			stroke="currentColor"
+			strokeLinecap="round"
+			strokeLinejoin="round"
+			strokeWidth="2"
+			viewBox="0 0 24 24"
+		>
+			<path d="M16 3h5v5" />
+			<path d="M8 3H3v5" />
+			<path d="M12 22v-8.3a4 4 0 0 0-1.172-2.872L3 3" />
+			<path d="m15 9 6-6" />
+		</svg>
+	);
+}
+
+function MessageTimestamp({ children }: { children: React.ReactNode }) {
+	return (
+		<time
+			className="shrink-0 whitespace-nowrap text-xs leading-none text-muted-foreground"
+			dateTime="2026-08-11T11:18:00-07:00"
+		>
+			{children}
+		</time>
+	);
+}
+
 function ChatFrame({ children }: { children: React.ReactNode }) {
 	return (
 		<div className="flex h-[680px] min-w-[320px] bg-background">
@@ -75,10 +157,20 @@ export const CompleteConversation = () => (
 			<MessageContent>
 				Can you find the settings screen and align it with our shared theme?
 			</MessageContent>
-			<MessageActions>
+			<MessageActions side="end">
 				<MessageAction label="Copy user message" title="Copy message">
-					Copy
+					<CopyIcon />
 				</MessageAction>
+				<MessageAction
+					label="Edit user message"
+					title="Edit message and restart from this point"
+				>
+					<PencilIcon />
+				</MessageAction>
+				<MessageAction label="Restore checkpoint" title="Restore checkpoint">
+					<UndoIcon />
+				</MessageAction>
+				<MessageTimestamp>11:18 AM</MessageTimestamp>
 			</MessageActions>
 		</Message>
 
@@ -134,10 +226,17 @@ export const CompleteConversation = () => (
 					<li>Verified keyboard focus states</li>
 				</ul>
 			</MessageContent>
-			<MessageActions>
+			<MessageActions side="start">
 				<MessageAction label="Copy assistant message" title="Copy response">
-					Copy
+					<CopyIcon />
 				</MessageAction>
+				<MessageAction
+					label="Fork session"
+					title="Fork session - copy full message history into a new session"
+				>
+					<ForkIcon />
+				</MessageAction>
+				<MessageTimestamp>11:18 AM</MessageTimestamp>
 			</MessageActions>
 		</Message>
 	</ChatFrame>
@@ -404,7 +503,7 @@ export const DisabledControls = () => (
 			<MessageContent>Actions stay readable when unavailable.</MessageContent>
 			<MessageActions visible>
 				<MessageAction disabled label="Copy message">
-					Copy
+					<CopyIcon />
 				</MessageAction>
 			</MessageActions>
 			<Reasoning>
diff --git a/sdk/packages/ui/theme/scoped-tokens.css b/sdk/packages/ui/theme/scoped-tokens.css
index fd20a01d8e..6f62c8b26d 100644
--- a/sdk/packages/ui/theme/scoped-tokens.css
+++ b/sdk/packages/ui/theme/scoped-tokens.css
@@ -355,6 +355,7 @@
 	--brand-magenta: oklch(0.75 0.15 330);
 	--brand-periwinkle: oklch(0.69 0.14 275);
 	--brand-cyan: oklch(0.87 0.07 210);
+	--card-surface: color-mix(in srgb, var(--neutral-2) 50%, var(--neutral-3));
 
 	/* Standard Tailwind typography variables. Consumers provide the fonts. */
 	--font-sans: "Inter Variable", sans-serif;
@@ -405,6 +406,7 @@
 	--brand-magenta: oklch(0.64 0.17 330);
 	--brand-periwinkle: oklch(0.63 0.16 275);
 	--brand-cyan: oklch(0.72 0.09 210);
+	--card-surface: var(--neutral-3);
 	--font-weight-normal: 400;
 	--font-weight-medium: 500;
 	--font-weight-semibold: 600;
diff --git a/sdk/packages/ui/theme/tokens.css b/sdk/packages/ui/theme/tokens.css
index 9ba196c4ed..1a38bb9903 100644
--- a/sdk/packages/ui/theme/tokens.css
+++ b/sdk/packages/ui/theme/tokens.css
@@ -19,6 +19,7 @@
 	--brand-magenta: oklch(0.75 0.15 330);
 	--brand-periwinkle: oklch(0.69 0.14 275);
 	--brand-cyan: oklch(0.87 0.07 210);
+	--card-surface: color-mix(in srgb, var(--neutral-2) 50%, var(--neutral-3));
 
 	/* Standard Tailwind typography variables. Consumers provide the fonts. */
 	--font-sans: "Inter Variable", sans-serif;
@@ -68,6 +69,7 @@
 	--brand-magenta: oklch(0.64 0.17 330);
 	--brand-periwinkle: oklch(0.63 0.16 275);
 	--brand-cyan: oklch(0.72 0.09 210);
+	--card-surface: var(--neutral-3);
 	--font-weight-normal: 400;
 	--font-weight-medium: 500;
 	--font-weight-semibold: 600;