entasis 0.11.0 → 0.12.0

package/dist/components/AIComposer/AIComposer.svelte

@@ -10,6 +10,8 @@
 	} from '../RichTextInput/richTextInput.props.js';
 	import { toRichTextInputToken } from '../RichTextInput/suggestions.js';
 	import Alert from '../Alert/Alert.svelte';
+	import Button from '../Button/Button.svelte';
+	import { xIcon } from '../Icons/x.js';
 	import { getAIConversation } from '../AIConversation/aiConversation.state.svelte.js';
 	import { uploadSimpleIcon } from '../Icons/uploadSimple.js';
 	import Slot from '../Slot/Slot.svelte';
@@ -59,8 +61,8 @@
 		mentions,
 		references,
 		skills,
-		submitShortcut = 'none',
-		toolbar = 'hover',
+		submitShortcut = 'enter',
+		toolbar = 'none',
 		formats,
 		autoresize = true,
 		voiceInput = false,
@@ -115,6 +117,7 @@
 		class: className,
 		theme,
 		voiceInputTheme,
+		onkeydown,
 		...formAttachments
 	}: AIComposerProps = $props();
 	const valueState = createBindableValue<string | undefined>(
@@ -123,6 +126,7 @@
 		() => defaultValue
 	);
 
+	const NOTICE_DURATION = 6000;
 	const conversation = getAIConversation<AIThreadItem>();
 	const t = $derived(useI18n());
 	let editorHandle = $state<RichTextInputHandle>();
@@ -196,7 +200,10 @@
 		onFileReject,
 		onAttachmentAdd,
 		onAttachmentRetry,
-		onAttachmentRemove
+		onAttachmentRemove,
+		get messages() {
+			return t;
+		}
 	}));
 	const fileDropzoneController = fileController.dropzone;
 	const displayFiles: File[] = $derived(fileController.files);
@@ -238,6 +245,13 @@
 		conversation,
 		buildMeta: buildSubmitMeta,
 		clearDraft,
+		hasFocus: (event) =>
+			Boolean(
+				ref?.contains(document.activeElement) ||
+				(event && 'submitter' in event && ref?.contains(event.submitter))
+			),
+		restoreFocus: restoreEditorFocus,
+		messages: { submitFailed: t.aiComposerSubmitFailed, stopFailed: t.aiComposerStopFailed },
 		onSubmit,
 		onStop
 	}));
@@ -261,14 +275,46 @@
 		queueController.syncConversation(resolvedQueue);
 	});
 
+	// A rejected-file note is information, not a blocking error: it dismisses itself. Each new
+	// rejection (even one with the same text) bumps `noticeId` and restarts the timer.
+	$effect(() => {
+		void fileController.noticeId;
+		if (!fileController.notice) return;
+		const timeout = setTimeout(() => fileController.dismissNotice(), NOTICE_DURATION);
+		return () => clearTimeout(timeout);
+	});
+
+	/**
+	 * Focuses the editor with the caret at the end. A parent that has just changed the value (a
+	 * suggestion filling the shared input) has not reached the editor yet: Lexical would load that
+	 * text after this call and skip writing the selection, so focus again once it has loaded.
+	 */
 	export function focus(): void {
 		editorHandle?.focus();
+		void tick().then(() => editorHandle?.focus());
 	}
 
 	export function clear(): void {
 		clearEditor();
 	}
 
+	/**
+	 * Sends the current draft, or `text` in place of it, through the same path as Enter or the send
+	 * button (queueing while busy), then returns focus to the editor.
+	 */
+	export async function submit(text?: string): Promise<void> {
+		if (text !== undefined) {
+			tokens = [];
+			submitMetadata.clear();
+			editorValue = text;
+			setValue(text);
+			await tick();
+		}
+		await submitController.submit();
+		await tick();
+		editorHandle?.focus();
+	}
+
 	export function insertText(text: string): void {
 		editorHandle?.insertText(text);
 	}
@@ -368,6 +414,29 @@
 		void tick().then(() => editorHandle?.focus());
 	}
 
+	// Sending, queueing and leaving a queued edit clear the editor or unmount the control that was
+	// used; keep focus in the composer unless it already moved somewhere else on the page.
+	function restoreEditorFocus(): void {
+		void tick().then(() => {
+			const active = document.activeElement;
+			if (active && active !== document.body && !ref?.contains(active)) return;
+			editorHandle?.focus();
+		});
+	}
+
+	function handleKeydown(event: KeyboardEvent & { currentTarget: HTMLFormElement }): void {
+		onkeydown?.(event);
+		// The editor and its suggestion popup handle Escape first and mark it handled.
+		if (event.defaultPrevented || event.key !== 'Escape' || !queueController.isEditing) return;
+		event.preventDefault();
+		cancelQueuedEdit();
+	}
+
+	function cancelQueuedEdit(): void {
+		queueController.cancelEdit();
+		restoreEditorFocus();
+	}
+
 	function clearDraft(): void {
 		clearEditor();
 		fileController.clear();
@@ -389,6 +458,7 @@
 	data-file-drag-state={fileDropzoneController.isActive ? fileDropzoneController.state : undefined}
 	class={classes.root({ className, dragState: fileDropzoneController.state })}
 	onsubmit={submitController.submit}
+	onkeydown={handleKeydown}
 	onpaste={(event) => fileController.handlePaste(event)}
 	{@attach fileDropzoneController.zone}
 	{...formAttachments}
@@ -437,7 +507,7 @@
 		onSteer={(messageId) => queueController.steer(messageId)}
 		onEdit={(messageId) => queueController.startEdit(messageId)}
 		onCancel={(messageId) => queueController.cancel(messageId)}
-		onCancelEdit={() => queueController.cancelEdit()}
+		onCancelEdit={cancelQueuedEdit}
 		{theme}
 	/>
 
@@ -461,7 +531,7 @@
 		{autoresize}
 		triggers={resolvedSources.triggers}
 		placeholder={resolvedPlaceholder}
-		disabled={disabled || isWorking}
+		disabled={disabled || submitController.isSubmitting}
 		{submitShortcut}
 		{prefix}
 		{suffix}
@@ -478,6 +548,31 @@
 		<Alert color="danger" variant="soft" description={visibleError} class={classes.error()} />
 	{/if}
 
+	<!-- The status region stays mounted (visually hidden while empty) and only its text changes, so
+	     screen readers announce each note; re-keying the text re-announces a repeated rejection. -->
+	<div
+		data-slot="ai-composer-notice"
+		data-empty={fileController.notice ? undefined : 'true'}
+		class={classes.notice({ empty: !fileController.notice })}
+	>
+		<span role="status" class="min-w-0">
+			{#key fileController.noticeId}{fileController.notice ?? ''}{/key}
+		</span>
+		{#if fileController.notice}
+			<Button
+				type="button"
+				squared
+				size="small"
+				variant="ghost"
+				color="neutral"
+				label={t.close}
+				onclick={() => fileController.dismissNotice()}
+			>
+				{@render xIcon({ size: 14 })}
+			</Button>
+		{/if}
+	</div>
+
 	<AIComposerFooter
 		state={submitState}
 		{footer}
@@ -492,6 +587,7 @@
 		voiceInputAriaLabel={voiceInputAriaLabel ?? t.voiceInputStart}
 		voiceInputStopLabel={voiceInputStopLabel ?? t.voiceInputStop}
 		voiceInputProcessingLabel={voiceInputProcessingLabel ?? t.voiceInputProcessing}
+		voiceInputFailedLabel={t.aiComposerVoiceFailed}
 		{onVoiceInput}
 		{fileDropzone}
 		attachDisabled={disabled || isWorking || displayFiles.length >= resolvedMaxFiles}
@@ -503,6 +599,7 @@
 		{queueWhileBusy}
 		submitLabel={resolvedSubmitLabel}
 		stopLabel={resolvedStopLabel}
+		queueLabel={t.aiComposerQueue}
 		attachLabel={resolvedAttachLabel}
 		onAttach={() => fileDropzoneController.open()}
 		onStop={submitController.stop}

package/dist/components/AIComposer/AIComposer.svelte.d.ts

@@ -3,6 +3,7 @@ import type { AIComposerCommand, AIComposerMentionItem, AIComposerProps, AICompo
 declare const AIComposer: import("svelte").Component<AIComposerProps, {
     focus: () => void;
     clear: () => void;
+    submit: (text?: string) => Promise<void>;
     insertText: (text: string) => void;
     insertItem: (trigger: string, item: RichTextInputItem) => void;
     insertToken: (token: RichTextInputToken) => void;

package/dist/components/AIComposer/AIComposerFooter.svelte

@@ -1,11 +1,13 @@
 <script lang="ts">
+	import { MediaQuery } from 'svelte/reactivity';
 	import Button from '../Button/Button.svelte';
 	import VoiceInput from '../Form/VoiceInput/VoiceInput.svelte';
 	import type { VoiceInputResult } from '../Form/VoiceInput/voiceInput.props.js';
 	import type { VoiceInputThemeProps } from '../Form/VoiceInput/voiceInput.theme.js';
+	import { listPlusIcon } from '../Icons/listPlus.js';
 	import { paperPlaneRightIcon } from '../Icons/paperPlaneRight.js';
 	import { paperclipIcon } from '../Icons/paperclip.js';
-	import { stopIcon } from '../Icons/stop.js';
+	import { stopIconFill } from '../Icons/stop.js';
 	import Slot from '../Slot/Slot.svelte';
 	import type { Slot as SlotType } from '../Slot/slot.js';
 	import type { Colors } from '../../types/theme.js';
@@ -26,6 +28,7 @@
 		voiceInputAriaLabel,
 		voiceInputStopLabel,
 		voiceInputProcessingLabel,
+		voiceInputFailedLabel,
 		onVoiceInput,
 		fileDropzone,
 		attachDisabled,
@@ -37,6 +40,7 @@
 		queueWhileBusy,
 		submitLabel,
 		stopLabel,
+		queueLabel,
 		attachLabel,
 		onAttach,
 		onStop,
@@ -56,6 +60,7 @@
 		voiceInputAriaLabel: string;
 		voiceInputStopLabel: string;
 		voiceInputProcessingLabel: string;
+		voiceInputFailedLabel: string;
 		onVoiceInput?: (audioBuffer: ArrayBuffer) => Promise<void>;
 		fileDropzone: boolean;
 		attachDisabled: boolean;
@@ -67,6 +72,7 @@
 		queueWhileBusy: boolean;
 		submitLabel: string;
 		stopLabel: string;
+		queueLabel: string;
 		attachLabel: string;
 		onAttach: () => void;
 		onStop: () => void;
@@ -80,6 +86,22 @@
 	let voiceInputErrors = $state<string[]>([]);
 	let isVoiceInputProcessing = $state(false);
 
+	// The footer's other controls grow to 36px through the theme's `@max-md` container query and
+	// `pointer-coarse`; VoiceInput sizes its mic, playback and clear buttons from its `size` prop, so
+	// the same two conditions pick its 36px `normal` size here. 28rem is Tailwind's `@md` container.
+	const coarsePointer = new MediaQuery('(pointer: coarse)', false);
+	let narrowFooter = $state(false);
+	const touchControls = $derived(narrowFooter || coarsePointer.current);
+
+	function observeFooterWidth(node: HTMLElement) {
+		const observer = new ResizeObserver(([entry]) => {
+			const rem = parseFloat(getComputedStyle(document.documentElement).fontSize) || 16;
+			narrowFooter = entry.contentRect.width < 28 * rem;
+		});
+		observer.observe(node);
+		return () => observer.disconnect();
+	}
+
 	async function processVoiceInput(result: VoiceInputResult): Promise<void> {
 		voiceInputValue = null;
 		voiceInputDuration = 0;
@@ -90,9 +112,7 @@
 		try {
 			await onVoiceInput(await result.blob.arrayBuffer());
 		} catch (cause) {
-			voiceInputErrors = [
-				cause instanceof Error ? cause.message : 'Voice input processing failed.'
-			];
+			voiceInputErrors = [cause instanceof Error ? cause.message : voiceInputFailedLabel];
 		} finally {
 			isVoiceInputProcessing = false;
 		}
@@ -102,9 +122,14 @@
 {#if footer}
 	<Slot render={footer} payload={submitState} class={classes.footer()} />
 {:else}
-	<div data-slot="ai-composer-footer" class={classes.footer()}>
+	<!-- Attach sits at the far start; the model picker, voice and the send position share the end,
+	     so the send/stop control is always last and never pushed out of the composer. -->
+	<div
+		data-slot="ai-composer-footer"
+		class={classes.footer()}
+		{@attach voiceInput ? observeFooterWidth : undefined}
+	>
 		<div class={classes.actions({ side: 'start' })}>
-			<Slot render={footerStart} payload={submitState} />
 			{#if fileDropzone}
 				<Button
 					type="button"
@@ -119,10 +144,11 @@
 					{@render paperclipIcon({ size: 16 })}
 				</Button>
 			{/if}
-			<Slot render={modelSelector} />
+			<Slot render={footerStart} payload={submitState} />
 		</div>
 		<div class={classes.actions({ side: 'end' })}>
 			<Slot render={actions} payload={submitState} />
+			<Slot render={modelSelector} />
 			{#if voiceInput}
 				<div
 					data-slot="ai-composer-voice-input"
@@ -132,7 +158,7 @@
 						<Button
 							type="button"
 							squared
-							size="small"
+							size={touchControls ? 'large' : 'small'}
 							variant="ghost"
 							color="neutral"
 							label={voiceInputProcessingLabel}
@@ -140,16 +166,17 @@
 							disabled
 						/>
 					{:else}
+						<!-- startLabel names the mic button; no Field label, so nothing renders above it. -->
 						<VoiceInput
 							bind:value={voiceInputValue}
 							bind:duration={voiceInputDuration}
 							bind:errors={voiceInputErrors}
-							size="small"
+							size={touchControls ? 'normal' : 'small'}
 							variant={voiceInputVariant}
 							minDuration={voiceInputMinDuration}
 							maxDuration={voiceInputMaxDuration}
 							color={voiceInputColor}
-							label={voiceInputAriaLabel}
+							startLabel={voiceInputAriaLabel}
 							stopLabel={voiceInputStopLabel}
 							disabled={disabled || isWorking}
 							onStop={processVoiceInput}
@@ -159,23 +186,38 @@
 				</div>
 			{/if}
 			{#if submitState.isBusy && !isEditing}
+				{#if queueWhileBusy && !submitState.isEmpty}
+					<Button
+						type="submit"
+						squared
+						size="small"
+						variant="ghost"
+						color="neutral"
+						data-slot="ai-composer-queue-action"
+						label={queueLabel}
+						disabled={disabled || isWorking}
+					>
+						{@render listPlusIcon({ size: 16 })}
+					</Button>
+				{/if}
 				<Button
 					type="button"
 					squared
 					size="small"
-					variant="soft"
+					data-slot="ai-composer-stop"
 					label={stopLabel}
 					loading={isStopping}
 					disabled={disabled || isWorking}
 					onclick={onStop}
 				>
-					{@render stopIcon({ size: 16 })}
+					{@render stopIconFill({ size: 14 })}
 				</Button>
 			{:else}
 				<Button
 					type="submit"
 					squared
 					size="small"
+					data-slot="ai-composer-submit"
 					label={submitLabel}
 					loading={isSubmitting}
 					disabled={disabled ||

package/dist/components/AIComposer/AIComposerFooter.svelte.d.ts

@@ -17,6 +17,7 @@ type $$ComponentProps = {
     voiceInputAriaLabel: string;
     voiceInputStopLabel: string;
     voiceInputProcessingLabel: string;
+    voiceInputFailedLabel: string;
     onVoiceInput?: (audioBuffer: ArrayBuffer) => Promise<void>;
     fileDropzone: boolean;
     attachDisabled: boolean;
@@ -28,6 +29,7 @@ type $$ComponentProps = {
     queueWhileBusy: boolean;
     submitLabel: string;
     stopLabel: string;
+    queueLabel: string;
     attachLabel: string;
     onAttach: () => void;
     onStop: () => void;

package/dist/components/AIComposer/AIComposerQueue.svelte

@@ -76,13 +76,18 @@
 				{#snippet item({ item }: SortableListItemPayload<AIComposerQueuedMessage>)}
 					<div
 						data-slot="ai-composer-queue-item"
-						class={classes.queueItem()}
+						class={classes.queueItem({ steered: Boolean(item.steered) })}
 						data-steered={item.steered || undefined}
 					>
+						{#if item.steered}
+							<span data-slot="ai-composer-queue-badge" class={classes.queueBadge()}>
+								{t.aiComposerSteering}
+							</span>
+						{/if}
 						<div class={classes.queueText()}>{getMessagePreview(item)}</div>
 						{#if item.attachments.length > 0}
-							<span class="text-neutral/50 text-xs">
-								{item.attachments.length} file{item.attachments.length === 1 ? '' : 's'}
+							<span data-slot="ai-composer-queue-files" class={classes.queueFiles()}>
+								{t.aiComposerQueuedFiles(item.attachments.length)}
 							</span>
 						{/if}
 						<Button

package/dist/components/AIComposer/aiComposer.editor.theme.js

@@ -1,6 +1,17 @@
+// Composer chrome around the editor. Inline tokens carry `data-ai-token="<kind>"`, so each kind
+// gets its own tint here without reaching into the editor's token node: commands read as
+// actions (primary), mentions as people (info), skills as tools (success); files and references
+// keep the neutral pill. On a narrow composer or a touch screen the text steps up to 16px, which
+// also stops iOS Safari from zooming the page when the editor takes focus.
+const touchText = '@max-md:text-base pointer-coarse:text-base';
+const tokenTints = [
+    '[&_[data-ai-token=command]]:border-primary-muted [&_[data-ai-token=command]]:bg-primary-muted [&_[data-ai-token=command]]:text-primary-muted-readable',
+    '[&_[data-ai-token=mention]]:border-info-muted [&_[data-ai-token=mention]]:bg-info-muted [&_[data-ai-token=mention]]:text-info-muted-readable',
+    '[&_[data-ai-token=skill]]:border-success-muted [&_[data-ai-token=skill]]:bg-success-muted [&_[data-ai-token=skill]]:text-success-muted-readable'
+].join(' ');
 export const aiComposerEditorTheme = {
     scrollArea: { base: '!min-h-0' },
     editorShell: { base: 'px-sm py-0' },
-    editor: { base: '!min-h-row-md' },
-    placeholder: { base: 'left-2 top-0' }
+    editor: { base: `!min-h-row-md ${touchText} ${tokenTints}` },
+    placeholder: { base: `left-2 top-0 ${touchText}` }
 };

package/dist/components/AIComposer/aiComposer.mcp.d.ts

@@ -1 +1 @@
-export declare const aiComposerDescription = "\n# AIComposer\n\nAIComposer is a Markdown prompt composer built on the existing `RichTextInput`, `VoiceInput`, file-acceptance helpers, `SortableList`, `ScrollArea`, and `AIFilePreview`. It adds AI command, mention, reference, and skill tokens; optional voice capture; raw or managed files; queue editing; steering; submit/stop state; and optional `AIConversation` integration without owning transport.\n\n## Requires\n\nAIComposer embeds RichTextInput, which is built on Lexical. Those packages are optional peer dependencies of entasis, so install them alongside it:\n\n`pnpm add lexical @lexical/history @lexical/link @lexical/list @lexical/markdown @lexical/rich-text @lexical/selection @lexical/utils`\n\n## Import\n\n```svelte\n<script lang=\"ts\">\n  import {\n    AIComposer,\n    type AIComposerAttachment,\n    type AIComposerCommand,\n    type AIComposerHandle,\n    type AIComposerMentionItem,\n    type AIComposerQueuedMessage,\n    type AIComposerSkillItem,\n    type AIComposerSubmitPayload\n  } from './index.ts';\n</script>\n```\n\n## State and defaults\n\n- `value`, `files`, `attachments`, and `queue` are bindable.\n- Omitted `value`, `files`, `attachments`, `busy`, and labels inherit from the nearest `AIConversation`. A supplied direct prop always wins.\n- `defaultValue` initializes an uncontrolled draft once; `onValueChange` reports each library edit once and stays silent for parent updates.\n- Provider queue synchronization is signature-based and idempotent. It never compares proxy queue objects to their raw counterparts.\n\n## Submission\n\n`onSubmit` receives `AIComposerSubmitPayload`: display `markdown`, model-ready `modelInput`, raw files, attachment records, normalized tokens, and command/file/mention/reference/skill id lists. Every submitted token has serialized MDX-style `markdown`.\n\n```svelte\n<AIComposer\n  commands={[\n    {\n      id: 'summarize',\n      label: 'Summarize',\n      prompt: 'Summarize the request and preserve decisions and risks.'\n    }\n  ]}\n  onSubmit={({ markdown, modelInput, tokens, files }) =>\n    sendPrompt({ markdown, modelInput, tokens, files })}\n/>\n```\n\nWhen no direct submit callback is supplied, the nearest conversation receives a user message and the draft clears after successful submission. Direct callbacks retain the draft so application code controls when it clears. Callback failures render a danger alert. `onStop` overrides `conversation.requestStop()`; stop failures are also visible.\n\n## Trigger sources\n\n- `commands` drives `/`; it accepts a Svelte Pro-compatible command array or a trigger-source object.\n- `mentionItems` is the compatibility list for files, references, and skills.\n- `mentions` and `references` compose into `@`; `skills` drives `$`.\n- Trigger-source objects support items, title, empty copy, grouping, token-kind resolution, custom token conversion, sync/async search, and selection.\n- Compatibility callbacks are `onCommandSearch`, `onMentionSearch`, and `onSkillSearch`. Mention search receives `{ query, type }`; skill search falls back to `onMentionSearch({ query, type: 'skill' })`.\n- Synchronous searches stay synchronous. Promise searches expose loading/error/request state through the reused RichTextInput lifecycle and ignore stale responses.\n- A trigger source's `onSelect({ item, context })` is the pick event. The per-kind\n  `onCommandInsert`, `onMentionInsert`, and `onSkillInsert` callbacks run after the token is\n  inserted, so they are named for the insertion rather than the pick: `onSelect` is reserved for\n  \"the user picked this item\" and one component cannot own three of them.\n- Those callbacks and `onSuggestionOpen`, `onSuggestionClose`, `onSuggestionQueryChange`, and `onSuggestionHighlightChange` receive normalized source/lifecycle data.\n\n## Files and attachments\n\nSet `fileDropzone` to enable the chooser, paste, and drag-and-drop intake. The composer delegates to the shared `FileDropzone`, exposes `data-file-drag-state=\"potential | valid | invalid\"`, and renders a default overlay while a file drag is active. Override its copy with `dropLabel` and `dropInvalidLabel`, or replace the overlay content through the `dropzone` slot, which receives `{ state, files, accept, multiple, maxFiles, maxFileSize }`. `fileMultiple`, accepted types, maximum count, and maximum bytes use the shared file acceptance rules and report detailed rejections through `onFileReject`.\n\nWith only `files`, the composer uses raw `File[]`. Supplying `attachments`, an attachment callback, or conversation attachment state activates managed attachments. Managed records use `pending | uploading | uploaded | failed`, keep stable ids across queue edits, show `previewUrl` or `remoteUrl`, and expose add/retry/remove callbacks. Rejected files and retry failures remain visible.\n\n## Voice input\n\nSet `voiceInput` to render the existing VoiceInput primitive before the submit control. `voiceInputVariant` is `compact | expandable` and defaults to `compact`. The expandable presentation grows into the remaining footer width while recording; compact remains a mic-sized control.\n\nConfigure capture with `voiceInputMinDuration`, `voiceInputMaxDuration`, `voiceInputColor`, the accessible labels, and `voiceInputTheme`.\n\n`onVoiceInput` is the only voice lifecycle callback. It receives the finalized recording as an `ArrayBuffer` and must return a promise. AIComposer clears the internal recording before playback can render and replaces the voice control with a spinner until the promise settles. Callback failures render on the voice field. AIComposer remains transport-free: the callback owns transcription, upload, or any other application workflow. Replacing the complete `footer` also replaces the integrated voice control.\n\n```svelte\n<AIComposer\n  voiceInput\n  voiceInputVariant=\"expandable\"\n  onVoiceInput={(audioBuffer) => transcribe(audioBuffer)}\n/>\n```\n\n## Queue\n\nWhen `busy` and `queueWhileBusy` are true, submission creates a flat `AIComposerQueuedMessage` and clears the draft. Queue rows can be reordered, steered, edited, restored, cancelled, or have editing cancelled. The lifecycle callbacks are:\n\n- `onQueueChange`\n- `onQueuedMessageAdd`, `onQueuedMessageCancel`\n- `onQueuedMessageEditStart`, `onQueuedMessageEditCommit`, `onQueuedMessageEditCancel`\n- `onQueuedMessageReorder`, `onSteer`\n\nSingle-message queue callbacks receive `{ message, index }`; edit commits also include `previousMessage`.\n\nAIComposer does not automatically drain the queue when `busy` becomes false. Missing queue targets throw instead of reporting a false success.\n\n## Editor and composition\n\n`submitShortcut` is `none | enter | shift-enter | command-enter`. `toolbar` is `hover | fixed | both | none`; `formats` and `autoresize` are forwarded to RichTextInput.\n\n`header`, `prefix`, `suffix`, and `modelSelector` are content slots. `dropzone` customizes the active file-drop overlay. `footerStart`, `actions`, and replacement `footer` receive `{ value, files, attachments, isEmpty, isBusy }`. The default footer orders file/model controls at the start and custom actions, voice input, and submit/stop at the end.\n\nThe component handle exposes `focus`, `clear`, `insertText`, `insertItem`, `insertToken`, `insertCommand`, `insertMention`, `insertReference`, and `insertSkill`. `clear()` clears editor Markdown and token metadata, not attached files.\n\nThe root accepts native form attributes plus bindable `ref`, `class`, and `theme`. Theme parts cover root, dropzone/dropzone icon, header, files, file rows, body, editor, toolbar, errors, footer/actions, the voice-input region, and every queue region. `voiceInputTheme` is forwarded to the reused VoiceInput primitive.\n";
+export declare const aiComposerDescription = "\n# AIComposer\n\nAIComposer is a Markdown prompt composer built on the existing `RichTextInput`, `VoiceInput`, file-acceptance helpers, `SortableList`, `ScrollArea`, and `AIFilePreview`. It adds AI command, mention, reference, and skill tokens; optional voice capture; raw or managed files; queue editing; steering; submit/stop state; and optional `AIConversation` integration without owning transport.\n\n## Requires\n\nAIComposer embeds RichTextInput, which is built on Lexical. Those packages are optional peer dependencies of entasis, so install them alongside it:\n\n`pnpm add lexical @lexical/history @lexical/link @lexical/list @lexical/markdown @lexical/rich-text @lexical/selection @lexical/utils`\n\n## Import\n\n```svelte\n<script lang=\"ts\">\n  import {\n    AIComposer,\n    type AIComposerAttachment,\n    type AIComposerCommand,\n    type AIComposerHandle,\n    type AIComposerMentionItem,\n    type AIComposerQueuedMessage,\n    type AIComposerSkillItem,\n    type AIComposerSubmitPayload\n  } from './index.ts';\n</script>\n```\n\n## State and defaults\n\n- `value`, `files`, `attachments`, and `queue` are bindable.\n- Omitted `value`, `files`, `attachments`, `busy`, and labels inherit from the nearest `AIConversation`. A supplied direct prop always wins.\n- `defaultValue` initializes an uncontrolled draft once; `onValueChange` reports each library edit once and stays silent for parent updates.\n- Provider queue synchronization is signature-based and idempotent. It never compares proxy queue objects to their raw counterparts.\n\n## Submission\n\n`onSubmit` receives `AIComposerSubmitPayload`: display `markdown`, model-ready `modelInput`, raw files, attachment records, normalized tokens, and command/file/mention/reference/skill id lists. Every submitted token has serialized MDX-style `markdown`.\n\n```svelte\n<AIComposer\n  commands={[\n    {\n      id: 'summarize',\n      label: 'Summarize',\n      prompt: 'Summarize the request and preserve decisions and risks.'\n    }\n  ]}\n  onSubmit={({ markdown, modelInput, tokens, files }) =>\n    sendPrompt({ markdown, modelInput, tokens, files })}\n/>\n```\n\nEnter sends and Shift+Enter inserts a newline (`submitShortcut` defaults to `'enter'`; pass `'none'` to make Enter a newline). When no direct submit callback is supplied, the nearest conversation receives a user message. Either way the draft clears once the send succeeds: a direct `onSubmit` clears it when it returns or its promise resolves, and keeps it when it throws or rejects, showing the error as a danger alert. Focus returns to the editor after every send that started in the composer (Enter, the send button even in Safari, the Queue button, or committing a queued edit), so the next message can be typed straight away. `onStop` overrides `conversation.requestStop()`; stop failures are also visible.\n\nThe handle's `submit(text?)` sends the current draft, or `text` in its place, through the same path (queueing while busy) and focuses the editor; use it for submit-on-select prompt suggestions. For fill-on-select, set the input and call `focus()`: it lands in the editor with the caret after the new text, even when the value changed in the same tick.\n\n## Trigger sources\n\n- `commands` drives `/`; it accepts a Svelte Pro-compatible command array or a trigger-source object.\n- `mentionItems` is the compatibility list for files, references, and skills.\n- `mentions` and `references` compose into `@`; `skills` drives `$`.\n- Trigger-source objects support items, title, empty copy, grouping, token-kind resolution, custom token conversion, sync/async search, and selection.\n- Compatibility callbacks are `onCommandSearch`, `onMentionSearch`, and `onSkillSearch`. Mention search receives `{ query, type }`; skill search falls back to `onMentionSearch({ query, type: 'skill' })`.\n- Synchronous searches stay synchronous. Promise searches expose loading/error/request state through the reused RichTextInput lifecycle and ignore stale responses.\n- A trigger source's `onSelect({ item, context })` is the pick event. The per-kind\n  `onCommandInsert`, `onMentionInsert`, and `onSkillInsert` callbacks run after the token is\n  inserted, so they are named for the insertion rather than the pick: `onSelect` is reserved for\n  \"the user picked this item\" and one component cannot own three of them.\n- Those callbacks and `onSuggestionOpen`, `onSuggestionClose`, `onSuggestionQueryChange`, and `onSuggestionHighlightChange` receive normalized source/lifecycle data.\n\n## Files and attachments\n\nSet `fileDropzone` to enable the chooser, paste, and drag-and-drop intake. The composer delegates to the shared `FileDropzone`, exposes `data-file-drag-state=\"potential | valid | invalid\"`, and renders a default overlay while a file drag is active. Override its copy with `dropLabel` and `dropInvalidLabel`, or replace the overlay content through the `dropzone` slot, which receives `{ state, files, accept, multiple, maxFiles, maxFileSize }`. `fileMultiple`, accepted types, maximum count, and maximum bytes use the shared file acceptance rules and report detailed rejections through `onFileReject`.\n\nWith only `files`, the composer uses raw `File[]`. Supplying `attachments`, an attachment callback, or conversation attachment state activates managed attachments. Managed records use `pending | uploading | uploaded | failed`, keep stable ids across queue edits, show `previewUrl` or `remoteUrl`, and expose add/retry/remove callbacks. Retry failures render as an alert. Rejected files show a short, localized note that names the file and what to attach instead (\"notes.txt isn't supported \u2014 use images or PDF\", built from `accept`), with a dismiss button; it clears itself after a few seconds (a repeated rejection restarts that timer) or on the next accepted file. The note lives in an always-mounted `role=\"status\"` region so screen readers announce each rejection. With `fileMultiple={false}` the limit note reads one file.\n\n## Voice input\n\nSet `voiceInput` to render the existing VoiceInput primitive before the submit control. `voiceInputVariant` is `compact | expandable` and defaults to `compact`. The expandable presentation grows into the remaining footer width while recording; compact remains a mic-sized control.\n\nConfigure capture with `voiceInputMinDuration`, `voiceInputMaxDuration`, `voiceInputColor`, the accessible labels, and `voiceInputTheme`.\n\n`onVoiceInput` is the only voice lifecycle callback. It receives the finalized recording as an `ArrayBuffer` and must return a promise. AIComposer clears the internal recording before playback can render and replaces the voice control with a spinner until the promise settles. Callback failures render on the voice field. AIComposer remains transport-free: the callback owns transcription, upload, or any other application workflow. Replacing the complete `footer` also replaces the integrated voice control.\n\n```svelte\n<AIComposer\n  voiceInput\n  voiceInputVariant=\"expandable\"\n  onVoiceInput={(audioBuffer) => transcribe(audioBuffer)}\n/>\n```\n\n## Queue\n\nWhen `busy` and `queueWhileBusy` are true, submission creates a flat `AIComposerQueuedMessage` and clears the draft. While busy the footer shows a solid stop button in the send position and, once the draft is not empty, a \"Queue message\" button next to it. Queue rows can be reordered, steered (a steered row carries a \"Steering\" badge), edited, restored, cancelled, or have editing cancelled; Escape in the composer cancels an edit unless the suggestion popup handled it; cancelling an edit, by Escape or its button, keeps focus in the editor. Long queued messages truncate inside the composer. The lifecycle callbacks are:\n\n- `onQueueChange`\n- `onQueuedMessageAdd`, `onQueuedMessageCancel`\n- `onQueuedMessageEditStart`, `onQueuedMessageEditCommit`, `onQueuedMessageEditCancel`\n- `onQueuedMessageReorder`, `onSteer`\n\nSingle-message queue callbacks receive `{ message, index }`; edit commits also include `previousMessage`.\n\nAIComposer does not automatically drain the queue when `busy` becomes false. Missing queue targets throw instead of reporting a false success.\n\n## Editor and composition\n\n`submitShortcut` is `none | enter | shift-enter | command-enter` and defaults to `enter`. `toolbar` is `hover | fixed | both | none` and defaults to `none` (no formatting chrome in a chat composer; Markdown shortcuts still work); `formats` and `autoresize` are forwarded to RichTextInput.\n\nThe / @ $ menus show an item's `path` (files and references) or else its `description` as a second line and a leading icon per kind when the item has none. Inline tokens are tinted by kind: commands primary, mentions info, skills success, files and references neutral.\n\n`header`, `prefix`, `suffix`, and `modelSelector` are content slots. `dropzone` customizes the active file-drop overlay. `footerStart`, `actions`, and replacement `footer` receive `{ value, files, attachments, isEmpty, isBusy }`. The default footer puts the attach button at the far start, then `footerStart`; the end holds custom `actions`, the `modelSelector` slot, voice input and the send/stop control, which is always last and keeps priority when the footer is tight. The voice button carries an accessible name only (`voiceInputAriaLabel`), no visible label.\n\nThe component handle exposes `submit`, `focus`, `clear`, `insertText`, `insertItem`, `insertToken`, `insertCommand`, `insertMention`, `insertReference`, and `insertSkill`. `clear()` clears editor Markdown and token metadata, not attached files.\n\n## Look and layout\n\nThe composer is a raised card (raised surface, hairline border, soft lift) that reads on any chat surface. It caps its width at the CSS variable `--ai-chat-content-width` when an ancestor sets it (AIChat does) and centres itself; without the variable it spans its container. The focus ring shows only while the editor has focus, not when a footer button does. On a narrow composer (below 28rem) or a touch screen, editor text steps up to 16px (no iOS focus zoom) and footer buttons, including the voice-input mic, grow to the 36px control height.\n\nThe root accepts native form attributes plus bindable `ref`, `class`, and `theme`; a native `onkeydown` runs before the built-in Escape handling and `preventDefault()` cancels it. Theme parts cover root, dropzone/dropzone icon, header, files, file rows, body, editor, toolbar, errors, the rejected-file `notice`, footer/actions, the voice-input region, and every queue region including `queueBadge` and `queueFiles`. `voiceInputTheme` is forwarded to the reused VoiceInput primitive.\n";

package/dist/components/AIComposer/aiComposer.mcp.js

@@ -51,7 +51,9 @@ AIComposer embeds RichTextInput, which is built on Lexical. Those packages are o
 />
 \`\`\`
 
-When no direct submit callback is supplied, the nearest conversation receives a user message and the draft clears after successful submission. Direct callbacks retain the draft so application code controls when it clears. Callback failures render a danger alert. \`onStop\` overrides \`conversation.requestStop()\`; stop failures are also visible.
+Enter sends and Shift+Enter inserts a newline (\`submitShortcut\` defaults to \`'enter'\`; pass \`'none'\` to make Enter a newline). When no direct submit callback is supplied, the nearest conversation receives a user message. Either way the draft clears once the send succeeds: a direct \`onSubmit\` clears it when it returns or its promise resolves, and keeps it when it throws or rejects, showing the error as a danger alert. Focus returns to the editor after every send that started in the composer (Enter, the send button even in Safari, the Queue button, or committing a queued edit), so the next message can be typed straight away. \`onStop\` overrides \`conversation.requestStop()\`; stop failures are also visible.
+
+The handle's \`submit(text?)\` sends the current draft, or \`text\` in its place, through the same path (queueing while busy) and focuses the editor; use it for submit-on-select prompt suggestions. For fill-on-select, set the input and call \`focus()\`: it lands in the editor with the caret after the new text, even when the value changed in the same tick.
 
 ## Trigger sources
 
@@ -71,7 +73,7 @@ When no direct submit callback is supplied, the nearest conversation receives a
 
 Set \`fileDropzone\` to enable the chooser, paste, and drag-and-drop intake. The composer delegates to the shared \`FileDropzone\`, exposes \`data-file-drag-state="potential | valid | invalid"\`, and renders a default overlay while a file drag is active. Override its copy with \`dropLabel\` and \`dropInvalidLabel\`, or replace the overlay content through the \`dropzone\` slot, which receives \`{ state, files, accept, multiple, maxFiles, maxFileSize }\`. \`fileMultiple\`, accepted types, maximum count, and maximum bytes use the shared file acceptance rules and report detailed rejections through \`onFileReject\`.
 
-With only \`files\`, the composer uses raw \`File[]\`. Supplying \`attachments\`, an attachment callback, or conversation attachment state activates managed attachments. Managed records use \`pending | uploading | uploaded | failed\`, keep stable ids across queue edits, show \`previewUrl\` or \`remoteUrl\`, and expose add/retry/remove callbacks. Rejected files and retry failures remain visible.
+With only \`files\`, the composer uses raw \`File[]\`. Supplying \`attachments\`, an attachment callback, or conversation attachment state activates managed attachments. Managed records use \`pending | uploading | uploaded | failed\`, keep stable ids across queue edits, show \`previewUrl\` or \`remoteUrl\`, and expose add/retry/remove callbacks. Retry failures render as an alert. Rejected files show a short, localized note that names the file and what to attach instead ("notes.txt isn't supported — use images or PDF", built from \`accept\`), with a dismiss button; it clears itself after a few seconds (a repeated rejection restarts that timer) or on the next accepted file. The note lives in an always-mounted \`role="status"\` region so screen readers announce each rejection. With \`fileMultiple={false}\` the limit note reads one file.
 
 ## Voice input
 
@@ -91,7 +93,7 @@ Configure capture with \`voiceInputMinDuration\`, \`voiceInputMaxDuration\`, \`v
 
 ## Queue
 
-When \`busy\` and \`queueWhileBusy\` are true, submission creates a flat \`AIComposerQueuedMessage\` and clears the draft. Queue rows can be reordered, steered, edited, restored, cancelled, or have editing cancelled. The lifecycle callbacks are:
+When \`busy\` and \`queueWhileBusy\` are true, submission creates a flat \`AIComposerQueuedMessage\` and clears the draft. While busy the footer shows a solid stop button in the send position and, once the draft is not empty, a "Queue message" button next to it. Queue rows can be reordered, steered (a steered row carries a "Steering" badge), edited, restored, cancelled, or have editing cancelled; Escape in the composer cancels an edit unless the suggestion popup handled it; cancelling an edit, by Escape or its button, keeps focus in the editor. Long queued messages truncate inside the composer. The lifecycle callbacks are:
 
 - \`onQueueChange\`
 - \`onQueuedMessageAdd\`, \`onQueuedMessageCancel\`
@@ -104,11 +106,17 @@ AIComposer does not automatically drain the queue when \`busy\` becomes false. M
 
 ## Editor and composition
 
-\`submitShortcut\` is \`none | enter | shift-enter | command-enter\`. \`toolbar\` is \`hover | fixed | both | none\`; \`formats\` and \`autoresize\` are forwarded to RichTextInput.
+\`submitShortcut\` is \`none | enter | shift-enter | command-enter\` and defaults to \`enter\`. \`toolbar\` is \`hover | fixed | both | none\` and defaults to \`none\` (no formatting chrome in a chat composer; Markdown shortcuts still work); \`formats\` and \`autoresize\` are forwarded to RichTextInput.
+
+The / @ $ menus show an item's \`path\` (files and references) or else its \`description\` as a second line and a leading icon per kind when the item has none. Inline tokens are tinted by kind: commands primary, mentions info, skills success, files and references neutral.
+
+\`header\`, \`prefix\`, \`suffix\`, and \`modelSelector\` are content slots. \`dropzone\` customizes the active file-drop overlay. \`footerStart\`, \`actions\`, and replacement \`footer\` receive \`{ value, files, attachments, isEmpty, isBusy }\`. The default footer puts the attach button at the far start, then \`footerStart\`; the end holds custom \`actions\`, the \`modelSelector\` slot, voice input and the send/stop control, which is always last and keeps priority when the footer is tight. The voice button carries an accessible name only (\`voiceInputAriaLabel\`), no visible label.
+
+The component handle exposes \`submit\`, \`focus\`, \`clear\`, \`insertText\`, \`insertItem\`, \`insertToken\`, \`insertCommand\`, \`insertMention\`, \`insertReference\`, and \`insertSkill\`. \`clear()\` clears editor Markdown and token metadata, not attached files.
 
-\`header\`, \`prefix\`, \`suffix\`, and \`modelSelector\` are content slots. \`dropzone\` customizes the active file-drop overlay. \`footerStart\`, \`actions\`, and replacement \`footer\` receive \`{ value, files, attachments, isEmpty, isBusy }\`. The default footer orders file/model controls at the start and custom actions, voice input, and submit/stop at the end.
+## Look and layout
 
-The component handle exposes \`focus\`, \`clear\`, \`insertText\`, \`insertItem\`, \`insertToken\`, \`insertCommand\`, \`insertMention\`, \`insertReference\`, and \`insertSkill\`. \`clear()\` clears editor Markdown and token metadata, not attached files.
+The composer is a raised card (raised surface, hairline border, soft lift) that reads on any chat surface. It caps its width at the CSS variable \`--ai-chat-content-width\` when an ancestor sets it (AIChat does) and centres itself; without the variable it spans its container. The focus ring shows only while the editor has focus, not when a footer button does. On a narrow composer (below 28rem) or a touch screen, editor text steps up to 16px (no iOS focus zoom) and footer buttons, including the voice-input mic, grow to the 36px control height.
 
-The root accepts native form attributes plus bindable \`ref\`, \`class\`, and \`theme\`. Theme parts cover root, dropzone/dropzone icon, header, files, file rows, body, editor, toolbar, errors, footer/actions, the voice-input region, and every queue region. \`voiceInputTheme\` is forwarded to the reused VoiceInput primitive.
+The root accepts native form attributes plus bindable \`ref\`, \`class\`, and \`theme\`; a native \`onkeydown\` runs before the built-in Escape handling and \`preventDefault()\` cancels it. Theme parts cover root, dropzone/dropzone icon, header, files, file rows, body, editor, toolbar, errors, the rejected-file \`notice\`, footer/actions, the voice-input region, and every queue region including \`queueBadge\` and \`queueFiles\`. \`voiceInputTheme\` is forwarded to the reused VoiceInput primitive.
 `;

package/dist/components/AIComposer/aiComposer.props.d.ts

@@ -95,6 +95,11 @@ export type AIComposerQueuedMessageEditPayload = AIComposerQueuedMessagePayload
     previousMessage: AIComposerQueuedMessage;
 };
 export type AIComposerHandle = RichTextInputHandle & {
+    /**
+     * Sends the current draft, or `text` in its place, exactly like Enter or the send button
+     * (queued while busy when `queueWhileBusy` is on), then focuses the editor.
+     */
+    submit: (text?: string) => Promise<void>;
     insertCommand: (item: AIComposerCommand) => void;
     insertMention: (item: AIComposerMentionItem) => void;
     insertReference: (item: AIComposerMentionItem) => void;
@@ -163,9 +168,17 @@ export type AIComposerProps = WithAttachments<Omit<HTMLFormAttributes, 'children
     references?: AIComposerTriggerSource<AIComposerMentionItem>;
     /** Skill trigger source. */
     skills?: AIComposerTriggerSource<AIComposerSkillItem> | readonly AIComposerSkillItem[];
-    /** Keyboard shortcut that submits when the suggestion popup has not handled the key. */
+    /**
+     * Keyboard shortcut that submits when the suggestion popup has not handled the key. With the
+     * default `'enter'`, Shift+Enter inserts a newline; `'none'` makes Enter a newline again.
+     * @default 'enter'
+     */
     submitShortcut?: RichTextInputSubmitShortcut;
-    /** Formatting toolbar mode forwarded to RichTextInput. */
+    /**
+     * Formatting toolbar mode forwarded to RichTextInput. Chat composers show no formatting chrome
+     * by default; Markdown shortcuts still work.
+     * @default 'none'
+     */
     toolbar?: RichTextInputToolbar;
     /** Formatting controls and Markdown shortcuts enabled in RichTextInput. */
     formats?: RichTextInputFormat[];
@@ -181,7 +194,7 @@ export type AIComposerProps = WithAttachments<Omit<HTMLFormAttributes, 'children
     voiceInputMaxDuration?: number;
     /** Semantic color used while recording. */
     voiceInputColor?: Colors;
-    /** Accessible label and tooltip for starting voice capture. */
+    /** Accessible name and tooltip of the mic button that starts voice capture (no visible label). */
     voiceInputAriaLabel?: string;
     /** Accessible label and tooltip for stopping voice capture. */
     voiceInputStopLabel?: string;
@@ -205,7 +218,7 @@ export type AIComposerProps = WithAttachments<Omit<HTMLFormAttributes, 'children
     dropzone?: Slot<AIComposerDropzoneState>;
     /** Content rendered below the composer controls. */
     footer?: Slot<AIComposerSubmitState>;
-    /** Content rendered at the start of the default footer. */
+    /** Content rendered at the start of the default footer, after the attach button. */
     footerStart?: Slot<AIComposerSubmitState>;
     /** Additional actions rendered before the default submit or stop control. */
     actions?: Slot<AIComposerSubmitState>;
@@ -213,13 +226,20 @@ export type AIComposerProps = WithAttachments<Omit<HTMLFormAttributes, 'children
     prefix?: Slot;
     /** Content rendered after the default composer actions. */
     suffix?: Slot;
-    /** Model selector rendered in the default action row. */
+    /** Model selector rendered at the end of the default footer, next to the send control. */
     modelSelector?: Slot;
-    /** Handles a submission, queued submission, or steering message. */
+    /**
+     * Handles a submission, queued submission, or steering message. The draft clears once it
+     * returns or its promise resolves; a throw or rejection keeps the draft and shows the error.
+     * Focus returns to the editor either way.
+     */
     onSubmit?: (payload: AIComposerSubmitPayload) => void | Promise<void>;
     /** Requests that the active response stop. */
     onStop?: () => void | Promise<void>;
-    /** Called with files rejected by count, type, or size constraints. */
+    /**
+     * Called with files rejected by count, type, or size constraints. The composer also shows a
+     * short, localized note naming the file and what to attach instead, which dismisses itself.
+     */
     onFilesRejected?: (files: File[]) => void;
     /** Called whenever the accepted file list changes. */
     onFilesChange?: (files: File[]) => void;