entasis 0.10.2 → 0.12.0

package/dist/components/AIThread/AIThreadAskUserQuestion.svelte

@@ -55,6 +55,7 @@
 		nextLabel={request.nextLabel}
 		previousLabel={request.previousLabel}
 		discardLabel={request.discardLabel}
+		showOther={request.showOther}
 		onValueChange={(values) => onValuesChange({ request, values })}
 		onSubmit={(detail: AIAskUserQuestionSubmitPayload) =>
 			onResolve({ request, state: 'completed', detail })}

package/dist/components/AIThread/AIThreadItems.svelte

@@ -2,16 +2,22 @@
 	import { useI18n } from '../../i18n/context.svelte.js';
 	import type { VirtualItem } from '@tanstack/svelte-virtual';
 	import type { Attachment } from 'svelte/attachments';
+	import Alert from '../Alert/Alert.svelte';
+	import AIAskUserQuestionSummary from '../AIAskUserQuestion/AIAskUserQuestionSummary.svelte';
 	import { getAIConversation } from '../AIConversation/aiConversation.state.svelte.js';
-	import Empty from '../Empty/Empty.svelte';
 	import AIMessage from '../AIMessage/AIMessage.svelte';
-	import AISuggestions from '../AISuggestion/AISuggestions.svelte';
+	import AIMessageActions from '../AIMessageActions/AIMessageActions.svelte';
+	import type { AIMessageActionVisibility } from '../AIMessageActions/aiMessageActions.props.js';
+	import AIReasoning from '../AIReasoning/AIReasoning.svelte';
+	import AISuggestion from '../AISuggestion/AISuggestion.svelte';
+	import Button from '../Button/Button.svelte';
+	import { arrowsClockwiseIcon } from '../Icons/arrowsClockwise.js';
 	import Slot from '../Slot/Slot.svelte';
 	import AITool from '../AITool/AITool.svelte';
 	import AIThreadMarker from './AIThreadMarker.svelte';
 	import type { AIThreadItem, AIThreadProps, AIThreadRole } from './aiThread.props.js';
 	import { useAIThreadTheme } from './aiThread.theme.js';
-	import type { AIThreadRenderItem } from './threadRenderItems.js';
+	import type { AIThreadRenderItem, AIThreadUnitActions } from './threadRenderItems.js';
 
 	type MessageRenderItem<TMessage extends AIThreadItem> = Extract<
 		AIThreadRenderItem<TMessage>,
@@ -25,6 +31,7 @@
 		| 'density'
 		| 'messageSize'
 		| 'messageVariant'
+		| 'messageColor'
 		| 'empty'
 		| 'message'
 		| 'messageActions'
@@ -46,28 +53,35 @@
 		| 'marker'
 		| 'markerIcon'
 		| 'markerContent'
+		| 'liveText'
 		| 'theme'
 	> & {
 		renderItems: readonly AIThreadRenderItem<TMessage>[];
 		virtualItems: readonly VirtualItem[];
 		totalSize: number;
+		/** The element sized to `totalSize`, so the thread can resize it in step with the virtualizer. */
+		listRef?: HTMLDivElement | null;
 		measureItem: Attachment<HTMLElement>;
+		error?: unknown;
+		errorRetry?: () => void | Promise<void>;
 	};
 
 	let {
 		renderItems,
 		virtualItems,
 		totalSize,
+		listRef = $bindable(null),
 		measureItem,
 		suggestions = [],
 		onSelect,
 		density = 'normal',
 		messageSize = 'normal',
-		messageVariant = 'bubble',
+		messageVariant = 'minimal',
+		messageColor,
 		empty,
 		message: messageSlot,
 		messageActions,
-		messageActionsVisibility,
+		messageActionsVisibility = 'latest',
 		messageCopyable,
 		messageEditable,
 		messageRetryable,
@@ -85,18 +99,76 @@
 		marker: markerSlot,
 		markerIcon,
 		markerContent,
+		liveText,
+		error,
+		errorRetry,
 		theme
 	}: Props<TMessage> = $props();
+	// Tool calls and reasoning read one step below the message text (code blocks do the same), so
+	// they sit with the answer without competing with it; `small` messages are already at the floor.
+	const blockSize = $derived(messageSize === 'large' ? 'normal' : 'small');
 
 	const conversation = getAIConversation<TMessage>();
 	const classes = $derived(useAIThreadTheme(theme));
 	const t = $derived(useI18n());
-	const resolvedMessageActionsVisibility = $derived(messageActionsVisibility ?? 'always');
 
 	function messageRole(message: TMessage): AIThreadRole {
 		return message.role ?? 'assistant';
 	}
 
+	// The turn under the pointer. Its bar may sit on a row of its own, outside the hovered row, so
+	// hovering any row of the turn (reasoning, tools, text) reveals the turn's bar.
+	let hoveredUnit = $state<string>();
+
+	function enterUnit(event: PointerEvent, unit: string | undefined): void {
+		if (event.pointerType === 'touch') return;
+		hoveredUnit = unit;
+	}
+
+	function leaveUnit(unit: string | undefined): void {
+		if (hoveredUnit === unit) hoveredUnit = undefined;
+	}
+
+	// `latest` keeps the final assistant turn's bar visible and the rest on hover (always shown on
+	// touch screens by AIMessageActions' hover recipe). Segments that do not end their unit have no
+	// bar at all.
+	function unitVisibility(
+		actions: AIThreadUnitActions<TMessage> | false | undefined,
+		unit: string | undefined
+	): AIMessageActionVisibility {
+		if (actions === false) return 'none';
+		const visibility =
+			messageActionsVisibility !== 'latest'
+				? messageActionsVisibility
+				: actions?.latest
+					? 'always'
+					: 'hover';
+		return visibility === 'hover' && unit !== undefined && hoveredUnit === unit
+			? 'always'
+			: visibility;
+	}
+
+	// Whether a row ends with a built-in action bar. The bar keeps its layout space while it is
+	// hover-hidden, so that space already separates the turn from the next one.
+	function endsWithBar(item: AIThreadRenderItem<TMessage> | undefined): boolean {
+		if (!item || messageActions === false || messageActionsVisibility === 'none') return false;
+		if (item.kind === 'actions') return true;
+		return item.kind === 'message' && !messageSlot && Boolean(item.actions);
+	}
+
+	// The spacing rhythm: the first row of a turn adds the larger gap between turns, a turn's own
+	// action-bar row sits right under the row it closes, other rows keep the in-turn gap. After a
+	// turn that ends with a bar, the bar stands in for the larger gap (`afterBar`), so a hidden bar
+	// does not add its height on top of the turn gap.
+	function rowBoundary(index: number): 'part' | 'unit' | 'afterBar' | 'bar' {
+		const item = renderItems[index];
+		if (!item || index === 0) return 'part';
+		if (item.kind === 'actions') return 'bar';
+		const previous = renderItems[index - 1];
+		if (item.unit !== undefined && item.unit === previous?.unit) return 'part';
+		return endsWithBar(previous) ? 'afterBar' : 'unit';
+	}
+
 	function previousMessage(index: number): MessageRenderItem<TMessage> | undefined {
 		for (let previousIndex = index - 1; previousIndex >= 0; previousIndex -= 1) {
 			const item = renderItems[previousIndex];
@@ -117,90 +189,220 @@
 		}
 		return item.message.name;
 	}
+
+	function displayError(value: unknown): string {
+		if (value instanceof Error && value.message) return value.message;
+		if (typeof value === 'string' && value) return value;
+		return t.aiChatErrorDescription;
+	}
 </script>
 
-{#snippet suggestionContent()}
-	<AISuggestions {suggestions} {onSelect} class="mx-auto max-w-full" />
+{#snippet pendingLabel()}
+	<span data-slot="ai-thread-pending-label" class={classes.pending()}>
+		{liveText || t.aiReasoningThinking}
+	</span>
+{/snippet}
+
+{#snippet errorDescription()}
+	<span class={classes.errorBody()}>
+		<span>{displayError(error)}</span>
+		{#if errorRetry}
+			<Button
+				size="small"
+				variant="outline"
+				color="danger"
+				prefix={arrowsClockwiseIcon}
+				data-slot="ai-thread-error-retry"
+				onclick={() => void errorRetry?.()}>{t.aiThreadRetry}</Button
+			>
+		{/if}
+	</span>
 {/snippet}
 
 {#if renderItems.length === 0}
 	{#if empty}
 		<Slot render={empty} />
 	{:else}
-		<Empty
-			class="min-h-48"
-			title={t.aiThreadEmptyTitle}
-			description={t.aiThreadEmptyDescription}
-			content={suggestions.length > 0 ? suggestionContent : undefined}
-		/>
+		<div data-slot="ai-thread-empty" class={classes.empty()}>
+			<h2 data-slot="ai-thread-greeting" class={classes.greeting()}>{t.aiThreadGreeting}</h2>
+			{#if suggestions.length > 0}
+				<div
+					data-slot="ai-thread-empty-suggestions"
+					role="group"
+					aria-label={t.promptSuggestions}
+					class={classes.emptySuggestions()}
+				>
+					{#each suggestions as suggestion, index (`${suggestion}:${index}`)}
+						<AISuggestion {suggestion} onSelect={(value) => onSelect?.(value)} />
+					{/each}
+				</div>
+			{/if}
+		</div>
 	{/if}
 {:else}
-	<div class={classes.list()} style:height={`${totalSize}px`}>
+	<!-- Pointer tracking only reveals a turn's hover actions; the actions stay keyboard-reachable. -->
+	<!-- svelte-ignore a11y_no_static_element_interactions -->
+	<div
+		bind:this={listRef}
+		class={classes.list()}
+		style:height={`${totalSize}px`}
+		onpointerleave={() => (hoveredUnit = undefined)}
+	>
 		{#each virtualItems as virtualItem (virtualItem.key)}
 			{@const item = renderItems[virtualItem.index]}
 			{#if item}
+				<!-- svelte-ignore a11y_no_static_element_interactions -->
 				<div
 					data-slot="ai-thread-item"
 					data-index={virtualItem.index}
 					data-kind={item.kind}
-					class={classes.item({ density })}
+					class={classes.item({ density, boundary: rowBoundary(virtualItem.index) })}
 					style:transform={`translateY(${virtualItem.start}px)`}
+					onpointerenter={(event) => enterUnit(event, item.unit)}
+					onpointerleave={() => leaveUnit(item.unit)}
 					{@attach measureItem}
 				>
-					{#if item.kind === 'message'}
-						{#if messageSlot}
-							<Slot
-								render={messageSlot}
-								payload={{
-									message: item.message,
-									index: item.messageIndex,
-									actionsVisibility: resolvedMessageActionsVisibility
-								}}
+					<div data-slot="ai-thread-item-content" class={classes.content()}>
+						{#if item.kind === 'message'}
+							{@const visibility = unitVisibility(item.actions, item.unit)}
+							{#if messageSlot}
+								<Slot
+									render={messageSlot}
+									payload={{
+										message: item.message,
+										index: item.messageIndex,
+										actionsVisibility: visibility
+									}}
+								/>
+							{:else}
+								<AIMessage
+									message={item.message}
+									index={item.messageIndex}
+									class={classes.message()}
+									size={messageSize}
+									{density}
+									variant={messageVariant}
+									color={messageColor}
+									name={messageName(item, virtualItem.index)}
+									content={item.content ?? item.message.content ?? ''}
+									files={item.files ?? item.message.files}
+									streaming={item.streaming}
+									{conversation}
+									actions={item.actions === false ? false : messageActions}
+									actionVisibility={visibility}
+									copyAction={messageCopyable}
+									editAction={messageEditable}
+									retryAction={messageRetryable}
+									onCopy={onMessageCopy}
+									onEdit={onMessageEdit}
+									onRetry={onMessageRetry}
+								/>
+							{/if}
+						{:else if item.kind === 'marker'}
+							<AIThreadMarker
+								{item}
+								size={messageSize}
+								marker={markerSlot}
+								{markerIcon}
+								{markerContent}
+							/>
+						{:else if item.kind === 'tool-group'}
+							{#if toolSlot}
+								<Slot
+									render={toolSlot}
+									payload={{
+										tools: item.tools,
+										message: item.message,
+										index: item.messageIndex
+									}}
+								/>
+							{:else}
+								<AITool
+									tools={item.tools}
+									size={blockSize}
+									icon={toolIcon}
+									title={toolTitle}
+									content={toolContent}
+									input={toolInput}
+									output={toolOutput}
+									error={toolError}
+									status={toolStatus}
+								/>
+							{/if}
+						{:else if item.kind === 'reasoning'}
+							<AIReasoning content={item.content} streaming={item.streaming} size={blockSize} />
+						{:else if item.kind === 'question-summary'}
+							<AIAskUserQuestionSummary
+								size={messageSize}
+								questions={item.questions}
+								value={item.value}
+								title={item.title}
 							/>
-						{:else}
+						{:else if item.kind === 'sources'}
+							<div data-slot="ai-thread-sources" data-size={messageSize} class={classes.sources()}>
+								<span class={classes.sourcesLabel()}>{t.aiThreadSources}</span>
+								{#each item.sources as source (source.id)}
+									{#if source.url}
+										<!-- eslint-disable svelte/no-navigation-without-resolve -- Sources are external URLs from the model; library links cannot depend on SvelteKit routing. -->
+										<a
+											data-slot="ai-thread-source"
+											href={source.url}
+											target="_blank"
+											rel="noopener noreferrer"
+											title={source.url}
+											class={classes.source()}>{source.title}</a
+										>
+										<!-- eslint-enable svelte/no-navigation-without-resolve -->
+									{:else}
+										<span data-slot="ai-thread-source" class={classes.source()}>{source.title}</span
+										>
+									{/if}
+								{/each}
+							</div>
+						{:else if item.kind === 'actions'}
+							{@const visibility = unitVisibility(item.actions, item.unit)}
+							{#if messageActions !== false && visibility !== 'none'}
+								<AIMessageActions
+									message={item.actions.message}
+									messageIndex={item.actions.messageIndex}
+									role={item.actions.role}
+									content={item.actions.content}
+									size={messageSize}
+									{conversation}
+									actions={messageActions}
+									{visibility}
+									copyable={messageCopyable}
+									editable={messageEditable}
+									retryable={messageRetryable}
+									onCopy={onMessageCopy}
+									onEdit={onMessageEdit}
+									onRetry={onMessageRetry}
+									class={classes.actions()}
+								/>
+							{/if}
+						{:else if item.kind === 'pending'}
 							<AIMessage
-								message={item.message}
-								index={item.messageIndex}
+								from="assistant"
 								size={messageSize}
+								{density}
 								variant={messageVariant}
-								name={messageName(item, virtualItem.index)}
-								content={item.content ?? item.message.content ?? ''}
-								{conversation}
-								actions={messageActions}
-								actionVisibility={resolvedMessageActionsVisibility}
-								copyAction={messageCopyable}
-								editAction={messageEditable}
-								retryAction={messageRetryable}
-								onCopy={onMessageCopy}
-								onEdit={onMessageEdit}
-								onRetry={onMessageRetry}
-							/>
-						{/if}
-					{:else if item.kind === 'marker'}
-						<AIThreadMarker {item} marker={markerSlot} {markerIcon} {markerContent} />
-					{:else if item.kind === 'tool-group'}
-						{#if toolSlot}
-							<Slot
-								render={toolSlot}
-								payload={{
-									tools: item.tools,
-									message: item.message,
-									index: item.messageIndex
-								}}
-							/>
-						{:else}
-							<AITool
-								tools={item.tools}
-								icon={toolIcon}
-								title={toolTitle}
-								content={toolContent}
-								input={toolInput}
-								output={toolOutput}
-								error={toolError}
-								status={toolStatus}
+								actions={false}
+								class={classes.message()}
+								aria-hidden="true"
+								data-slot="ai-thread-pending"
+								children={pendingLabel}
 							/>
+						{:else if item.kind === 'error'}
+							<div data-slot="ai-thread-error" class={classes.error()}>
+								<Alert
+									color="danger"
+									variant="soft"
+									title={t.aiChatErrorTitle}
+									description={errorDescription}
+								/>
+							</div>
 						{/if}
-					{/if}
+					</div>
 				</div>
 			{/if}
 		{/each}

package/dist/components/AIThread/AIThreadItems.svelte.d.ts

@@ -2,16 +2,20 @@ import type { VirtualItem } from '@tanstack/svelte-virtual';
 import type { Attachment } from 'svelte/attachments';
 import type { AIThreadItem, AIThreadProps } from './aiThread.props.js';
 import type { AIThreadRenderItem } from './threadRenderItems.js';
-type Props<TMessage extends AIThreadItem> = Pick<AIThreadProps<TMessage>, 'suggestions' | 'onSelect' | 'density' | 'messageSize' | 'messageVariant' | 'empty' | 'message' | 'messageActions' | 'messageActionsVisibility' | 'messageCopyable' | 'messageEditable' | 'messageRetryable' | 'onMessageCopy' | 'onMessageEdit' | 'onMessageRetry' | 'tool' | 'toolIcon' | 'toolTitle' | 'toolContent' | 'toolInput' | 'toolOutput' | 'toolError' | 'toolStatus' | 'marker' | 'markerIcon' | 'markerContent' | 'theme'> & {
+type Props<TMessage extends AIThreadItem> = Pick<AIThreadProps<TMessage>, 'suggestions' | 'onSelect' | 'density' | 'messageSize' | 'messageVariant' | 'messageColor' | 'empty' | 'message' | 'messageActions' | 'messageActionsVisibility' | 'messageCopyable' | 'messageEditable' | 'messageRetryable' | 'onMessageCopy' | 'onMessageEdit' | 'onMessageRetry' | 'tool' | 'toolIcon' | 'toolTitle' | 'toolContent' | 'toolInput' | 'toolOutput' | 'toolError' | 'toolStatus' | 'marker' | 'markerIcon' | 'markerContent' | 'liveText' | 'theme'> & {
     renderItems: readonly AIThreadRenderItem<TMessage>[];
     virtualItems: readonly VirtualItem[];
     totalSize: number;
+    /** The element sized to `totalSize`, so the thread can resize it in step with the virtualizer. */
+    listRef?: HTMLDivElement | null;
     measureItem: Attachment<HTMLElement>;
+    error?: unknown;
+    errorRetry?: () => void | Promise<void>;
 };
 declare function $$render<TMessage extends AIThreadItem = AIThreadItem>(): {
     props: Props<TMessage>;
     exports: {};
-    bindings: "";
+    bindings: "listRef";
     slots: {};
     events: {};
 };
@@ -19,7 +23,7 @@ declare class __sveltets_Render<TMessage extends AIThreadItem = AIThreadItem> {
     props(): ReturnType<typeof $$render<TMessage>>['props'];
     events(): ReturnType<typeof $$render<TMessage>>['events'];
     slots(): ReturnType<typeof $$render<TMessage>>['slots'];
-    bindings(): "";
+    bindings(): "listRef";
     exports(): {};
 }
 interface $$IsomorphicComponent {

package/dist/components/AIThread/AIThreadMarker.svelte

@@ -6,11 +6,13 @@
 
 	let {
 		item,
+		size = 'normal',
 		marker,
 		markerIcon,
 		markerContent
 	}: {
 		item: Extract<AIThreadRenderItem<TMessage>, { kind: 'marker' }>;
+		size?: import('../../types/theme.js').Sizes;
 		marker?: import('../Slot/slot.js').Slot<AIThreadRenderPayload<TMessage>>;
 		markerIcon?: import('../Slot/slot.js').Slot<AIThreadRenderPayload<TMessage>>;
 		markerContent?: import('../Slot/slot.js').Slot<AIThreadRenderPayload<TMessage>>;
@@ -30,5 +32,10 @@
 {#if marker}
 	<Slot render={marker} {payload} />
 {:else}
-	<AIMarker variant={item.variant ?? 'separator'} icon={markerIcon ? icon : undefined} {content} />
+	<AIMarker
+		{size}
+		variant={item.variant ?? 'separator'}
+		icon={markerIcon ? icon : undefined}
+		{content}
+	/>
 {/if}

package/dist/components/AIThread/AIThreadMarker.svelte.d.ts

@@ -5,6 +5,7 @@ declare function $$render<TMessage extends AIThreadItem = AIThreadItem>(): {
         item: Extract<AIThreadRenderItem<TMessage>, {
             kind: "marker";
         }>;
+        size?: import("../../types/theme.js").Sizes;
         marker?: import("../Slot/slot.js").Slot<AIThreadRenderPayload<TMessage>>;
         markerIcon?: import("../Slot/slot.js").Slot<AIThreadRenderPayload<TMessage>>;
         markerContent?: import("../Slot/slot.js").Slot<AIThreadRenderPayload<TMessage>>;

package/dist/components/AIThread/aiThread.mcp.d.ts

@@ -1 +1 @@
-export declare const aiThreadDescription = "\n# AIThread\n\nVirtualized AI transcript with stable message keys, initial end anchoring, pinned append following, prepend preservation, message actions, AI SDK tool parts, ask-user-question flows, prompt suggestions, and the standalone AIThreadToc primitive.\n\n## Basic usage\n\n```svelte\n<script lang=\"ts\">\n  import { AIThread, type AIThreadItem } from './index.ts';\n\n  let messages: AIThreadItem[] = $state([]);\n  let announcement = $state('');\n</script>\n\n<AIThread\n  {messages}\n  getMessageKey={(message) => message.id}\n  liveText={announcement}\n  streaming={Boolean(announcement)}\n  showToc\n/>\n```\n\n`liveText` is announced through a polite, atomic, screen-reader-only region. It is not appended to the visual transcript and does not suppress the empty state.\n\n## Message input\n\n`AIThreadItem` accepts message, context/marker, tool-shaped, file, and attachment fields. The `parts` array supports:\n\n- `{ type: 'text', text }`\n- `{ type: 'marker', content, variant? }`\n- `{ type: 'tool', tool: AIToolCall }`\n- AI SDK `dynamic-tool` and `tool-*` parts with `toolCallId`, `state`, `input`, `output`, `structuredContent`, `result`, `error`, and `_meta`\n\nWhen text parts are present, top-level message content is not rendered again. Consecutive ordinary tools are grouped through `AITool`.\n\n## Core props\n\n- **messages**: readonly TMessage[] - Direct transcript. Falls back to the nearest AIConversation.\n- **getMessageKey**: (message, index) => string | number | bigint | undefined - Stable virtualization key. Prefer persistent identifiers.\n- **liveText**: string - Screen-reader announcement. Falls back to AIConversation.\n- **streaming**: boolean - Sets the busy state. Falls back to AIConversation.\n- **density**: 'compact' | 'normal' | 'comfortable' - Transcript row and edge spacing. Default 'normal'.\n- **messageSize**: 'small' | 'normal' | 'large' - Size forwarded to default AIMessage rows. Default 'normal'.\n- **messageVariant**: 'bubble' | 'minimal' - Presentation forwarded to default AIMessage rows. Default 'bubble'.\n- **followOutput**: boolean - Follow appended rows only while pinned. Default true.\n- **bottomThreshold**: number - End-pinned tolerance in pixels. Default 80.\n- **estimateSize**: number - Estimated row height. Defaults to 80, 96, or 120 from density.\n- **overscan**: number - Extra virtual rows. Default 4.\n- **padding**: number - Shared start/end virtual padding. Defaults to 8, 16, or 24 from density.\n- **paddingStart**, **paddingEnd**: number - Per-edge virtual padding overrides.\n- **scrollBehavior**: 'auto' | 'smooth' | 'instant' - Append, TOC, and scroll-button behavior. Default 'smooth'.\n- **showScrollButton**: boolean - Show the latest-message action away from the end. Default true.\n- **scrollButtonPosition**: 'left' | 'center' | 'right' - Default 'right'.\n- **ref**: HTMLDivElement - Bindable thread root, not the internal scroll viewport.\n- **class**: string - Thread-root classes.\n- **role**: HTML role - Thread-root role. Default 'log'.\n- **viewportLabel**: string - Label for the focusable transcript viewport.\n- **onscroll**: (event) => void - Raw native viewport-scroll callback.\n- Native div attributes and Svelte attachments are forwarded to the thread root.\n\n## Empty state and suggestions\n\n- **empty**: Slot - Replaces the empty state.\n- **suggestions**: readonly string[] - Default empty-state suggestions. Falls back to AIConversation.\n- **onSelect**: (suggestion) => void - Pick event for an empty-state suggestion; takes precedence over the provider's default `setInput` behavior.\n\n## Message composition\n\n- **message**: Slot<{ message, index, actionsVisibility }> - Replaces a complete message row. The\n  resolved action visibility keeps custom renderers aligned with the thread's latest-message rule.\n- **messageSize**, **messageVariant** - Configure only the default AIMessage renderer; a custom message slot owns its presentation.\n- **messageActions**: AIMessageActionSnippet | false - Replaces or disables default actions.\n- **messageActionsVisibility**: 'hover' | 'always' | 'none' (default: 'always')\n- **messageCopyable**, **messageEditable**, **messageRetryable**: boolean\n- **onMessageCopy**, **onMessageEdit**, **onMessageRetry**: AIMessage action handlers.\n\nAssistant text that continues through tool rows into another assistant segment does not render\nan action region. Actions belong to the terminal assistant segment for that user turn; completed\nhistorical turns retain hover actions.\n\n## Tool and marker composition\n\n- **tool**: Slot<{ tools, message, index }> - Replaces an ordinary grouped tool row.\n- **toolIcon**, **toolTitle**, **toolContent**, **toolInput**, **toolOutput**, **toolError**, **toolStatus** - Forwarded to the current AITool API.\n- **marker**: Slot<{ message, index }> - Replaces a complete context/marker row.\n- **markerIcon**, **markerContent** - Compose the default AIMarker.\n\n## Ask-user-question\n\nPending ask-user-question tools are auto-detected. Inside AIConversation, AIThread publishes a detected request only when no provider request is active and clears only the exact detected request it previously published; explicit provider requests retain precedence. Standalone AIThread renders the active question below the virtual viewport.\n\n- **activeAskUserQuestion**: request | null - Direct request takes precedence. Explicit null suppresses provider state and detection.\n- **renderAskUserQuestion**: boolean - Show and filter the active question tool. Default true.\n- **askUserQuestionDisabled**: boolean - Disable the question form.\n- **onAskUserQuestionStateChange**: async callback - Takes precedence over AIConversation resolution.\n\n## Minimap\n\n- **showToc**: boolean - Show the user-turn minimap when at least two user turns overflow the viewport.\n- **tocSide**: 'left' | 'right' - Default 'left'.\n- **tocMaxPins**: number - Maximum compacted pins.\n- **tocTheme**: AIThreadTocThemeProps - Theme overrides forwarded to the default standalone primitive.\n- **toc**: Slot<AIThreadTocState> - Replaces the minimap and receives entries, range, active index, visible offsets, `scrollToIndex`, and `scrollToOffset`.\n\n```svelte\n<script lang=\"ts\">\n  import { AIThread } from './index.ts';\n  import { AIThreadToc } from '../AIThreadToc/index.ts';\n</script>\n\n<AIThread {messages} showToc>\n  {#snippet toc(state)}\n    <AIThreadToc {state} side=\"left\" previewAlign=\"start\" />\n  {/snippet}\n</AIThread>\n```\n\nImport `AIThreadToc`, its controlled state types, and its dedicated theme from `entasis/ai-thread-toc`. AIThread composes that exact primitive for the default minimap.\n\n## Exports\n\nThe `entasis/ai-thread` entry exports `AIThread`, thread/message/part/question types, scroll behavior and button-position types, marker/tool/action types, and the AIThread theme helpers. It keeps an `AIThreadToc` re-export for composition compatibility; the dedicated primitive entry is `entasis/ai-thread-toc`.\n";
+export declare const aiThreadDescription = "\n# AIThread\n\nVirtualized AI transcript with stable message keys, initial end anchoring, pinned append following, prepend preservation, message actions, AI SDK tool parts, ask-user-question flows, prompt suggestions, and the standalone AIThreadToc primitive.\n\n## Basic usage\n\n```svelte\n<script lang=\"ts\">\n  import { AIThread, type AIThreadItem } from './index.ts';\n\n  let messages: AIThreadItem[] = $state([]);\n  let announcement = $state('');\n</script>\n\n<AIThread\n  {messages}\n  getMessageKey={(message) => message.id}\n  liveText={announcement}\n  streaming={Boolean(announcement)}\n  showToc\n/>\n```\n\n`liveText` is announced through a polite, atomic, screen-reader-only region and does not suppress the empty state. While `streaming` is true and the last item is a user turn, a pending assistant row shows `liveText` (or \"Thinking\u2026\") with the `shimmer` utility; the live region announces the same text. The segment that ends a streaming reply shows a pulsing caret.\n\n## Message input\n\n`AIThreadItem` accepts message, context/marker, tool-shaped, file, and attachment fields. The `parts` array supports:\n\n- `{ type: 'text', text }`\n- `{ type: 'marker', content, variant? }`\n- `{ type: 'tool', tool: AIToolCall }`\n- AI SDK `dynamic-tool` and `tool-*` parts with `toolCallId`, `state`, `input`, `output`, `structuredContent`, `result`, `error`, `approval`, and `_meta`. States map through `getAIToolStatusFromState`: `approval-requested`, `approval-responded` and `output-denied` become AITool's awaiting, approved and denied statuses, so a call waiting on the user never spins.\n- AI SDK `{ type: 'reasoning', text, state? }` - rendered with AIReasoning, streaming while `state` is `'streaming'` (or, without a state, while it is the last part of a streaming reply).\n- AI SDK `source-url` / `source-document` parts - one \"Sources\" row of chips per message; only http(s) URLs become links.\n- AI SDK `file` parts - shown as file previews with the message's text segment (or a segment of their own). Only https, blob and image data URLs are used as previews.\n- `step-start` and `data-*` parts carry no visible content and are skipped. An assistant message with nothing visible yet (only such parts, empty text, or the empty placeholder a client adds before the first token) is not rendered, so the pending row stays until real content arrives.\n\nWhen text parts are present, top-level message content is not rendered again. Consecutive ordinary tools are grouped through `AITool`. An ask-user-question tool that is answered (by the conversation, by the AI SDK output state, or locally through this thread) renders as a compact question \u2192 answer summary (`AIAskUserQuestionSummary`); a dismissed one settles as a cancelled call.\n\n## Core props\n\n- **messages**: readonly TMessage[] - Direct transcript. Falls back to the nearest AIConversation.\n- **getMessageKey**: (message, index) => string | number | bigint | undefined - Stable virtualization key. Prefer persistent identifiers.\n- **liveText**: string - Screen-reader announcement. Falls back to AIConversation.\n- **streaming**: boolean - Sets the busy state. Falls back to AIConversation.\n- **density**: 'compact' | 'normal' | 'comfortable' - Transcript row and edge spacing, and the spacing inside messages (table cells, code blocks, space between paragraphs and lists). Default 'normal'.\n- **messageSize**: 'small' | 'normal' | 'large' - Type scale of the whole transcript. Message text, tables, lists and quotes read at it; code blocks at 0.9\u00D7 of it; tool calls and reasoning one step below it (never under text-xs); sources, markers and answered-question summaries follow it too. Default 'normal'.\n- **messageVariant**: 'minimal' | 'bubble' - Presentation forwarded to default AIMessage rows. Default 'minimal' (flat full-width assistant prose).\n- **messageColor**: Colors - User-bubble colour forwarded to default AIMessage rows. Neutral (the theme default) is a quiet grey bubble; any other role paints a solid bubble.\n- **contentWidth**: string | number - Maximum width of the centred reading column (a CSS length, or pixels). Sets `--ai-thread-content-width`; without it rows follow an ancestor's `--ai-chat-content-width` (AIChat sets 48rem) and otherwise span the thread.\n- **followOutput**: boolean - Follow appended rows only while pinned. Default true.\n- **bottomThreshold**: number - End-pinned tolerance in pixels. Default 80.\n- **estimateSize**: number - Estimated row height. Defaults to 80, 96, or 120 from density.\n- **overscan**: number - Extra virtual rows. Default 4.\n- **padding**: number - Shared start/end virtual padding. Defaults to 8, 16, or 24 from density.\n- **paddingStart**, **paddingEnd**: number - Per-edge virtual padding overrides. Message actions sit inside their row, so the end padding reserves no extra room for them.\n- **scrollBehavior**: 'auto' | 'smooth' | 'instant' - TOC and scroll-to-latest behavior. Default 'smooth'. Following output (an appended row, streamed text, a docked question resizing the thread) is always instant, so new content is in place on its first painted frame.\n- **showScrollButton**: boolean - Show the round scroll-to-latest button as soon as the view leaves the end (by wheel, trackpad, keys or scrollbar). Default true.\n- **scrollButtonPosition**: 'left' | 'center' | 'right' - Default 'center', just above whatever sits below the thread.\n- **ref**: HTMLDivElement - Bindable thread root, not the internal scroll viewport.\n- **class**: string - Thread-root classes.\n- **role**: HTML role - Thread-root role. Default 'log'.\n- **viewportLabel**: string - Label for the focusable transcript viewport.\n- **onscroll**: (event) => void - Raw native viewport-scroll callback.\n- Native div attributes and Svelte attachments are forwarded to the thread root.\n\n## Empty state, suggestions and errors\n\n- **empty**: Slot - Replaces the empty state, a vertically centred greeting (\"How can I help you today?\") with wrapping suggestion chips.\n- **suggestions**: readonly string[] - Empty-state chips, then follow-ups below the transcript after a finished assistant turn (not while streaming, during a question or under an error). Follow-ups are one row that scrolls sideways with an edge fade instead of wrapping. Falls back to AIConversation.\n- **showFollowUps**: boolean - Show the follow-ups. Default true.\n- **onSelect**: (suggestion) => void - Pick event for a suggestion or follow-up; takes precedence over the provider's default `setInput` behavior.\n- **error**: unknown - Shown as a danger row at the end of the transcript, where the reply failed. Falls back to AIConversation. An empty transcript shows the error instead of the greeting.\n- **showError**: boolean - Show that row. Default true.\n- **onErrorRetry**: () => void - The row's Retry button. Defaults to the conversation's `retry` targeting the last message; without either, there is no Retry button.\n\n## Message composition\n\n- **message**: Slot<{ message, index, actionsVisibility }> - Replaces a complete message row. The\n  resolved action visibility keeps custom renderers aligned with the thread's latest-message rule.\n- **messageVariant** configures only the default AIMessage renderer, and a custom message slot owns its presentation. **messageSize** also sizes the built-in reasoning, tool, source, marker and summary rows.\n- **messageActions**: AIMessageActionSnippet | false - Replaces or disables default actions.\n- **messageActionsVisibility**: 'latest' | 'hover' | 'always' | 'none' (default: 'latest'). `latest` keeps the final assistant turn's bar visible and reveals the rest on hover or focus; hovering any row of a turn (its reasoning, tools or text) reveals that turn's bar, and hover-revealed bars always show on touch screens. Hidden bars keep their height, so no row draws under them. A system notice or marker after the last reply does not make it lose its `latest` bar or hide the follow-ups.\n- **messageCopyable**, **messageEditable**, **messageRetryable**: boolean\n- **onMessageCopy**, **onMessageEdit**, **onMessageRetry**: AIMessage action handlers.\n\nA turn is one unit. A user message has its own bar; an assistant turn \u2014 reasoning, tools, and text\nup to the next user message or marker \u2014 has a single bar at its end. When the turn ends with its\nonly text segment the bar sits under that text; otherwise it gets a row of its own whose copy takes\nthe whole turn's text and whose retry targets the turn's last assistant message. The bar of a\nreply that is still streaming appears when it ends. The message slot's `actionsVisibility` is\n`none` for segments that do not end their unit. Rows of one turn are spaced by one gap; a larger\nfixed gap separates turns, and the action bar sits right under the row it closes.\n\n## Tool and marker composition\n\n- **tool**: Slot<{ tools, message, index }> - Replaces an ordinary grouped tool row.\n- **toolIcon**, **toolTitle**, **toolContent**, **toolInput**, **toolOutput**, **toolError**, **toolStatus** - Forwarded to the current AITool API.\n- **marker**: Slot<{ message, index }> - Replaces a complete context/marker row.\n- **markerIcon**, **markerContent** - Compose the default AIMarker.\n\n## Ask-user-question\n\nPending ask-user-question tools are auto-detected. Inside AIConversation, AIThread publishes a detected request only when no provider request is active and clears only the exact detected request it previously published; explicit provider requests retain precedence. Standalone AIThread renders the active question below the virtual viewport.\n\n- **activeAskUserQuestion**: request | null - Direct request takes precedence. Explicit null suppresses provider state and detection.\n- **renderAskUserQuestion**: boolean - Show and filter the active question tool. Default true.\n- **askUserQuestionDisabled**: boolean - Disable the question form.\n- **onAskUserQuestionStateChange**: async callback - Takes precedence over AIConversation resolution.\n\n## Minimap\n\n- **showToc**: boolean - Show the user-turn minimap when at least two user turns overflow the viewport. Below a 480px-wide viewport the minimap and its gutter step aside.\n- **tocSide**: 'left' | 'right' - Default 'left'.\n- **tocMaxPins**: number - Maximum compacted pins.\n- **tocTheme**: AIThreadTocThemeProps - Theme overrides forwarded to the default standalone primitive.\n- **toc**: Slot<AIThreadTocState> - Replaces the minimap and receives entries, range, active index, visible offsets, `scrollToIndex`, and `scrollToOffset`.\n\n```svelte\n<script lang=\"ts\">\n  import { AIThread } from './index.ts';\n  import { AIThreadToc } from '../AIThreadToc/index.ts';\n</script>\n\n<AIThread {messages} showToc>\n  {#snippet toc(state)}\n    <AIThreadToc {state} side=\"left\" previewAlign=\"start\" />\n  {/snippet}\n</AIThread>\n```\n\nImport `AIThreadToc`, its controlled state types, and its dedicated theme from `entasis/ai-thread-toc`. AIThread composes that exact primitive for the default minimap.\n\n## Exports\n\nThe `entasis/ai-thread` entry exports `AIThread`, thread/message/part/question types, scroll behavior and button-position types, marker/tool/action types, and the AIThread theme helpers. It keeps an `AIThreadToc` re-export for composition compatibility; the dedicated primitive entry is `entasis/ai-thread-toc`.\n";