entasis 0.11.0 → 0.13.0

package/dist/components/AIThread/AIThread.svelte

@@ -1,11 +1,16 @@
 <script lang="ts" generics="TMessage extends AIThreadItem = AIThreadItem">
-	import { createVirtualizer } from '@tanstack/svelte-virtual';
+	import { on } from 'svelte/events';
+	import {
+		createVirtualizer,
+		measureElement as measureVirtualElement
+	} from '@tanstack/svelte-virtual';
 	import { onDestroy, tick, untrack } from 'svelte';
 	import type { Attachment } from 'svelte/attachments';
 	import { get } from 'svelte/store';
 	import Alert from '../Alert/Alert.svelte';
 	import Button from '../Button/Button.svelte';
 	import type { AIMessageSize } from '../AIMessage/aiMessage.props.js';
+	import AISuggestions from '../AISuggestion/AISuggestions.svelte';
 	import { arrowDownIcon } from '../Icons/arrowDown.js';
 	import type {
 		AIAskAnswers,
@@ -32,9 +37,6 @@
 	import { AIThreadScrollController } from './threadScrollController.js';
 	import { useI18n } from '../../i18n/context.svelte.js';
 
-	type EndStateVirtualizer = {
-		isAtEnd: (threshold?: number) => boolean;
-	};
 	const DENSITY_PADDING: Record<AIThreadDensity, number> = {
 		compact: 8,
 		normal: 16,
@@ -45,21 +47,11 @@
 		normal: 96,
 		comfortable: 120
 	};
-	const MESSAGE_ACTION_HEIGHT: Record<AIMessageSize, number> = {
-		small: 24,
-		normal: 28,
-		large: 32
-	};
-	const MESSAGE_BOTTOM_PADDING: Record<AIMessageSize, number> = {
-		small: 6,
-		normal: 8,
-		large: 10
-	};
-	const ITEM_BOTTOM_PADDING: Record<AIThreadDensity, number> = {
-		compact: 2,
-		normal: 8,
-		comfortable: 14
-	};
+	// The scroll-to-latest button shows as soon as the view is this far from the end.
+	const SCROLL_BUTTON_THRESHOLD = 8;
+	// Below this viewport width the table of contents and its gutter step aside (AIThreadToc's own
+	// narrow-container width), so a phone-width thread keeps its full width for messages.
+	const TOC_MIN_VIEWPORT_WIDTH = 480;
 	function normalizeThreadScale(value: unknown): 'small' | 'normal' | 'large' {
 		return value === 'small' || value === 'large' ? value : 'normal';
 	}
@@ -75,7 +67,9 @@
 		streaming,
 		density = 'normal',
 		messageSize = 'normal',
-		messageVariant = 'bubble',
+		messageVariant = 'minimal',
+		messageColor,
+		contentWidth,
 		followOutput = true,
 		bottomThreshold = 80,
 		estimateSize,
@@ -85,20 +79,25 @@
 		paddingEnd,
 		scrollBehavior = 'smooth',
 		showScrollButton = true,
-		scrollButtonPosition = 'right',
+		scrollButtonPosition = 'center',
 		showToc = false,
 		tocSide = 'left',
 		tocMaxPins,
+		tocShowRange = false,
 		tocTheme,
 		activeAskUserQuestion,
 		renderAskUserQuestion = true,
 		askUserQuestionDisabled = false,
 		suggestions,
+		showFollowUps = true,
 		onSelect,
+		error: errorProp,
+		showError = true,
+		onErrorRetry,
 		empty,
 		message: messageSlot,
 		messageActions,
-		messageActionsVisibility,
+		messageActionsVisibility = 'latest',
 		messageCopyable,
 		messageEditable,
 		messageRetryable,
@@ -133,21 +132,30 @@
 	const conversation = getAIConversation<TMessage>();
 	const generatedKeys = new WeakMap<object, string>();
 	const questionPublisher = new AIThreadAskUserQuestionPublisher<TMessage>();
-	const scrollController = new AIThreadScrollController(() => scrollBehavior);
+	const scrollController = new AIThreadScrollController();
 	let generatedKeyId = 0;
 	let viewport = $state<HTMLDivElement>();
 	let viewportHeight = $state(0);
+	let viewportWidth = $state(0);
 	let viewportScrollTop = $state(0);
 	let isPinned = $state(true);
 	let hasInitializedEnd = $state(false);
 	let isInitializingEnd = $state(false);
 	let isFollowingAppendedItem = $state(false);
+	// The thread follows new output only while the user is at the very end. Scrolling up stops it;
+	// scrolling back to the end resumes it. Nothing else moves the user's scroll position.
+	let lastScrollTop = 0;
+	// A pointer or a finger is down on the transcript: a scroll now is the reader dragging it (the
+	// scrollbar, a touch pan), not layout or the virtualizer moving the offset.
+	let isDragging = false;
+	let stickFrame: number | undefined;
+	// Set while the virtualizer handles its ResizeObserver delivery (see `measureItem`).
+	let isInResizeDelivery = false;
 	let errorMessage = $state<string>();
 	let questionStates = $state<Record<string, AIThreadAskUserQuestionState | undefined>>({});
 	let questionValuesByKey = $state<Record<string, AIAskAnswers | undefined>>({});
 	let previousRenderItemCount = 0;
 	let previousFirstRenderItemKey: string | undefined;
-	let shouldSmoothAppendedItem = false;
 	let prependScrollTarget: 'start' | 'end' | undefined;
 	let initialEndFrame: number | undefined;
 	let initialEndSchedule = 0;
@@ -158,24 +166,23 @@
 	);
 	const resolvedPadding = $derived(Math.max(0, padding ?? DENSITY_PADDING[resolvedDensity]));
 	const resolvedPaddingStart = $derived(Math.max(0, paddingStart ?? resolvedPadding));
-	const messageActionOverflow = $derived(
-		messageActions === false || messageActionsVisibility === 'none'
-			? 0
-			: Math.max(
-					0,
-					MESSAGE_ACTION_HEIGHT[resolvedMessageSize] -
-						MESSAGE_BOTTOM_PADDING[resolvedMessageSize] -
-						ITEM_BOTTOM_PADDING[resolvedDensity]
-				)
-	);
-	const resolvedPaddingEnd = $derived(
-		Math.max(0, paddingEnd ?? Math.max(resolvedPadding, messageActionOverflow))
-	);
+	// Message actions take layout space inside their row, so the end padding no longer reserves
+	// room for an action bar hanging below the last message.
+	const resolvedPaddingEnd = $derived(Math.max(0, paddingEnd ?? resolvedPadding));
+	// The follow-up suggestions float over the bottom of the transcript (no band of their own), so
+	// the list ends that much lower: at the end, the last row still sits above the chips.
+	let followUpsHeight = $state(0);
 
 	const resolvedMessages = $derived<readonly TMessage[]>(messages ?? conversation?.messages ?? []);
 	const resolvedLiveText = $derived(liveText ?? conversation?.liveText);
 	const resolvedStreaming = $derived(streaming ?? conversation?.streaming ?? false);
 	const resolvedSuggestions = $derived(suggestions ?? conversation?.suggestions ?? []);
+	const resolvedError = $derived(errorProp !== undefined ? errorProp : conversation?.error);
+	const hasErrorRow = $derived(showError && resolvedError !== undefined);
+	const errorRetry = $derived(resolveErrorRetry());
+	const resolvedContentWidth = $derived(
+		typeof contentWidth === 'number' ? `${contentWidth}px` : contentWidth
+	);
 	const messageKeys = $derived.by(() => createMessageKeys(resolvedMessages));
 	const detectedQuestion = $derived<AIThreadAskUserQuestion<TMessage> | null>(
 		findActiveAskUserQuestion(
@@ -198,22 +205,17 @@
 		return deriveAIThreadRenderItems(resolvedMessages, {
 			getMessageKey: (_message, index) => messageKeys[index] ?? `missing:${index}`,
 			activeQuestion: resolvedQuestion,
-			splitMessageParts: !messageSlot
+			splitMessageParts: !messageSlot,
+			questionStates,
+			questionValues: questionValuesByKey,
+			streaming: resolvedStreaming,
+			error: hasErrorRow
 		});
 	});
 	const classes = $derived(useAIThreadTheme(theme));
 	const isSettlingInitialEnd = $derived(
 		renderItems.length > 0 && (!hasInitializedEnd || isInitializingEnd)
 	);
-	const shouldShowScrollButton = $derived(
-		showScrollButton &&
-			!isPinned &&
-			!isFollowingAppendedItem &&
-			!isSettlingInitialEnd &&
-			!isViewportAtEnd() &&
-			renderItems.length > 0
-	);
-
 	const virtualizerStore = createVirtualizer<HTMLDivElement, HTMLElement>(
 		untrack(() => ({
 			count: initialThreadCount(),
@@ -227,14 +229,52 @@
 			scrollToFn: scrollController.scrollToFn,
 			anchorTo: 'end',
 			followOnAppend: followOnAppendBehavior(),
-			scrollEndThreshold: Math.max(0, bottomThreshold),
+			scrollEndThreshold: endThreshold(),
 			initialOffset: initialThreadOffset,
+			measureElement: measureThreadItem,
 			onChange: handleVirtualizerChange
 		}))
 	);
 
 	const virtualItems = $derived($virtualizerStore.getVirtualItems());
 	const totalSize = $derived($virtualizerStore.getTotalSize());
+	// Read from reactive scroll state, not the DOM: a wheel, trackpad, key or scrollbar scroll
+	// updates `viewportScrollTop`, so the button appears as soon as the view leaves the end.
+	const distanceToEnd = $derived(Math.max(0, totalSize - viewportHeight - viewportScrollTop));
+	const shouldShowScrollButton = $derived(
+		showScrollButton &&
+			renderItems.length > 0 &&
+			!isFollowingAppendedItem &&
+			!isSettlingInitialEnd &&
+			distanceToEnd > SCROLL_BUTTON_THRESHOLD &&
+			(!isPinned || !followOutput)
+	);
+	const isPending = $derived(renderItems.at(-1)?.kind === 'pending');
+	const liveRegionText = $derived(
+		resolvedLiveText || (isPending ? t.aiReasoningThinking : undefined)
+	);
+	// The last turn, ignoring markers and system notices that may follow it (a context marker, a
+	// "model switched" notice): they do not end the turn.
+	const lastTurnMessage = $derived(
+		resolvedMessages.findLast(
+			(message) =>
+				message.type !== 'marker' && message.type !== 'context' && message.role !== 'system'
+		)
+	);
+	const shouldShowFollowUps = $derived(
+		showFollowUps &&
+			resolvedSuggestions.length > 0 &&
+			renderItems.length > 0 &&
+			!resolvedStreaming &&
+			!hasErrorRow &&
+			!resolvedQuestion &&
+			lastTurnMessage !== undefined &&
+			// After an assistant turn: its reply, or the tool calls that ended it.
+			lastTurnMessage.role !== 'user'
+	);
+	const followUpsInset = $derived(shouldShowFollowUps ? followUpsHeight : 0);
+	const listPaddingEnd = $derived(resolvedPaddingEnd + followUpsInset);
+
 	const tocState = $derived.by(() => {
 		const virtualizer = $virtualizerStore;
 		const effectiveScrollOffset = isPinned
@@ -257,7 +297,11 @@
 		});
 	});
 	const shouldRenderToc = $derived(
-		showToc && tocState.entries.length > 1 && viewportHeight > 0 && totalSize > viewportHeight + 1
+		showToc &&
+			tocState.entries.length > 1 &&
+			viewportHeight > 0 &&
+			viewportWidth >= TOC_MIN_VIEWPORT_WIDTH &&
+			totalSize > viewportHeight + 1
 	);
 
 	$effect(() => {
@@ -267,7 +311,7 @@
 	$effect(() => {
 		const currentViewport = viewport;
 		if (!currentViewport) return;
-		const sync = () => syncThreadPosition(get(virtualizerStore));
+		const sync = () => syncThreadPosition();
 		sync();
 		const observer = new ResizeObserver(sync);
 		observer.observe(currentViewport);
@@ -284,31 +328,23 @@
 					? 'end'
 					: undefined
 			: undefined;
-		shouldSmoothAppendedItem =
-			hasAddedItems &&
-			!hasPrependedItems &&
-			followOutput &&
-			scrollBehavior === 'smooth' &&
-			isViewportAtEnd();
-		if (shouldSmoothAppendedItem) isFollowingAppendedItem = true;
 	});
 
 	$effect(() => {
 		const count = renderItems.length;
 		const currentViewport = viewport;
-		scrollController.prepareSmoothAppendAdjustment(shouldSmoothAppendedItem);
 		get(virtualizerStore).setOptions({
 			count,
 			getScrollElement: () => currentViewport ?? null,
 			estimateSize: () => resolvedEstimateSize,
 			overscan: Math.max(0, overscan),
 			paddingStart: resolvedPaddingStart,
-			paddingEnd: resolvedPaddingEnd,
+			paddingEnd: listPaddingEnd,
 			getItemKey: renderItemKey,
 			scrollToFn: scrollController.scrollToFn,
 			anchorTo: 'end',
 			followOnAppend: followOnAppendBehavior(),
-			scrollEndThreshold: Math.max(0, bottomThreshold),
+			scrollEndThreshold: endThreshold(),
 			onChange: handleVirtualizerChange
 		});
 		if (prependScrollTarget) {
@@ -316,19 +352,13 @@
 			prependScrollTarget = undefined;
 			scrollController.settlePrependedItems(
 				target === 'start' ? scrollToStart : () => scrollToBottom('instant'),
-				() => syncThreadPosition(get(virtualizerStore))
+				() => syncThreadPosition()
 			);
 		}
 		previousRenderItemCount = count;
 		previousFirstRenderItemKey = renderItems[0]?.key;
-		if (shouldSmoothAppendedItem) {
-			scrollController.scheduleSmoothAppendAdjustmentReset();
-			scrollController.watchAppendFollowEnd(isViewportAtEnd, () => {
-				isFollowingAppendedItem = false;
-				syncThreadPosition(get(virtualizerStore));
-			});
-		}
 		if (count === 0) {
+			isPinned = true;
 			hasInitializedEnd = false;
 			isInitializingEnd = false;
 			isFollowingAppendedItem = false;
@@ -340,17 +370,67 @@
 			hasInitializedEnd = true;
 			scheduleInitialEndSettlement();
 		}
-		syncThreadPosition(get(virtualizerStore));
+		syncThreadPosition();
+		stickToEnd();
+	});
+
+	$effect(() => {
+		void isPinned;
+		untrack(applyFollowOptions);
 	});
 
 	onDestroy(() => {
 		cancelInitialEndSettlement();
+		if (stickFrame !== undefined) cancelAnimationFrame(stickFrame);
 		questionPublisher.destroy();
 		scrollController.destroy();
 	});
 
+	// The virtualizer re-measures rows from its ResizeObserver and re-renders the range in the same
+	// pass (a streamed row grows, the pinned view moves to the new end, rows enter and leave the
+	// overscan). A row that starts or stops being laid out while the browser is still delivering
+	// resize notifications cannot be delivered in that pass, and the browser reports a
+	// "ResizeObserver loop" error. Rows that mount during a delivery are measured and observed on the
+	// next frame, before the next delivery (their cached or estimated size holds until then), and a
+	// removed row stops being observed before the browser looks for further changes.
+	function measureThreadItem(
+		element: HTMLElement,
+		entry: ResizeObserverEntry | undefined,
+		instance: Parameters<typeof measureVirtualElement<HTMLElement>>[2]
+	): number {
+		if (entry && !isInResizeDelivery) {
+			isInResizeDelivery = true;
+			setTimeout(() => (isInResizeDelivery = false));
+		}
+		return measureVirtualElement(element, entry, instance);
+	}
+
+	let isReleasingItems = false;
+
+	function releaseRemovedItems(): void {
+		if (isReleasingItems) return;
+		isReleasingItems = true;
+		queueMicrotask(() => {
+			isReleasingItems = false;
+			// With no node, the virtualizer unobserves and forgets every disconnected row.
+			get(virtualizerStore).measureElement(null);
+		});
+	}
+
 	const measureItem: Attachment<HTMLElement> = (element) => {
-		get(virtualizerStore).measureElement(element);
+		let frame: number | undefined;
+		if (isInResizeDelivery) {
+			frame = requestAnimationFrame(() => {
+				frame = undefined;
+				if (element.isConnected) get(virtualizerStore).measureElement(element);
+			});
+		} else {
+			get(virtualizerStore).measureElement(element);
+		}
+		return () => {
+			if (frame !== undefined) cancelAnimationFrame(frame);
+			releaseRemovedItems();
+		};
 	};
 
 	function createMessageKeys(currentMessages: readonly TMessage[]): string[] {
@@ -384,7 +464,7 @@
 	function initialThreadOffset(): number {
 		return Math.max(
 			0,
-			resolvedPaddingStart + resolvedPaddingEnd + renderItems.length * resolvedEstimateSize
+			resolvedPaddingStart + listPaddingEnd + renderItems.length * resolvedEstimateSize
 		);
 	}
 
@@ -392,63 +472,222 @@
 		return renderItems.length;
 	}
 
+	// The virtualizer keeps the end in view by itself when an item is appended or re-measured
+	// (streaming text, rows mounting as they scroll in) within `scrollEndThreshold` of the end. That
+	// is only wanted while the thread follows: once the user scrolls up, it would pull every small
+	// scroll back down. Read untracked: the effect below applies a change of `isPinned`.
+	// Always instant: a new row is in place on its first painted frame, like streamed text. A smooth
+	// follow painted it below the fold first, which on a short row reads as a one-frame stutter;
+	// `scrollBehavior` stays for the navigation the reader asks for (TOC, scroll to latest).
 	function followOnAppendBehavior(): AIThreadScrollBehavior | false {
-		return followOutput ? scrollBehavior : false;
+		return followOutput && untrack(() => isPinned) ? 'instant' : false;
 	}
 
-	function handleVirtualizerChange(instance: EndStateVirtualizer): void {
-		syncThreadPosition(instance);
+	// Unpinned, no distance counts as the end (-1): a reader left exactly at the end by a layout
+	// change (a row shrinking under them) would otherwise be pulled down when that row grows again.
+	function endThreshold(): number {
+		return untrack(() => isPinned) ? Math.max(0, bottomThreshold) : -1;
+	}
+
+	let listElement = $state<HTMLDivElement | null>(null);
+
+	// Called from inside the virtualizer's measurement (a row's resize observer). When a row grows
+	// at the end it moves the offset to keep the end in view, but the list's height only follows a
+	// moment later through the template, so the browser clamps that move and the virtualizer retries
+	// it right after this callback. Sizing the list here, before the retry, lets it land before the
+	// frame is painted, instead of showing the new line below the fold for a frame.
+	function handleVirtualizerChange(instance: { getTotalSize: () => number }): void {
+		// Only while following: a reader who scrolled up keeps the template's pace, or the
+		// virtualizer's correction for a row growing across the fold would land in full and move them.
+		const following = isPinned && followOutput && !isInitializingEnd && !isFollowingAppendedItem;
+		if (following && viewport && listElement) {
+			listElement.style.height = `${instance.getTotalSize()}px`;
+			// With the list already at its new height, land on the end now rather than in
+			// `stickToEnd`'s next frame (a row growing at the end, the action bar mounting as a reply
+			// ends).
+			if (distanceFromEnd() > 1) viewport.scrollTop = viewport.scrollHeight;
+		}
+		syncThreadPosition();
 	}
 
-	function syncThreadPosition(instance: EndStateVirtualizer): void {
+	function syncThreadPosition(): void {
 		if (!viewport) return;
 		viewportHeight = viewport.clientHeight;
+		viewportWidth = viewport.clientWidth;
 		viewportScrollTop = viewport.scrollTop;
 		if (isInitializingEnd) {
 			isPinned = true;
 			return;
 		}
-		isPinned = isViewportAtEnd() || instance.isAtEnd(Math.max(0, bottomThreshold));
+		stickToEnd();
+	}
+
+	// Closes any gap between the viewport and the end while pinned. Deferred a frame so the spacer
+	// has taken the virtualizer's new total size, and coalesced because size changes arrive in bursts.
+	function stickToEnd(): void {
+		if (stickFrame !== undefined || !followOutput) return;
+		stickFrame = requestAnimationFrame(() => {
+			stickFrame = undefined;
+			if (!viewport || !isPinned || isInitializingEnd) return;
+			// A smooth follow or a smooth scroll-to-latest owns the viewport until it lands.
+			if (isFollowingAppendedItem || renderItems.length === 0) return;
+			if (distanceFromEnd() <= 1) return;
+			get(virtualizerStore).scrollToEnd({ behavior: 'instant' });
+			syncThreadPosition();
+		});
 	}
 
 	function isViewportAtStart(): boolean {
 		return !viewport || viewport.scrollTop <= 1;
 	}
 
-	function isViewportAtEnd(): boolean {
-		if (!viewport) return isPinned;
-		const distanceFromEnd = viewport.scrollHeight - viewport.clientHeight - viewport.scrollTop;
-		return Math.max(distanceFromEnd, 0) <= Math.max(0, bottomThreshold);
+	function distanceFromEnd(): number {
+		if (!viewport) return 0;
+		return Math.max(0, viewport.scrollHeight - viewport.clientHeight - viewport.scrollTop);
 	}
 
-	function handleScroll(event: UIEvent & { currentTarget: EventTarget & HTMLDivElement }): void {
-		syncThreadPosition(get(virtualizerStore));
-		onscroll?.(event);
+	function isViewportAtEnd(): boolean {
+		if (!viewport) return isPinned;
+		return distanceFromEnd() <= Math.max(0, bottomThreshold);
 	}
 
-	function handleWheel(): void {
+	function unpin(): void {
 		cancelInitialEndSettlement();
 		isInitializingEnd = false;
 		isFollowingAppendedItem = false;
 		isPinned = false;
+		// Now, not in the effect below: a row measured before that effect runs would otherwise still
+		// see the pinned end threshold and scroll a scroll that has only just started back down.
+		applyFollowOptions();
+		cancelProgrammaticScroll();
+	}
+
+	// The virtualizer keeps steering a scrollToEnd/scrollToIndex toward its target for up to 5s,
+	// until the offset holds for a frame, and re-scrolls whenever measurements move that target. It
+	// also remembers an end adjustment the browser clamped, and re-applies it once the list grows.
+	// On a busy page either can still be pending when the reader scrolls away, and would pull them
+	// back. The reader wins: drop both. Neither has a public cancel (and scrolling to the current
+	// offset would cut a smooth wheel or keyboard scroll short), so clear the fields they check.
+	function cancelProgrammaticScroll(): void {
+		const virtualizer = get(virtualizerStore) as unknown as {
+			scrollState?: unknown;
+			_clampedAdjustment?: unknown;
+		};
+		if (virtualizer.scrollState) virtualizer.scrollState = null;
+		if (virtualizer._clampedAdjustment) virtualizer._clampedAdjustment = null;
+	}
+
+	function applyFollowOptions(): void {
+		const virtualizer = get(virtualizerStore);
+		virtualizer.setOptions({
+			...virtualizer.options,
+			followOnAppend: followOnAppendBehavior(),
+			scrollEndThreshold: endThreshold()
+		});
+	}
+
+	function handleScroll(event: UIEvent & { currentTarget: EventTarget & HTMLDivElement }): void {
+		const scrollTop = event.currentTarget.scrollTop;
+		if (scrollTop < lastScrollTop - 0.5) {
+			// Only the reader moving up away from the end stops following. A wheel or a key already
+			// unpinned on its own event; here that leaves a drag (the scrollbar, a touch pan). Every other
+			// upward move is layout: the virtualizer keeping the end anchored as the viewport grows (the
+			// suggestions bar going away), or the browser clamping the offset onto the end (the composer
+			// coming back after a docked question). Those change nothing, so a following thread keeps
+			// following and a reader who scrolled up is not re-pinned.
+			if (isDragging && !isInitializingEnd && distanceFromEnd() >= 1) unpin();
+		}
+		// Only a scroll that reaches the very end follows output again. A layout change that happens
+		// to leave the view at the end (rows above it measured smaller) must not re-pin it, or the next
+		// growth pulls a reader who scrolled up back to the bottom.
+		else if (distanceFromEnd() < 1) isPinned = true;
+		lastScrollTop = scrollTop;
+		syncThreadPosition();
+		onscroll?.(event);
 	}
 
+	// A wheel up stops following before its scroll lands, so no output appended in between pulls the
+	// view back down.
+	function handleWheel(event: WheelEvent): void {
+		if (event.deltaY < 0) unpin();
+	}
+
+	// The keys that scroll the transcript up stop following on keydown, like a wheel: a smooth
+	// keyboard scroll lands over several frames, and output appended meanwhile must not undo it.
+	const scrollUpKeys = new Set(['PageUp', 'ArrowUp', 'Home']);
+	function handleViewportKeydown(event: KeyboardEvent): void {
+		if (event.target !== event.currentTarget || event.altKey || event.ctrlKey || event.metaKey)
+			return;
+		if (scrollUpKeys.has(event.key) || (event.key === ' ' && event.shiftKey)) unpin();
+	}
+
+	// When the viewport itself changes height while the thread follows the end (the suggestions bar
+	// appearing as a reply ends, a question docked in place of the composer), land on the end before
+	// the frame is painted. A resize observer runs after layout and before paint; the virtualizer's
+	// change callback would only stick a frame later, showing the end below the fold for a frame.
+	const keepEndOnResize: Attachment<HTMLDivElement> = (node) => {
+		if (typeof ResizeObserver === 'undefined') return;
+		let lastHeight = node.clientHeight;
+		const observer = new ResizeObserver(() => {
+			const height = node.clientHeight;
+			if (height === lastHeight) return;
+			lastHeight = height;
+			if (!isPinned || !followOutput || isInitializingEnd || isFollowingAppendedItem) return;
+			node.scrollTop = node.scrollHeight;
+			syncThreadPosition();
+		});
+		observer.observe(node);
+		return () => observer.disconnect();
+	};
+
+	// Tracks a drag on the transcript. Touch uses touch events: a touch pan cancels its pointer as
+	// soon as the browser takes it over, before the scroll events arrive.
+	const trackDrag: Attachment<HTMLDivElement> = (node) => {
+		const start = () => (isDragging = true);
+		const end = () => (isDragging = false);
+		const offs = [
+			on(node, 'pointerdown', (event) => {
+				if (event.pointerType !== 'touch') start();
+			}),
+			on(node, 'touchstart', start, { passive: true }),
+			on(window, 'pointerup', end),
+			on(window, 'pointercancel', (event) => {
+				if (event.pointerType !== 'touch') end();
+			}),
+			on(window, 'touchend', end),
+			on(window, 'touchcancel', end)
+		];
+		return () => {
+			for (const off of offs) off();
+			isDragging = false;
+		};
+	};
+
 	function handleRootWheel(
 		event: WheelEvent & { currentTarget: EventTarget & HTMLDivElement }
 	): void {
-		handleWheel();
+		handleWheel(event);
 		onWheel?.(event);
 	}
 
 	function scrollToStart(): void {
 		get(virtualizerStore).scrollToOffset(0, { behavior: 'instant' });
-		syncThreadPosition(get(virtualizerStore));
+		syncThreadPosition();
 	}
 
 	function scrollToBottom(behavior: AIThreadScrollBehavior = scrollBehavior): void {
 		if (renderItems.length === 0) return;
+		isPinned = true;
+		if (behavior === 'smooth') {
+			isFollowingAppendedItem = true;
+			scrollController.watchAppendFollowEnd(isViewportAtEnd, () => {
+				isFollowingAppendedItem = false;
+				syncThreadPosition();
+				stickToEnd();
+			});
+		}
 		get(virtualizerStore).scrollToEnd({ behavior });
-		syncThreadPosition(get(virtualizerStore));
+		syncThreadPosition();
 	}
 
 	function scheduleInitialEndSettlement(): void {
@@ -461,7 +700,7 @@
 				get(virtualizerStore).scrollToEnd({ behavior: 'instant' });
 				initialEndFrame = undefined;
 				isInitializingEnd = false;
-				syncThreadPosition(get(virtualizerStore));
+				syncThreadPosition();
 			});
 		});
 	}
@@ -473,6 +712,16 @@
 		initialEndFrame = undefined;
 	}
 
+	function resolveErrorRetry(): (() => void | Promise<void>) | undefined {
+		if (onErrorRetry) return onErrorRetry;
+		const current = conversation;
+		if (!current) return undefined;
+		return () => {
+			const index = current.messages.length - 1;
+			current.retry(index >= 0 ? { index } : undefined);
+		};
+	}
+
 	function handleSuggestionSelect(suggestion: string): void {
 		if (onSelect) {
 			onSelect(suggestion);
@@ -502,6 +751,7 @@
 	}): Promise<void> {
 		errorMessage = undefined;
 		questionStates = { ...questionStates, [request.key]: state };
+		if (detail) questionValuesByKey = { ...questionValuesByKey, [request.key]: detail.values };
 		const change = {
 			request,
 			state,
@@ -520,7 +770,7 @@
 			await conversation.resolveAskUserQuestion(state, change.detail, request);
 		} catch (error) {
 			questionStates = { ...questionStates, [request.key]: 'pending' };
-			errorMessage = getErrorMessage(error, 'Unable to resolve the question request.');
+			errorMessage = getErrorMessage(error, t.aiThreadQuestionFailed);
 		}
 	}
 
@@ -537,16 +787,17 @@
 	aria-busy={resolvedStreaming}
 	class={classes.root({ className })}
 	{...rootAttributes}
+	style:--ai-thread-content-width={resolvedContentWidth}
 	onwheel={handleRootWheel}
 >
-	{#if resolvedLiveText}
+	{#if liveRegionText}
 		<div data-slot="ai-thread-live-region" class="sr-only" aria-live="polite" aria-atomic="true">
-			{resolvedLiveText}
+			{liveRegionText}
 		</div>
 	{/if}
 	{#if header}<Slot render={header} class={classes.header()} />{/if}
 	{#if errorMessage}<Alert color="danger" variant="soft" description={errorMessage} />{/if}
-	<div class={classes.body()}>
+	<div class={classes.body()} style:--ai-thread-follow-ups-height={`${followUpsInset}px`}>
 		<!-- svelte-ignore a11y_no_noninteractive_tabindex -->
 		<div
 			bind:this={viewport}
@@ -557,17 +808,25 @@
 			tabindex="0"
 			aria-label={viewportLabel ?? t.aiThreadTranscript}
 			onscroll={handleScroll}
+			{@attach (node) => on(node, 'keydown', handleViewportKeydown)}
+			{@attach trackDrag}
+			{@attach keepEndOnResize}
 		>
 			<AIThreadItems
 				{renderItems}
 				{virtualItems}
 				{totalSize}
+				bind:listRef={listElement}
 				{measureItem}
 				density={resolvedDensity}
 				messageSize={resolvedMessageSize}
 				{messageVariant}
+				{messageColor}
 				suggestions={resolvedSuggestions}
 				onSelect={handleSuggestionSelect}
+				error={resolvedError}
+				{errorRetry}
+				liveText={resolvedLiveText}
 				{empty}
 				message={messageSlot}
 				{messageActions}
@@ -598,7 +857,13 @@
 				<Slot render={toc} payload={tocState} />
 			{:else}
 				<div class={classes.tocOverlay({ side: tocSide })}>
-					<AIThreadToc state={tocState} maxPins={tocMaxPins} side={tocSide} theme={tocTheme} />
+					<AIThreadToc
+						state={tocState}
+						maxPins={tocMaxPins}
+						showRange={tocShowRange}
+						side={tocSide}
+						theme={tocTheme}
+					/>
 				</div>
 			{/if}
 		{/if}
@@ -606,15 +871,33 @@
 		{#if shouldShowScrollButton}
 			<Button
 				squared
-				size="small"
-				variant="soft"
+				size="normal"
+				variant="outline"
 				label={t.aiThreadScrollToLatest}
+				data-slot="ai-thread-scroll-button"
 				class={classes.scrollButton({ position: scrollButtonPosition })}
 				onclick={() => scrollToBottom()}
 			>
 				{@render arrowDownIcon({ size: 16 })}
 			</Button>
 		{/if}
+		{#if shouldShowFollowUps}
+			<!-- The scroll row's viewport is the labelled group. -->
+			<div
+				data-slot="ai-thread-follow-ups"
+				class={classes.followUps({ density: resolvedDensity })}
+				bind:clientHeight={followUpsHeight}
+			>
+				<!-- One row that scrolls sideways (with a fade) rather than wrapping on a phone. -->
+				<div class={classes.followUpList()}>
+					<AISuggestions
+						suggestions={resolvedSuggestions}
+						label={t.aiThreadFollowUps}
+						onSelect={handleSuggestionSelect}
+					/>
+				</div>
+			</div>
+		{/if}
 	</div>
 	{#if renderAskUserQuestion && resolvedQuestion}
 		{@const question = resolvedQuestion}