entasis 0.11.0 → 0.13.0

package/dist/components/AIAskUserQuestion/AIAskUserQuestionStep.svelte

@@ -1,12 +1,19 @@
 <script lang="ts">
+	import { tick } from 'svelte';
 	import CheckboxesInput from '../Form/CheckboxesInput/CheckboxesInput.svelte';
 	import RadioInput from '../Form/RadioInput/RadioInput.svelte';
 	import TextArea from '../Form/TextArea/TextArea.svelte';
+	import TextInput from '../Form/TextInput/TextInput.svelte';
 	import Slot from '../Slot/Slot.svelte';
 	import type { Slot as SlotType } from '../Slot/slot.js';
+	import { composedContains, getDeepActiveElement } from '../../utils/focus.js';
+	import { useI18n } from '../../i18n/context.svelte.js';
 	import AIAskUserQuestionFileStep from './AIAskUserQuestionFileStep.svelte';
 	import {
+		AI_ASK_OTHER_VALUE,
+		getAIAskCustomAnswer,
 		getAIAskFileAnswer,
+		getAIAskOptionAnswers,
 		getAIAskStringAnswer,
 		getAIAskStringArrayAnswer,
 		isAIAskQuestionRequired
@@ -14,7 +21,9 @@
 	import type {
 		AIAskAnswer,
 		AIAskQuestion,
-		AIAskUserQuestionQuestionState
+		AIAskUserQuestionQuestionState,
+		AIMultipleQuestion,
+		AISingleQuestion
 	} from './aiAskUserQuestion.props.js';
 	import {
 		useAIAskUserQuestionTheme,
@@ -27,8 +36,11 @@
 		errorMessage,
 		disabled = false,
 		renderer,
+		other,
 		onValueChange,
+		onOtherChange,
 		onError,
+		onRegister,
 		theme
 	}: {
 		question: AIAskQuestion;
@@ -36,21 +48,150 @@
 		errorMessage?: string;
 		disabled?: boolean;
 		renderer?: SlotType<AIAskUserQuestionQuestionState>;
-		onValueChange: (value: AIAskAnswer) => void;
+		/** The "Other…" text while Other is chosen, kept by the parent so it survives a remount. */
+		other?: string;
+		/** `advance: false` marks an edit that must never auto-advance (the "Other…" field). */
+		onValueChange: (value: AIAskAnswer, options?: { advance?: boolean }) => void;
+		onOtherChange: (text: string | undefined) => void;
 		onError: (message: string) => void;
+		/** Registers the number-key picker; returns its cleanup. */
+		onRegister?: (pick: (position: number) => boolean) => () => void;
 		theme?: AIAskUserQuestionThemeProps;
 	} = $props();
 
+	const id = $props.id();
+	const t = $derived(useI18n());
 	const classes = $derived(useAIAskUserQuestionTheme(theme));
 	const required = $derived(isAIAskQuestionRequired(question));
+	const errorId = $derived(`${id}-error`);
+	let stepElement = $state<HTMLElement>();
+	// The parent remembers whether "Other…" is chosen and its text, so typed text that equals an
+	// option id still reads as Other. An answer that arrives with free text (a string that is no
+	// option id, from `defaultValue` say) also chooses Other.
+	const customAnswer = $derived(getAIAskCustomAnswer(question, value));
+	const otherText = $derived(other ?? customAnswer ?? '');
+	const otherActive = $derived(other !== undefined || customAnswer !== undefined);
+	const choiceAttrs = $derived({
+		'aria-invalid': errorMessage ? ('true' as const) : undefined,
+		'aria-describedby': errorMessage ? errorId : undefined
+	});
+
+	function choiceItems(choice: AISingleQuestion | AIMultipleQuestion) {
+		const items = choice.options.map((option) => ({ ...option, value: option.id }));
+		if (!choice.showOther) return items;
+		return [...items, { value: AI_ASK_OTHER_VALUE, label: choice.otherLabel ?? t.aiAskOther }];
+	}
+
+	async function focusOther(): Promise<void> {
+		await tick();
+		stepElement
+			?.querySelector<HTMLInputElement>('[data-slot="ai-ask-user-question-other"] input')
+			?.focus();
+	}
+
+	// The option ids of a multiple answer. Its "Other…" text is the last entry, and is left out
+	// even when it equals an option id.
+	function optionAnswers(): string[] {
+		if (question.type !== 'multiple') return [];
+		const entries = getAIAskStringArrayAnswer(value);
+		const withoutOther =
+			otherActive && otherText.trim() && entries.at(-1) === otherText
+				? entries.slice(0, -1)
+				: entries;
+		return getAIAskOptionAnswers(question, withoutOther);
+	}
+
+	function selectSingle(answer: string | null): void {
+		if (answer === null) return;
+		if (answer !== AI_ASK_OTHER_VALUE) {
+			onOtherChange(undefined);
+			onValueChange(answer);
+			return;
+		}
+		const text = otherText;
+		onOtherChange(text);
+		onValueChange(text.trim() ? text : '', { advance: false });
+		void focusOther();
+	}
+
+	function selectMultiple(next: string[]): void {
+		const withOther = next.includes(AI_ASK_OTHER_VALUE);
+		const options = next.filter((entry) => entry !== AI_ASK_OTHER_VALUE);
+		const text = otherText;
+		if (withOther && !otherActive) void focusOther();
+		onOtherChange(withOther ? text : undefined);
+		onValueChange(withOther && text.trim() ? [...options, text] : options, { advance: false });
+	}
+
+	function typeOther(text: string): void {
+		const options = optionAnswers();
+		onOtherChange(text);
+		if (question.type === 'multiple') {
+			onValueChange(text.trim() ? [...options, text] : options, { advance: false });
+			return;
+		}
+		onValueChange(text, { advance: false });
+	}
+
+	$effect(() => onRegister?.(pickOption));
+
+	/** Picks or toggles the option behind a number key: 1 is the first option, Other comes last. */
+	function pickOption(position: number): boolean {
+		if (renderer || disabled) return false;
+		if (question.type !== 'single' && question.type !== 'multiple') return false;
+		const items = choiceItems(question);
+		const item = items[position];
+		if (!item || ('disabled' in item && item.disabled)) return false;
+		const followFocus =
+			item.value !== AI_ASK_OTHER_VALUE &&
+			stepElement !== undefined &&
+			composedContains(stepElement, getDeepActiveElement(stepElement.ownerDocument));
+		if (question.type === 'single') {
+			selectSingle(item.value);
+		} else {
+			const current = [...optionAnswers(), ...(otherActive ? [AI_ASK_OTHER_VALUE] : [])];
+			selectMultiple(
+				current.includes(item.value)
+					? current.filter((entry) => entry !== item.value)
+					: [...current, item.value]
+			);
+		}
+		// Like an arrow key in a radio group, the picked option takes focus and the Tab stop, so
+		// Space and Tab act on it next. Other… focuses its own text field instead.
+		if (followFocus) void focusChoice(position);
+		return true;
+	}
+
+	async function focusChoice(position: number): Promise<void> {
+		await tick();
+		stepElement
+			?.querySelectorAll<HTMLElement>('[role="radio"],[role="checkbox"]')
+			[position]?.focus();
+	}
 </script>
 
-<div data-slot="ai-ask-user-question-step" class={classes.stepContent()}>
+<!-- tabindex -1: the step itself takes focus when a step change finds no control inside it. -->
+<div
+	bind:this={stepElement}
+	data-slot="ai-ask-user-question-step"
+	tabindex="-1"
+	class={classes.stepContent()}
+>
 	{#if renderer}
-		<Slot render={renderer} payload={{ question, value, setValue: onValueChange }} />
+		<Slot
+			render={renderer}
+			payload={{ question, value, setValue: (answer: AIAskAnswer) => onValueChange(answer) }}
+		/>
 	{:else}
 		<div class={classes.question()}>
-			<div class={classes.questionTitle()}>{question.title}</div>
+			<div id={`${id}-title`} class={classes.questionTitle()}>
+				{question.title}{#if required}<span
+						data-slot="ai-ask-user-question-required"
+						class={classes.requiredMarker()}
+						><span aria-hidden="true">*</span><span class="sr-only">{t.aiAskRequiredMarker}</span
+						></span
+					>{/if}
+			</div>
 			{#if question.description}
 				<div class={classes.questionDescription()}>{question.description}</div>
 			{/if}
@@ -60,10 +201,14 @@
 			<TextArea
 				value={getAIAskStringAnswer(value)}
 				name={question.id}
-				placeholder={question.placeholder ?? 'Type your answer...'}
+				placeholder={question.placeholder ?? t.aiAskPlaceholder}
 				rows={question.rows ?? 4}
-				errors={errorMessage ? [errorMessage] : []}
 				class={classes.textArea()}
+				textareaAttrs={{
+					'aria-labelledby': `${id}-title`,
+					'aria-invalid': errorMessage ? 'true' : undefined,
+					'aria-describedby': errorMessage ? errorId : undefined
+				}}
 				{required}
 				{disabled}
 				onValueChange={(answer) => onValueChange(answer ?? '')}
@@ -71,34 +216,33 @@
 		{:else if question.type === 'single'}
 			<RadioInput
 				mode="card"
-				value={getAIAskStringAnswer(value) || null}
+				value={otherActive ? AI_ASK_OTHER_VALUE : getAIAskStringAnswer(value) || null}
 				name={question.id}
-				items={question.options.map((option) => ({ ...option, value: option.id }))}
+				items={choiceItems(question)}
 				class={classes.options()}
-				fieldAttrs={{ 'aria-label': question.title }}
-				errors={errorMessage ? [errorMessage] : []}
+				fieldAttrs={{ 'aria-label': question.title, ...choiceAttrs }}
 				{required}
 				{disabled}
-				onValueChange={(answer) => {
-					if (answer !== null) onValueChange(answer);
-				}}
+				onValueChange={selectSingle}
 			/>
 		{:else if question.type === 'multiple'}
 			<CheckboxesInput
 				mode="card"
-				value={getAIAskStringArrayAnswer(value)}
+				value={[...optionAnswers(), ...(otherActive ? [AI_ASK_OTHER_VALUE] : [])]}
 				name={question.id}
-				items={question.options.map((option) => ({ ...option, value: option.id }))}
+				items={choiceItems(question)}
 				class={classes.options()}
-				fieldAttrs={{ role: 'group', 'aria-label': question.title }}
-				errors={errorMessage ? [errorMessage] : []}
+				fieldAttrs={{ role: 'group', 'aria-label': question.title, ...choiceAttrs }}
 				{required}
 				{disabled}
-				onValueChange={(answer: string[]) => onValueChange(answer)}
+				onValueChange={(answer: string[]) => selectMultiple(answer)}
 			/>
 		{:else if question.type === 'file'}
 			<AIAskUserQuestionFileStep
 				{question}
+				labelledby={`${id}-title`}
+				invalid={Boolean(errorMessage)}
+				describedby={errorMessage ? errorId : undefined}
 				files={getAIAskFileAnswer(value)}
 				{required}
 				{disabled}
@@ -107,9 +251,24 @@
 				onValueChange={(files) => onValueChange(files)}
 			/>
 		{/if}
+
+		{#if (question.type === 'single' || question.type === 'multiple') && question.showOther && otherActive}
+			<div data-slot="ai-ask-user-question-other" class={classes.other()}>
+				<TextInput
+					value={otherText}
+					name={`${question.id}-other`}
+					placeholder={question.otherPlaceholder ?? t.aiAskOtherPlaceholder}
+					inputAttrs={{ 'aria-label': question.otherLabel ?? t.aiAskOther }}
+					{disabled}
+					onValueChange={(text) => typeOther(text ?? '')}
+				/>
+			</div>
+		{/if}
 	{/if}
 
-	{#if errorMessage && (renderer || question.type === 'file')}
-		<div role="alert" class={classes.error()}>{errorMessage}</div>
+	{#if errorMessage}
+		<p id={errorId} role="alert" data-slot="ai-ask-user-question-error" class={classes.error()}>
+			{errorMessage}
+		</p>
 	{/if}
 </div>

package/dist/components/AIAskUserQuestion/AIAskUserQuestionStep.svelte.d.ts

@@ -7,8 +7,16 @@ type $$ComponentProps = {
     errorMessage?: string;
     disabled?: boolean;
     renderer?: SlotType<AIAskUserQuestionQuestionState>;
-    onValueChange: (value: AIAskAnswer) => void;
+    /** The "Other…" text while Other is chosen, kept by the parent so it survives a remount. */
+    other?: string;
+    /** `advance: false` marks an edit that must never auto-advance (the "Other…" field). */
+    onValueChange: (value: AIAskAnswer, options?: {
+        advance?: boolean;
+    }) => void;
+    onOtherChange: (text: string | undefined) => void;
     onError: (message: string) => void;
+    /** Registers the number-key picker; returns its cleanup. */
+    onRegister?: (pick: (position: number) => boolean) => () => void;
     theme?: AIAskUserQuestionThemeProps;
 };
 declare const AIAskUserQuestionStep: import("svelte").Component<$$ComponentProps, {}, "">;

package/dist/components/AIAskUserQuestion/AIAskUserQuestionSummary.svelte

@@ -0,0 +1,56 @@
+<script lang="ts">
+	import { useI18n } from '../../i18n/context.svelte.js';
+	import { summarizeAIAskAnswers } from './aiAskUserQuestionAnswers.js';
+	import type { AIAskUserQuestionSummaryProps } from './aiAskUserQuestion.props.js';
+	import { useAIAskUserQuestionTheme } from './aiAskUserQuestion.theme.js';
+
+	let {
+		ref = $bindable(null),
+		size = 'normal',
+		questions,
+		value,
+		title,
+		showSkipped = true,
+		class: className,
+		theme,
+		...attachments
+	}: AIAskUserQuestionSummaryProps = $props();
+
+	const id = $props.id();
+	const t = $derived(useI18n());
+	const classes = $derived(useAIAskUserQuestionTheme(theme));
+	const items = $derived(
+		summarizeAIAskAnswers(questions, value).filter((item) => showSkipped || item.answered)
+	);
+	const heading = $derived(title === false ? undefined : (title ?? t.aiAskSummaryTitle));
+</script>
+
+<div
+	bind:this={ref}
+	data-slot="ai-ask-user-question-summary"
+	role="group"
+	data-size={size}
+	aria-labelledby={heading ? `${id}-title` : undefined}
+	class={classes.summary({ className })}
+	{...attachments}
+>
+	{#if heading}
+		<div
+			id={`${id}-title`}
+			data-slot="ai-ask-user-question-summary-title"
+			class={classes.summaryTitle()}
+		>
+			{heading}
+		</div>
+	{/if}
+	<dl class={classes.summaryList()}>
+		{#each items as item (item.questionId)}
+			<div data-slot="ai-ask-user-question-summary-item" class={classes.summaryItem()}>
+				<dt class={classes.summaryQuestion()}>{item.question.title}</dt>
+				<dd class={classes.summaryAnswer({ answered: item.answered })}>
+					{item.answered ? item.labels.join(', ') : t.aiAskSkipped}
+				</dd>
+			</div>
+		{/each}
+	</dl>
+</div>

package/dist/components/AIAskUserQuestion/AIAskUserQuestionSummary.svelte.d.ts

@@ -0,0 +1,4 @@
+import type { AIAskUserQuestionSummaryProps } from './aiAskUserQuestion.props.js';
+declare const AIAskUserQuestionSummary: import("svelte").Component<AIAskUserQuestionSummaryProps, {}, "ref">;
+type AIAskUserQuestionSummary = ReturnType<typeof AIAskUserQuestionSummary>;
+export default AIAskUserQuestionSummary;

package/dist/components/AIAskUserQuestion/aiAskUserQuestion.mcp.d.ts

@@ -1 +1 @@
-export declare const aiAskUserQuestionDescription = "\n# AIAskUserQuestion\n\nAIAskUserQuestion renders a validated stepped answer flow for AI tools that need structured human input. It reuses `Stepper`, `TextArea`, card radio/checkbox inputs, `FileInput`, `Button`, `Alert`, and `Empty`.\n\n## Import and schemas\n\n```svelte\n<script lang=\"ts\">\n  import {\n    AIAskUserQuestion,\n    aiAskUserQuestionToolInputSchema,\n    type AIAskUserQuestionQuestion,\n    type AIAskUserQuestionSubmitPayload,\n    type AIAskUserQuestionValues\n  } from './index.ts';\n</script>\n```\n\nThe package exports Valibot schemas for tool state, options, every question kind, question arrays, answer maps, and the complete tool payload. The loose tool payload accepts `state`, `prompt`, `questions`, `value`/`values`, headings, context, and action labels.\n\n## Question kinds\n\n- Text: `{ id, title, type?: 'text', description?, required?, placeholder?, rows? }`\n- Single choice: `{ id, title, type: 'single', options, ... }`\n- Multiple choice: `{ id, title, type: 'multiple', options, ... }`\n- File: `{ id, title, type: 'file', accept?, multiple?, maxFiles?, maxSize?, ... }`\n\nQuestions are required by default. Disabled choice options remain visible but cannot be selected. File questions use the shared chooser/drop acceptance behavior and show type, size, count, and duplicate failures.\n\n## State and behavior\n\n- `value` is the bindable answer map. `defaultValue` initializes omitted state once; later default changes do not reset answers.\n- `onValueChange(value)` runs once after a user changes an answer. Parent value changes and selecting the current answer do not emit it.\n- `activeIndex` is bindable and is clamped whenever the question list changes.\n- `autoAdvance` wins over `autoAdvanceSingle`; `autoAdvanceDelay` wins over `autoAdvanceSingleDelay`.\n- Single-choice answers auto-advance by default after 280 ms, including values set through a custom question slot. Empty values, the last step, disabled state, and active async work never auto-advance.\n- `disabled` blocks all controls. `submitting` combines with internal async submit/discard state.\n\n## Validation and actions\n\nThe default required message is `Answer required.`. `requiredMessage` accepts either a string or a per-question formatter. Primary navigation validates the active question; final submission finds the first missing required answer and moves to it. Previous/next icon controls remain available for explicit navigation.\n\n`onSubmit` receives typed `answers`, the raw `values` map, and the source `questions`. `onDiscard` adds the optional dismiss action. Async submit/discard exceptions and file rejection messages render visibly instead of being swallowed.\n\n```svelte\n<AIAskUserQuestion\n  questions={[\n    {\n      id: 'tone',\n      type: 'single',\n      title: 'Choose a tone',\n      options: [\n        { id: 'brief', label: 'Brief' },\n        { id: 'detailed', label: 'Detailed' }\n      ]\n    },\n    {\n      id: 'notes',\n      type: 'text',\n      title: 'Add constraints',\n      required: false\n    }\n  ]}\n  bind:value={answers}\n  onSubmit={({ answers, values }) => resolveTool({ answers, values })}\n/>\n```\n\n## Composition\n\n`header`, `footer`, `children`, and `empty` receive `AIAskUserQuestionState`: questions, value, active question/index, visible error, working flags, first/last flags, and `goTo`, `previous`, `next`, `submit`, and `discard` actions.\n\nThe `question` slot receives `{ question, value, setValue }`. Its setter preserves central validation, change callbacks, and single-choice auto-advance; no public compound subcomponents are required.\n\nThe root forwards native div attributes and exposes bindable `ref`, `class`, and `theme`. Theme parts cover root, header text/progress group/steps, the body region, step content, question title and description, textarea, option/file regions, empty/error states, and footer.\n";
+export declare const aiAskUserQuestionDescription = "\n# AIAskUserQuestion\n\nAIAskUserQuestion renders a validated stepped answer flow for AI tools that need structured human input. It reuses `Stepper`, `TextArea`, card radio/checkbox inputs, `FileInput`, `Button`, `Alert`, and `Empty`.\n\n## Import and schemas\n\n```svelte\n<script lang=\"ts\">\n  import {\n    AIAskUserQuestion,\n    aiAskUserQuestionToolInputSchema,\n    type AIAskUserQuestionQuestion,\n    type AIAskUserQuestionSubmitPayload,\n    type AIAskUserQuestionValues\n  } from './index.ts';\n</script>\n```\n\nThe package exports Valibot schemas for tool state, options, every question kind, question arrays, answer maps, and the complete tool payload. The loose tool payload accepts `state`, `prompt`, `questions`, `value`/`values`, headings, context, and action labels.\n\n## Question kinds\n\n- Text: `{ id, title, type?: 'text', description?, required?, placeholder?, rows? }`\n- Single choice: `{ id, title, type: 'single', options, showOther?, otherLabel?, otherPlaceholder?, ... }`\n- Multiple choice: `{ id, title, type: 'multiple', options, showOther?, otherLabel?, otherPlaceholder?, ... }`\n- File: `{ id, title, type: 'file', accept?, multiple?, maxFiles?, maxSize?, ... }`\n\nQuestions are optional by default; `required: true` blocks continuing until answered and shows a required marker after the title. On an optional, unanswered step before the last one the primary action reads \"Skip\" (`skipLabel`). Every single- and multiple-choice question offers a free-text \"Other\u2026\" choice after its options, so the user can always answer in their own words. The component's `showOther` prop (default `true`) sets this for every choice question and a question's own `showOther` wins over it, either way; file questions never get one (their answer is files). In AIThread and AIChat, an `showOther` key on the ask_user_question tool input (or the docked request) passes through. The Other\u2026 choice: its typed text is the answer (the single answer string, or the last entry of the multiple answer array) and it never auto-advances, even when the text equals an option id. The answer stays a plain string, so in `summarizeAIAskAnswers` and in a value restored later, text equal to an option id reads as that option. Disabled choice options remain visible but cannot be selected. File questions use the shared chooser/drop acceptance behavior and show type, size, count, and duplicate failures.\n\n## State and behavior\n\n- `value` is the bindable answer map. `defaultValue` initializes omitted state once; later default changes do not reset answers.\n- `onValueChange(value)` runs once after a user changes an answer. Parent value changes and selecting the current answer do not emit it.\n- `activeIndex` is bindable and is clamped whenever the question list changes.\n- `autoAdvance` wins over `autoAdvanceSingle`; `autoAdvanceDelay` wins over `autoAdvanceSingleDelay`.\n- Single-choice answers auto-advance by default after 280 ms, including values set through a custom question slot. Empty values, anything typed or chosen through \"Other\u2026\", the last step, disabled state, and active async work never auto-advance.\n- Keyboard: number keys 1\u20139 pick (single) or toggle (multiple) the active question's options, with \"Other\u2026\" last; digits typed into a text field stay text. When focus is on the question's options, the picked option takes focus and the Tab stop, as an arrow key does in a radio group (picking \"Other\u2026\" focuses its text field). Enter on a choice or a one-line field continues or submits; in a textarea, Ctrl/Cmd+Enter does. When the step changes with focus inside it, focus moves to the new step's first control (or to the step itself when it has none, such as a file step, where Enter also continues or submits), so the keys keep working step after step. A consumer `onkeydown` runs first and `preventDefault()` cancels these keys.\n- `disabled` blocks all controls. `submitting` combines with internal async submit/discard state.\n\n## Validation and actions\n\nThe default required message is `Answer required.`. `requiredMessage` accepts either a string or a per-question formatter. It renders once, in the danger colour, under the question; the options themselves stay neutral and the choice group gets `aria-invalid` and `aria-describedby`. Primary navigation validates the active question; final submission finds the first missing required answer and moves to it. The step dots (8px dots inside 24px pointer targets, labelled \"Go to question N\") and the primary action navigate; a single question shows no pager. `previousLabel` is deprecated: the default footer no longer renders previous/next arrow buttons.\n\n`onSubmit` receives typed `answers`, the raw `values` map, and the source `questions`. `onDiscard` adds the optional dismiss action. Async submit/discard exceptions and file rejection messages render visibly instead of being swallowed.\n\n```svelte\n<AIAskUserQuestion\n  questions={[\n    {\n      id: 'tone',\n      type: 'single',\n      title: 'Choose a tone',\n      options: [\n        { id: 'brief', label: 'Brief' },\n        { id: 'detailed', label: 'Detailed' }\n      ]\n    },\n    {\n      id: 'notes',\n      type: 'text',\n      title: 'Add constraints'\n    }\n  ]}\n  bind:value={answers}\n  onSubmit={({ answers, values }) => resolveTool({ answers, values })}\n/>\n```\n\n## Header\n\nThe header shows the `requester` (\"Asked by \u2026\") above a semibold `title` (default \"Answer request\") and the optional `context`.\n\n## Answered summary\n\nOnce a request is complete, keep a compact record in the transcript instead of a raw tool row. `AIAskUserQuestionSummary` renders question \u2192 chosen labels (option ids become labels, \"Other\u2026\" and text answers show as typed, files by name, skipped questions read \"Skipped\"); `summarizeAIAskAnswers(questions, values)` returns the same pairs as data.\n\n```svelte\n<script lang=\"ts\">\n  import { AIAskUserQuestionSummary } from './index.ts';\n</script>\n\n<AIAskUserQuestionSummary {questions} value={submittedValues} />\n```\n\nProps: `questions`, `value`, `title` (string, or `false` to hide the \"Your answers\" heading), `showSkipped` (default true), `ref`, `class`, `theme` (summary, summaryTitle, summaryList, summaryItem, summaryQuestion, summaryAnswer).\n\n## Composition\n\n`header`, `footer`, `children`, and `empty` receive `AIAskUserQuestionState`: questions, value, active question/index, visible error, working flags, first/last flags, and `goTo`, `previous`, `next`, `submit`, and `discard` actions.\n\nThe `question` slot receives `{ question, value, setValue }`. Its setter preserves central validation, change callbacks, and single-choice auto-advance; no public compound subcomponents are required.\n\nThe root forwards native div attributes and exposes bindable `ref`, `class`, and `theme`. Theme parts cover root, header text/requester/progress group/steps, the body region, step content, question title, required marker and description, textarea, option/other/file regions, the per-question error, the submit-failure alert, empty state, footer, and the summary parts.\n";

package/dist/components/AIAskUserQuestion/aiAskUserQuestion.mcp.js

@@ -22,11 +22,11 @@ The package exports Valibot schemas for tool state, options, every question kind
 ## Question kinds
 
 - Text: \`{ id, title, type?: 'text', description?, required?, placeholder?, rows? }\`
-- Single choice: \`{ id, title, type: 'single', options, ... }\`
-- Multiple choice: \`{ id, title, type: 'multiple', options, ... }\`
+- Single choice: \`{ id, title, type: 'single', options, showOther?, otherLabel?, otherPlaceholder?, ... }\`
+- Multiple choice: \`{ id, title, type: 'multiple', options, showOther?, otherLabel?, otherPlaceholder?, ... }\`
 - File: \`{ id, title, type: 'file', accept?, multiple?, maxFiles?, maxSize?, ... }\`
 
-Questions are required by default. Disabled choice options remain visible but cannot be selected. File questions use the shared chooser/drop acceptance behavior and show type, size, count, and duplicate failures.
+Questions are optional by default; \`required: true\` blocks continuing until answered and shows a required marker after the title. On an optional, unanswered step before the last one the primary action reads "Skip" (\`skipLabel\`). Every single- and multiple-choice question offers a free-text "Other…" choice after its options, so the user can always answer in their own words. The component's \`showOther\` prop (default \`true\`) sets this for every choice question and a question's own \`showOther\` wins over it, either way; file questions never get one (their answer is files). In AIThread and AIChat, an \`showOther\` key on the ask_user_question tool input (or the docked request) passes through. The Other… choice: its typed text is the answer (the single answer string, or the last entry of the multiple answer array) and it never auto-advances, even when the text equals an option id. The answer stays a plain string, so in \`summarizeAIAskAnswers\` and in a value restored later, text equal to an option id reads as that option. Disabled choice options remain visible but cannot be selected. File questions use the shared chooser/drop acceptance behavior and show type, size, count, and duplicate failures.
 
 ## State and behavior
 
@@ -34,12 +34,13 @@ Questions are required by default. Disabled choice options remain visible but ca
 - \`onValueChange(value)\` runs once after a user changes an answer. Parent value changes and selecting the current answer do not emit it.
 - \`activeIndex\` is bindable and is clamped whenever the question list changes.
 - \`autoAdvance\` wins over \`autoAdvanceSingle\`; \`autoAdvanceDelay\` wins over \`autoAdvanceSingleDelay\`.
-- Single-choice answers auto-advance by default after 280 ms, including values set through a custom question slot. Empty values, the last step, disabled state, and active async work never auto-advance.
+- Single-choice answers auto-advance by default after 280 ms, including values set through a custom question slot. Empty values, anything typed or chosen through "Other…", the last step, disabled state, and active async work never auto-advance.
+- Keyboard: number keys 1–9 pick (single) or toggle (multiple) the active question's options, with "Other…" last; digits typed into a text field stay text. When focus is on the question's options, the picked option takes focus and the Tab stop, as an arrow key does in a radio group (picking "Other…" focuses its text field). Enter on a choice or a one-line field continues or submits; in a textarea, Ctrl/Cmd+Enter does. When the step changes with focus inside it, focus moves to the new step's first control (or to the step itself when it has none, such as a file step, where Enter also continues or submits), so the keys keep working step after step. A consumer \`onkeydown\` runs first and \`preventDefault()\` cancels these keys.
 - \`disabled\` blocks all controls. \`submitting\` combines with internal async submit/discard state.
 
 ## Validation and actions
 
-The default required message is \`Answer required.\`. \`requiredMessage\` accepts either a string or a per-question formatter. Primary navigation validates the active question; final submission finds the first missing required answer and moves to it. Previous/next icon controls remain available for explicit navigation.
+The default required message is \`Answer required.\`. \`requiredMessage\` accepts either a string or a per-question formatter. It renders once, in the danger colour, under the question; the options themselves stay neutral and the choice group gets \`aria-invalid\` and \`aria-describedby\`. Primary navigation validates the active question; final submission finds the first missing required answer and moves to it. The step dots (8px dots inside 24px pointer targets, labelled "Go to question N") and the primary action navigate; a single question shows no pager. \`previousLabel\` is deprecated: the default footer no longer renders previous/next arrow buttons.
 
 \`onSubmit\` receives typed \`answers\`, the raw \`values\` map, and the source \`questions\`. \`onDiscard\` adds the optional dismiss action. Async submit/discard exceptions and file rejection messages render visibly instead of being swallowed.
 
@@ -58,8 +59,7 @@ The default required message is \`Answer required.\`. \`requiredMessage\` accept
     {
       id: 'notes',
       type: 'text',
-      title: 'Add constraints',
-      required: false
+      title: 'Add constraints'
     }
   ]}
   bind:value={answers}
@@ -67,11 +67,29 @@ The default required message is \`Answer required.\`. \`requiredMessage\` accept
 />
 \`\`\`
 
+## Header
+
+The header shows the \`requester\` ("Asked by …") above a semibold \`title\` (default "Answer request") and the optional \`context\`.
+
+## Answered summary
+
+Once a request is complete, keep a compact record in the transcript instead of a raw tool row. \`AIAskUserQuestionSummary\` renders question → chosen labels (option ids become labels, "Other…" and text answers show as typed, files by name, skipped questions read "Skipped"); \`summarizeAIAskAnswers(questions, values)\` returns the same pairs as data.
+
+\`\`\`svelte
+<script lang="ts">
+  import { AIAskUserQuestionSummary } from './index.ts';
+</script>
+
+<AIAskUserQuestionSummary {questions} value={submittedValues} />
+\`\`\`
+
+Props: \`questions\`, \`value\`, \`title\` (string, or \`false\` to hide the "Your answers" heading), \`showSkipped\` (default true), \`ref\`, \`class\`, \`theme\` (summary, summaryTitle, summaryList, summaryItem, summaryQuestion, summaryAnswer).
+
 ## Composition
 
 \`header\`, \`footer\`, \`children\`, and \`empty\` receive \`AIAskUserQuestionState\`: questions, value, active question/index, visible error, working flags, first/last flags, and \`goTo\`, \`previous\`, \`next\`, \`submit\`, and \`discard\` actions.
 
 The \`question\` slot receives \`{ question, value, setValue }\`. Its setter preserves central validation, change callbacks, and single-choice auto-advance; no public compound subcomponents are required.
 
-The root forwards native div attributes and exposes bindable \`ref\`, \`class\`, and \`theme\`. Theme parts cover root, header text/progress group/steps, the body region, step content, question title and description, textarea, option/file regions, empty/error states, and footer.
+The root forwards native div attributes and exposes bindable \`ref\`, \`class\`, and \`theme\`. Theme parts cover root, header text/requester/progress group/steps, the body region, step content, question title, required marker and description, textarea, option/other/file regions, the per-question error, the submit-failure alert, empty state, footer, and the summary parts.
 `;

package/dist/components/AIAskUserQuestion/aiAskUserQuestion.props.d.ts

@@ -1,3 +1,4 @@
+import type { Sizes } from '../../types/theme.js';
 import type { Slot } from '../Slot/slot.js';
 import type { WithAttachments } from '../../types/props.js';
 import type { AIAskUserQuestionThemeProps } from './aiAskUserQuestion.theme.js';
@@ -12,18 +13,32 @@ type AIQuestionBase = {
     id: string;
     title: string;
     description?: string;
+    /** Blocks continuing until answered and shows a required marker. Questions are optional by default. */
     required?: boolean;
 };
+type AIChoiceQuestionOther = {
+    /**
+     * Adds a free-text "Other…" choice after the options. Its text is stored in the answer as
+     * typed: the single answer string, or the last entry of the multiple answer array. Editing it
+     * never auto-advances. The answer stays a plain string, so text equal to an option id reads
+     * as that option once the flow is gone (in `summarizeAIAskAnswers` or a restored `value`).
+     */
+    showOther?: boolean;
+    /** Label of the "Other…" choice. */
+    otherLabel?: string;
+    /** Placeholder of the "Other…" text field. */
+    otherPlaceholder?: string;
+};
 export type AITextQuestion = AIQuestionBase & {
     type?: 'text';
     placeholder?: string;
     rows?: number;
 };
-export type AISingleQuestion = AIQuestionBase & {
+export type AISingleQuestion = AIQuestionBase & AIChoiceQuestionOther & {
     type: 'single';
     options: readonly AIQuestionOption[];
 };
-export type AIMultipleQuestion = AIQuestionBase & {
+export type AIMultipleQuestion = AIQuestionBase & AIChoiceQuestionOther & {
     type: 'multiple';
     options: readonly AIQuestionOption[];
 };
@@ -63,6 +78,35 @@ export type AIAskUserQuestionSubmitPayload = {
     values: AIAskAnswers;
     questions: readonly AIAskQuestion[];
 };
+/** One answered (or skipped) question of a completed request, ready to display. */
+export type AIAskUserQuestionSummaryItem = {
+    question: AIAskQuestion;
+    questionId: string;
+    /** Chosen option labels, typed text, or file names; empty when the question was skipped. */
+    labels: string[];
+    answered: boolean;
+};
+export type AIAskUserQuestionSummaryProps = WithAttachments<Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'class' | 'title'> & {
+    /** Bindable reference to the summary root. */
+    ref?: HTMLDivElement | null;
+    /** Type and icon scale: `small`, `normal` (default) or `large`, matching AIMessage sizes. AIThread passes its `messageSize`. */
+    size?: Sizes;
+    /** The questions of the completed request. */
+    questions: readonly AIAskQuestion[];
+    /**
+     * The submitted answers keyed by question id.
+     * @readonly-value The summary displays a completed request's answers and never edits them.
+     */
+    value: AIAskAnswers;
+    /** Heading above the answers; `false` hides it. Defaults to the localized "Your answers". */
+    title?: string | false;
+    /** Shows skipped questions with a "Skipped" note. @default true */
+    showSkipped?: boolean;
+    /** Class applied to the summary root. */
+    class?: string;
+    /** Theme overrides for the shared question theme, including the summary parts. */
+    theme?: AIAskUserQuestionThemeProps;
+}>;
 export type AIAskUserQuestionQuestionState = {
     question: AIAskQuestion;
     value: AIAskAnswer | undefined;
@@ -104,13 +148,20 @@ export type AIAskUserQuestionProps = WithAttachments<Omit<HTMLAttributes<HTMLDiv
     autoAdvanceDelay?: number;
     /** Svelte Pro-compatible alias for `autoAdvanceDelay`. */
     autoAdvanceSingleDelay?: number;
+    /**
+     * Adds a free-text "Other…" choice to every single- and multiple-choice question, so the
+     * user can always answer in their own words. A question's own `showOther` wins. File
+     * questions are left as they are: their answer is files, not text.
+     * @default true
+     */
+    showOther?: boolean;
     /** Disables answer controls and actions. */
     disabled?: boolean;
     /** Marks submission as externally in progress and disables the complete flow. */
     submitting?: boolean;
     /** Heading for the complete answer request. */
     title?: string;
-    /** Optional name of the model, tool, or agent requesting the answers. */
+    /** Optional name of the model, tool, or agent requesting the answers, shown above the title. */
     requester?: string;
     /** Optional context displayed above the active question. */
     context?: string;
@@ -120,10 +171,16 @@ export type AIAskUserQuestionProps = WithAttachments<Omit<HTMLAttributes<HTMLDiv
     submittingLabel?: string;
     /** Optional discard action label. */
     discardLabel?: string;
-    /** Previous-step action label. */
+    /**
+     * Previous-step action label.
+     * @deprecated The default footer no longer renders previous/next arrow buttons: the step dots
+     * and the primary action navigate. Custom footers can still call `previous()`.
+     */
     previousLabel?: string;
-    /** Next-step action label. */
+    /** Primary action label before the last question. */
     nextLabel?: string;
+    /** Primary action label on an optional, unanswered question before the last one. */
+    skipLabel?: string;
     /** Title used by the default empty state. Takes precedence over `emptyTitle`. */
     emptyLabel?: string;
     /** Svelte Pro-compatible alias for `emptyLabel`. */