entasis 0.11.0 → 0.13.0

package/dist/components/Toast/Toast.svelte

@@ -12,8 +12,11 @@
 	import { mergeToastTheme, useToastTheme, type ToastThemeProps } from './toast.theme.js';
 	import type { WithAttachments } from '../../types/props.js';
 	import { useI18n } from '../../i18n/context.svelte.js';
-	import { useDrag } from '../../utils/useDrag.svelte.js';
-	import { untrack } from 'svelte';
+	import { tick, untrack } from 'svelte';
+	import { createPointerDrag } from '../../utils/pointerDrag.js';
+	import { createVelocityTracker } from '../../utils/swipeVelocity.js';
+	import { composeHandlers } from '../../utils/handlers.js';
+	import { useTheme } from '../Theme/theme.state.svelte.js';
 
 	let {
 		toast,
@@ -66,22 +69,50 @@
 	);
 
 	const in_out = fso();
+	const uid = $props.id();
+	const titleId = `${uid}-title`;
+	const descriptionId = `${uid}-description`;
 
-	const onPointerEnter = () => {
+	// A tap fires compatibility mouse events and a `pointerenter`, but is not a hover: no
+	// `pointermove` follows it that would ever release the stack again.
+	const onPointerEnter = (event: PointerEvent) => {
 		const toaster = toast.toaster;
 		const position = toast.opts.position;
-		if (!toaster || toaster.hovering === position) return;
-		toaster.hovering = position;
+		if (!toaster || event.pointerType === 'touch' || toaster.hovering === position) return;
+		toaster.setHovering(position);
 		updateArea();
-		toaster.toggleTimers(position, 'pause');
+	};
+
+	// Keyboard focus holds the stack's timers, as hover does; a click or tap that focuses the toast
+	// does not (`:focus-visible` is what tells them apart).
+	const isFocusVisible = (target: EventTarget | null) => {
+		if (!(target instanceof Element)) return false;
+		try {
+			return target.matches(':focus-visible');
+		} catch {
+			// No `:focus-visible`: every focus counts, so a keyboard user is never left behind.
+			return true;
+		}
+	};
+	const onFocusIn = (event: FocusEvent) => {
+		const toaster = toast.toaster;
+		if (!toaster) return;
+		toaster.setFocused(isFocusVisible(event.target) ? toast : null);
+	};
+	const onFocusOut = (event: FocusEvent) => {
+		// Moving between the toast's own controls keeps the hold.
+		if (event.relatedTarget instanceof Node && toast.element?.contains(event.relatedTarget)) return;
+		toast.toaster?.setFocused(null, toast);
 	};
 
 	// --- Swipe / drag to dismiss ------------------------------------------------
 	// The toast is dragged toward its anchored screen edge: left/right corners swipe
 	// horizontally, center positions swipe vertically. Dragging the other way meets
-	// resistance. Past the threshold it dismisses — the exit transition continues
-	// from the dragged position since the swipe matches the position's outro.
+	// resistance. Past the threshold, or released in a flick toward the edge, it dismisses —
+	// the exit transition continues from the dragged position since the swipe matches the
+	// position's outro.
 	const SWIPE_THRESHOLD = 45; // px past which a release dismisses
+	const FLICK_VELOCITY = 0.4; // px/ms toward the edge at which a shorter release dismisses
 	const isBanner = $derived(
 		toast.opts.position === 'banner-top' || toast.opts.position === 'banner-bottom'
 	);
@@ -98,41 +129,144 @@
 	const swipeEnabled = $derived(!!toast.opts.dismissible && toast.opts.swipeToDismiss !== false);
 
 	let dragOffset = $state(0);
-	let dragging = $state(false);
-	let dragStartX = 0;
-	let dragStartY = 0;
+	// The click that ends a drag is not a press on the toast (`closeOnClick`). Set when a drag
+	// ends; the click consumes it, and the next press clears one that no click followed.
+	let suppressClick = false;
+	const tracker = createVelocityTracker();
+	const axisPos = (event: PointerEvent) => (swipe.axis === 'x' ? event.clientX : event.clientY);
+
+	// The press, or the swipe it became, ends: the stack's timers resume unless something else
+	// holds them.
+	const release = () => {
+		toast.dragging = false;
+		if (toast.pressed) {
+			toast.pressed = false;
+			toast.toaster?.syncHolds();
+		}
+	};
+	// Pressing a toast's own controls (action buttons, the close button, a link in its text) acts
+	// on them; only the surface of the toast starts a swipe.
+	const SWIPE_IGNORED =
+		'button, a[href], input, select, textarea, label, [role="button"], [data-swipe-ignore]';
+
+	// A toast re-added with the id of one still animating out takes this item over. It must
+	// not inherit the swipe that dismissed its predecessor, or it rests off its slot.
+	$effect.pre(() => {
+		if (!toast) return;
+		dragOffset = 0;
+		untrack(release);
+	});
 
-	const drag = useDrag({
-		get isActive() {
-			return swipeEnabled;
+	// Primary button only; a cancelled touch or a lost capture snaps the toast back. A mouse
+	// released outside the window ends the drag where the button was last held, so it dismisses
+	// or snaps back by the same rule as a normal release.
+	const dragAttachment = createPointerDrag({
+		disabled: () => !swipeEnabled,
+		canStart: (event) => {
+			const control = event.target instanceof Element ? event.target.closest(SWIPE_IGNORED) : null;
+			return !control || !toast.element?.contains(control);
 		},
-		onDragStart: (e) => {
-			dragStartX = e.clientX;
-			dragStartY = e.clientY;
-			dragging = true;
+		// `touch-action` keeps the page scrolling along the axis the swipe does not use, so the
+		// browser has to be left to govern touch panning around the gesture.
+		preventTouchMove: false,
+		// The toast holds buttons, not just a handle: the pointer is captured only once the press
+		// becomes a drag, so a press that never travels keeps its click.
+		capture: 'on-activate',
+		// A press that travels mostly across the swipe axis is spent: it never drags the toast.
+		axis: () => swipe.axis,
+		onDown: ({ event }) => {
+			// A press holds the stack's timers, so a toast does not vanish under a finger.
+			toast.pressed = true;
+			toast.toaster?.syncHolds();
+			suppressClick = false;
+			tracker.reset();
+			tracker.add(axisPos(event), event.timeStamp);
 		},
-		onDrag: (e) => {
-			let delta = swipe.axis === 'x' ? e.clientX - dragStartX : e.clientY - dragStartY;
+		// Attributed to the swipe axis (either way along it): the drag starts.
+		shouldActivate: () => true,
+		onStart: ({ node }) => {
+			toast.dragging = true;
+			// A mouse press that travelled before it became a drag may have begun selecting text.
+			const selection = window.getSelection();
+			if (selection && !selection.isCollapsed && node.contains(selection.anchorNode)) {
+				selection.removeAllRanges();
+			}
+		},
+		onMove: ({ event, deltaX, deltaY }) => {
+			let delta = swipe.axis === 'x' ? deltaX : deltaY;
 			// Rubber-band when dragging away from the dismiss direction.
 			if (delta * swipe.dir < 0) delta /= 4;
 			dragOffset = delta;
+			tracker.add(axisPos(event), event.timeStamp);
 		},
-		onDragEnd: () => {
-			dragging = false;
-			if (dragOffset * swipe.dir > SWIPE_THRESHOLD) {
+		onEnd: ({ event }) => {
+			release();
+			suppressClick = true;
+			tracker.add(axisPos(event), event.timeStamp);
+			const towardEdge = dragOffset * swipe.dir;
+			const flick = tracker.velocity(event.timeStamp) * swipe.dir > FLICK_VELOCITY;
+			if (towardEdge > SWIPE_THRESHOLD || (towardEdge > 0 && flick)) {
 				toast.remove();
 			} else {
 				dragOffset = 0; // snap back (animated by the CSS transition)
 			}
+		},
+		onCancel: () => {
+			release();
+			dragOffset = 0;
 		}
 	});
 
-	// Stable attachment; wires pointerdown on the toast when swipe is enabled.
-	const dragReference = (node: HTMLElement) => untrack(() => drag.reference?.(node));
+	// The toast is announced through the Toaster's persistent live regions rather than as a live
+	// region of its own, which screen readers often miss when it is inserted already filled in.
+	// Announces on arrival and again whenever the toast is updated, with the text as rendered.
+	let contentElement = $state<HTMLElement>();
+
+	// A toast shown again while it is on screen bounces once. It animates the `scale` property, which
+	// composes with the `transform` the stack and swipe write, and stays still under reduced motion.
+	const motionTheme = useTheme();
+	let seenAttention = untrack(() => toast.attentionKey);
+	$effect(() => {
+		const key = toast.attentionKey;
+		if (key === seenAttention) return;
+		seenAttention = key;
+		const element = untrack(() => toast.element);
+		if (!element || typeof element.animate !== 'function') return;
+		if (motionTheme?.preferReducesMotion) return;
+		element.animate([{ scale: '1' }, { scale: '1.04' }, { scale: '0.98' }, { scale: '1' }], {
+			duration: 360,
+			easing: 'cubic-bezier(0.34, 1.56, 0.64, 1)'
+		});
+	});
+	$effect(() => {
+		void toast.opts.title;
+		void toast.opts.description;
+		void toast.opts.important;
+		void toast.updateKey;
+		const toaster = toast.toaster;
+		const important = !!toast.opts.important;
+		let cancelled = false;
+		tick().then(() => {
+			if (cancelled || !contentElement) return;
+			const text = [...contentElement.children]
+				.map((part) => part.textContent?.trim())
+				.filter(Boolean)
+				.join('. ');
+			toaster?.announce(text, important);
+		});
+		return () => (cancelled = true);
+	});
+
+	// A toast pushed past `visibleToasts` turns inert, and focus on it would drop to the page.
+	$effect.pre(() => {
+		if (hidden) untrack(() => toast.toaster?.moveFocusFrom(toast));
+	});
 
 	// Fade the toast as it's dragged toward dismissal.
 	const dragOpacity = $derived(
-		dragging && dragOffset * swipe.dir > 0 ? Math.max(0.2, 1 - (dragOffset * swipe.dir) / 140) : 1
+		toast.dragging && dragOffset * swipe.dir > 0
+			? Math.max(0.2, 1 - (dragOffset * swipe.dir) / 140)
+			: 1
 	);
 </script>
 
@@ -141,8 +275,10 @@
 	bind:this={toast.element}
 	bind:clientHeight={toast.height}
 	{...attachments}
-	{@attach dragReference}
+	{@attach dragAttachment}
 	onpointerenter={onPointerEnter}
+	onfocusin={onFocusIn}
+	onfocusout={onFocusOut}
 	ontransitionend={(e) => {
 		if (e.propertyName === 'translate' && toast.hovered && index === 0) {
 			updateArea();
@@ -160,16 +296,17 @@
 	}}
 	out:in_out={toast.animations.out}
 	in:in_out={toast.animations.in}
-	aria-live={toast.opts.important ? 'assertive' : 'polite'}
-	aria-atomic="true"
-	role={toast.opts.important ? 'alert' : 'status'}
+	data-update-key={toast.updateKey}
+	role="group"
+	aria-labelledby={toast.opts.title ? titleId : toast.opts.description ? descriptionId : undefined}
+	aria-describedby={toast.opts.title && toast.opts.description ? descriptionId : undefined}
 	tabIndex={hidden ? -1 : 0}
 	inert={hidden}
 	style:opacity={hidden ? 0 : dragOpacity}
 	style:pointer-events={hidden ? 'none' : undefined}
-	style:touch-action={swipeEnabled ? 'none' : undefined}
-	style:cursor={dragging ? 'grabbing' : swipeEnabled ? 'grab' : undefined}
-	style:user-select={dragging ? 'none' : undefined}
+	style:touch-action={swipeEnabled ? (swipe.axis === 'x' ? 'pan-y' : 'pan-x') : undefined}
+	style:cursor={toast.dragging ? 'grabbing' : swipeEnabled ? 'grab' : undefined}
+	style:user-select={toast.dragging ? 'none' : undefined}
 	class={classes.root({
 		richColors: toast.opts.richColors,
 		color: toast.opts.color,
@@ -179,9 +316,14 @@
 	style:scale={toast.stacked ? Math.pow(0.97, reversedIndex).toFixed(4) : '1'}
 	style:translate="{swipe.axis === 'x' ? dragOffset : 0}px {toast.translateY +
 		(swipe.axis === 'y' ? dragOffset : 0)}px"
-	style:transition={dragging ? 'none' : undefined}
+	style:transition={toast.dragging ? 'none' : undefined}
 	style={toast.actualizedPosition[2]}
-	onclick={toast.opts.dismissible && toast.opts.closeOnClick ? () => toast.remove() : null}
+	onclick={toast.opts.dismissible && toast.opts.closeOnClick
+		? () => {
+				if (suppressClick) suppressClick = false;
+				else toast.remove();
+			}
+		: null}
 >
 	{#if icon || toast.loading}
 		<div
@@ -199,6 +341,7 @@
 		</div>
 	{/if}
 	<div
+		bind:this={contentElement}
 		class={classes.content({
 			size: toast.opts.size,
 			color: toast.opts.color,
@@ -212,6 +355,7 @@
 				richColors: toast.opts.richColors
 			})}
 			render={toast.opts.title}
+			attrs={{ id: titleId }}
 		/>
 		<Slot
 			class={classes.description({
@@ -220,6 +364,7 @@
 				richColors: toast.opts.richColors
 			})}
 			render={toast.opts.description}
+			attrs={{ id: descriptionId }}
 		/>
 	</div>
 	{#if toast.opts.actions?.length}
@@ -230,12 +375,12 @@
 					size="small"
 					variant="soft"
 					{...buttonProps}
-					onclick={(event) => {
-						onclick?.(event);
+					onclick={composeHandlers(onclick, () => {
 						// A manual dismiss fires onDismiss, never onAutoDismiss — so an Undo
-						// action here cancels the deferred commit just by closing early.
+						// action here cancels the deferred commit just by closing early. The
+						// action's own handler runs first; `event.preventDefault()` keeps the toast.
 						if (dismiss !== false) toast.remove();
-					}}
+					})}
 				>
 					{label}
 				</Button>

package/dist/components/Toast/Toaster.svelte

@@ -100,33 +100,37 @@
 	const setPolygon = useSafeArea({
 		isActive: () => !!toaster.hovering,
 		offset: 30,
-		callback: () => {
-			if (toaster.hovering) toaster.toggleTimers(toaster.hovering, 'resume');
-			toaster.hovering = null;
-		}
+		callback: () => toaster.setHovering(null)
 	});
 
 	const classes = $derived(useToastTheme(theme));
 	// F6 focuses the notification region from anywhere (Sonner's convention).
-	const hotkey = useHotKey({
-		hotKeys: { f6: () => toaster.element?.focus({ preventScroll: true }) },
+	// The window listener alone: attaching the hotkey's `reference` would make the always-present
+	// region a tab stop.
+	useHotKey({
+		hotKeys: { f6: () => toaster.focusRegion() },
 		isActive: true,
 		onWindow: true
 	});
 </script>
 
-<!-- A landmark region (not a dialog) so live announcements are not wrapped in a dialog role;
-     `data-live-region` keeps it outside any modal's `inert` sweep. F6 jumps to it. -->
+<!-- A landmark region (not a dialog), always rendered: it hosts the persistent live regions that
+     announce toasts, which must exist before the first one. It is empty and click-through while no
+     toast shows. `data-live-region` keeps it outside any modal's `inert` sweep. F6 jumps to it. -->
+<!-- svelte-ignore a11y_no_redundant_roles -->
 <section
 	bind:this={toaster.element}
 	tabIndex={-1}
 	role="region"
-	hidden={!toaster.isOpen}
+	{...direction ? { dir: direction } : {}}
 	aria-label={t.notifications}
 	data-live-region
+	data-open={toaster.isOpen ? '' : undefined}
 	class={classes.toaster()}
 	data-hovering={toaster.hovering}
-	{@attach hotkey.reference}
+	onfocusin={toaster.onRegionFocusIn}
+	onfocusout={toaster.onRegionFocusOut}
+	{@attach toaster.liveRegions.host}
 >
 	{#each toaster.toasts as toast (toast.id)}
 		<Toast

package/dist/components/Toast/index.d.ts

@@ -3,3 +3,4 @@ export { toast } from './toast.state.svelte.js';
 export { default as Toaster } from './Toaster.svelte';
 export { setToastTheme, useToastTheme, type ToastTheme, type ToastThemeProps } from './toast.theme.js';
 export type { ToastProps, ToasterProps } from './toast.props.js';
+export type { ToastPromiseOptions, ToastUpdate, ToastUpdater } from './toast.state.svelte.js';

package/dist/components/Toast/toast.mcp.d.ts

@@ -1 +1 @@
-export declare const toastDescription = "\nThe toast function displays non-blocking notification messages to the user. It provides color-based methods (primary, secondary, success, warning, danger, info, neutral) that each return a Toast instance.\n\n\n**Usage:**\n```typescript\nimport { toast } from 'entasis/toast';\n\n// Basic toast with a color variant\ntoast.success({\n  title: 'Success!',\n  description: 'Your changes have been saved.',\n  duration: 4000\n});\n\n// Toast with custom position\ntoast.danger({\n  title: 'Error',\n  description: 'Something went wrong.',\n  position: 'top-center',\n  duration: 5000\n});\n\n// Toast with loading state\ntoast.info({\n  title: 'Processing',\n  description: 'Please wait...',\n  loading: true,\n  duration: false // Don't auto-close\n});\n\n// Toast with callbacks\ntoast.warning({\n  title: 'Warning',\n  description: 'This action cannot be undone.',\n  duration: 6000,\n  onAfterOpen: (payload) => console.log('Toast opened:', payload.id),\n  onDismiss: (payload) => console.log('Toast dismissed:', payload.id),\n  onAutoDismiss: (payload) => console.log('Toast timed out:', payload.id)\n});\n```\n\n**Available Color Methods:**\n- `toast.primary(options)` - Primary color variant\n- `toast.secondary(options)` - Secondary color variant\n- `toast.success(options)` - Success/green variant\n- `toast.warning(options)` - Warning/yellow variant\n- `toast.danger(options)` - Danger/red variant\n- `toast.info(options)` - Info/blue variant\n- `toast.neutral(options)` - Neutral color variant\n\n**Parameters (all optional):**\n- `title` (Slot or string): The toast title text\n- `description` (Slot or string) optional: The toast description/message text\n- `position` (ToastPosition, optional): Position on screen. Options: `'top-left'`, `'top-right'`, `'top-center'`, `'bottom-left'`, `'bottom-right'`, `'bottom-center'`, plus `'banner-top'` / `'banner-bottom'` which render a full screen-width bar flush to the top/bottom edge. Default: `'bottom-right'`. Swipe axis follows the anchor: left/right corners swipe horizontally, center + banner positions swipe vertically.\n- `duration` (number | false, optional): Time in milliseconds before auto-closing. Set to `false` to disable auto-close. Default: 4000ms\n- `closeOnClick` (boolean, optional): If true, clicking the toast closes it. Default: inherited from Toaster\n- `showCloseIcon` (boolean, optional): If true, shows a close button. Default: inherited from Toaster\n- `dismissible` (boolean, optional): If false, prevents user from dismissing. Default: inherited from Toaster\n- `richColors` (boolean, optional): If true, uses richer color variants. Default: inherited from Toaster\n- `loading` (boolean, optional): If true, shows a loading spinner using Theme's global `spinnerVariant`\n- `progress` (boolean, optional): If true, shows a bar counting down the remaining duration (pauses on hover). Only appears when the toast has a finite `duration`. Can also be set on `<Toaster progress />` as a default.\n- `swipeToDismiss` (boolean, optional, default true): Drag the toast toward its anchored screen edge (down for bottom-*, up for top-*) past a threshold to dismiss it; dragging the other way rubber-bands. A manual dismiss fires `onDismiss`, not `onAutoDismiss`.\n- `closeOnClick` (boolean, optional, default false): Dismiss when the toast body is clicked. Off by default now that swipe-to-dismiss exists; the close icon and swipe are the primary dismiss affordances.\n- `size` (Sizes, optional): Size of the toast \u2014 scales padding, corner radius, type and icon. Options: `'small'`, `'normal'`, `'large'` (default `'normal'`). Can be defaulted for all toasts with `<Toaster size=\"...\" />`.\n- `prefix` (Slot | false, optional): Content before the text. `false` hides the default icon\n- `suffix` (Slot, optional): Content to display after the toast text\n- `actions` (ToastAction[], optional): Buttons rendered inside the toast. `ToastAction` is full Button props plus `content` (the label) and `dismiss` (default true \u2014 clicking dismisses the toast). Each button's `onclick` runs with the native MouseEvent, then the toast fires `onDismiss`.\n- `closeIcon` (Slot, optional): Custom close button component\n- `icon` (string, optional): Icon name to display before the toast text\n- `important` (boolean, optional): Uses `role=\"alert\"` + assertive announcements for screen readers\n- `transition` (FSOProps, optional): Enter/exit transition override for this toast\n- `theme` (ToastThemeProps, optional): Theme overrides for this toast alone, layered over the `<Toaster theme>` object (`base` classes are appended, so the per-toast ones win)\n- `id` (string, optional): Custom ID for the toast. Auto-generated if not provided\n- `onAfterOpen` (function, optional): Called once the toast finishes entering: `(payload: Toast) => void`\n- `onDismiss` (function, optional): Called on manual dismiss (close button, an action, or `toast.remove()`). Not called on timeout: `(payload: Toast) => void`\n- `onAutoDismiss` (function, optional): Called only when the toast times out after `duration`. Put deferred irreversible work here; it never runs if the toast is dismissed first: `(payload: Toast) => void`\n\n### Undo / deferred-commit pattern\n\nRemove the item from the UI immediately, defer the real irreversible action to `onAutoDismiss`, and offer an `Undo` action. Undo dismisses the toast manually, so `onAutoDismiss` never fires:\n\n```ts\nfunction deleteItemWithUndo(item) {\n  removeFromUI(item);                       // optimistic\n  toast.neutral({\n    title: `Deleted \"${item.name}\"`,\n    duration: 5000,\n    actions: [{ content: 'Undo', onclick: () => restore(item) }],\n    onAutoDismiss: () => commitDelete(item)   // runs only if not undone\n  });\n}\n```\n\n**Mounting order:** `toast()` never throws when no `<Toaster />` is mounted yet \u2014 the toast is queued and shown by the first Toaster that mounts. In development, a single `console.warn` reports a queue that is still waiting a tick later. Dismissing a queued toast drops it from the queue, and a `toast()` call made during SSR is discarded instead of queued.\n\n**Returns:**\nA `Toast` instance that you can use to programmatically control the root:\n- `toast.remove()` - Remove the toast manually\n- `toast.id` - Unique identifier\n- `toast.opts` - Toast options\n\n**Notes:**\n- Toasts are non-blocking and don't prevent user interaction\n- The toaster is a `role=\"region\"` landmark named \"Notifications\" (not a `<dialog>`); pressing F6 anywhere moves focus into it. Each toast is `role=\"status\"`, or `role=\"alert\"` when `important`\n- Toasts stacked away behind the front one are `inert` (rather than `aria-hidden`), so they take no clicks or tab stops until they surface\n- Multiple toasts can be displayed simultaneously and will stack based on position\n- Toasts pause their auto-close timer when hovered\n- Toasts can be dismissed by clicking the close icon, clicking the toast (if `closeOnClick` is true), or automatically after the duration expires\n\n## Theme Customization\n\nThe Toast component uses a theme object that can be customized using the `theme` prop in toast options or by setting a global theme.\n\n### Theme Structure\n\nThe theme object contains the following parts:\n- **motion**: Enter/exit transition preset, keyed by `position` (each toast flies in from the\n  edge it is pinned to). Takes `in` / `out` FSO params plus a `duration` / `easing` motion\n  token; overrides ladder `<Theme components={{ toast }}>` \u2192 `setToastTheme` \u2192 `theme.motion`\n  \u2192 the Toaster's `transition` prop \u2192 a toast's own `transition`\n- **root**: Main toast container styles\n- **prefix**: Prefix icon/content styles\n- **suffix**: Suffix content styles\n- **content**: Content wrapper styles\n- **closeIcon**: Close button icon styles\n- **title**: Title text styles\n- **description**: Description text styles\n\n### Available Variants\n\n**root**:\n- base: Base classes for toast container\n- Variants:\n  - richColors: boolean - Rich color variant styling\n  - color: Color variants\n  - size: 'small' | 'normal' | 'large' - Toast size\n\n**prefix**:\n- base: Base classes for prefix content\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Icon size\n  - color: Color variants\n  - richColors: boolean - Rich color variant styling\n\n**suffix**:\n- base: Base classes for suffix content\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Content size\n  - color: Color variants\n  - richColors: boolean - Rich color variant styling\n\n**content**:\n- base: Base classes for content wrapper\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Content size\n  - color: Color variants\n  - richColors: boolean - Rich color variant styling\n\n**closeIcon**:\n- base: Base classes for close button\n- Variants:\n  - richColors: boolean - Rich color variant styling\n  - color: Color variants\n\n**title**:\n- base: Base classes for title text\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Text size\n  - color: Color variants\n  - richColors: boolean - Rich color variant styling\n\n**description**:\n- base: Base classes for description text\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Text size\n  - color: Color variants\n  - richColors: boolean - Rich color variant styling\n\n### Usage Examples\n\n**Basic Theme Override**:\n```typescript\nimport { toast } from 'entasis/toast';\n\ntoast.success({\n  title: 'Success',\n  description: 'Operation completed',\n  theme: {\n    root: {\n      base: 'rounded-xl raised-5',\n      size: {\n        normal: 'px-4 py-3'\n      }\n    }\n  }\n});\n```\n\n**Custom Toast Styling**:\n```typescript\ntoast.danger({\n  title: 'Error',\n  description: 'Something went wrong',\n  theme: {\n    root: {\n      base: 'border-2 border-red-500',\n      richColors: {\n        true: 'bg-red-50 border-red-500'\n      }\n    },\n    title: {\n      base: 'font-bold text-red-900'\n    }\n  }\n});\n```\n\n**Global Theme Setting**:\n```svelte\n<script>\n  import { setToastTheme } from './index.ts';\n  \n  setToastTheme({\n    root: {\n      base: 'rounded-lg raised-4',\n      size: {\n        normal: 'px-3 py-2'\n      }\n    },\n    title: {\n      base: 'font-semibold'\n    }\n  });\n</script>\n```\n";
+export declare const toastDescription = "\nThe toast function displays non-blocking notification messages to the user. It provides color-based methods (primary, secondary, success, warning, danger, info, neutral) that each return a Toast instance.\n\n\n**Usage:**\n```typescript\nimport { toast } from 'entasis/toast';\n\n// Basic toast with a color variant\ntoast.success({\n  title: 'Success!',\n  description: 'Your changes have been saved.',\n  duration: 4000\n});\n\n// Toast with custom position\ntoast.danger({\n  title: 'Error',\n  description: 'Something went wrong.',\n  position: 'top-center',\n  duration: 5000\n});\n\n// Toast with loading state\ntoast.info({\n  title: 'Processing',\n  description: 'Please wait...',\n  loading: true,\n  duration: false // Don't auto-close\n});\n\n// Toast with callbacks\ntoast.warning({\n  title: 'Warning',\n  description: 'This action cannot be undone.',\n  duration: 6000,\n  onAfterOpen: (payload) => console.log('Toast opened:', payload.id),\n  onDismiss: (payload) => console.log('Toast dismissed:', payload.id),\n  onAutoDismiss: (payload) => console.log('Toast timed out:', payload.id)\n});\n```\n\n**Available Color Methods:**\n- `toast.primary(options)` - Primary color variant\n- `toast.secondary(options)` - Secondary color variant\n- `toast.success(options)` - Success/green variant\n- `toast.warning(options)` - Warning/yellow variant\n- `toast.danger(options)` - Danger/red variant\n- `toast.info(options)` - Info/blue variant\n- `toast.neutral(options)` - Neutral color variant\n\n**Parameters (all optional):**\n- `title` (Slot or string): The toast title text\n- `description` (Slot or string) optional: The toast description/message text\n- `position` (ToastPosition, optional): Position on screen. Options: `'top-left'`, `'top-right'`, `'top-center'`, `'bottom-left'`, `'bottom-right'`, `'bottom-center'`, plus `'banner-top'` / `'banner-bottom'` which render a full screen-width bar flush to the top/bottom edge. Default: `'bottom-right'`. Swipe axis follows the anchor: left/right corners swipe horizontally, center + banner positions swipe vertically.\n- `duration` (number | false, optional): Time in milliseconds before auto-closing. Set to `false` to disable auto-close. Default: 4000ms\n- `closeOnClick` (boolean, optional): If true, clicking the toast closes it. Default: inherited from Toaster\n- `showCloseIcon` (boolean, optional): If true, shows a close button. Default: inherited from Toaster\n- `dismissible` (boolean, optional): If false, prevents user from dismissing. Default: inherited from Toaster\n- `richColors` (boolean, optional): If true, uses richer color variants. Default: inherited from Toaster\n- `loading` (boolean, optional): If true, shows a loading spinner using Theme's global `spinnerVariant`\n- `progress` (boolean, optional): If true, shows a bar counting down the remaining duration (pauses on hover, keyboard focus, a press or swipe, and while the window is inactive). Only appears when the toast has a finite `duration`. Can also be set on `<Toaster progress />` as a default.\n- `swipeToDismiss` (boolean, optional, default true): Drag the toast toward its anchored screen edge (down for bottom-*, up for top-*) past a threshold, or flick it that way, to dismiss it; dragging the other way rubber-bands. Only the primary button drags, and only from the toast's surface: a press on an action button, the close button, a link or any `[data-swipe-ignore]` element never starts a drag. A press that travels mostly across the swipe axis never moves the toast, so the page keeps scrolling along that direction (a swipeable toast sets `touch-action` to `pan-y` when it swipes sideways and `pan-x` when it swipes vertically, so a touch drag along the swipe axis of a center or banner toast swipes it instead of scrolling the page); the stack stays expanded and its timers paused while a toast is dragged; a cancelled touch snaps it back, and a mouse released outside the window ends the drag where the button was last held (it dismisses or snaps back by the same rule as a normal release); and the click that ends a drag is not a `closeOnClick` press. A manual dismiss fires `onDismiss`, not `onAutoDismiss`.\n- `closeOnClick` (boolean, optional, default false): Dismiss when the toast body is clicked. Off by default now that swipe-to-dismiss exists; the close icon and swipe are the primary dismiss affordances.\n- `size` (Sizes, optional): Size of the toast \u2014 scales padding, corner radius, type and icon. Options: `'small'`, `'normal'`, `'large'` (default `'normal'`). Can be defaulted for all toasts with `<Toaster size=\"...\" />`.\n- `prefix` (Slot | false, optional): Content before the text. `false` hides the default icon\n- `suffix` (Slot, optional): Content to display after the toast text\n- `actions` (ToastAction[], optional): Buttons rendered inside the toast. `ToastAction` is full Button props plus `content` (the label) and `dismiss` (default true \u2014 clicking dismisses the toast). Each button's `onclick` runs with the native MouseEvent, then the toast fires `onDismiss`.\n- `closeIcon` (Slot, optional): Custom close button component\n- `icon` (string, optional): Icon name to display before the toast text\n- `important` (boolean, optional): Announced through the assertive live region instead of the polite one, so screen readers interrupt for it\n- `transition` (FSOProps, optional): Enter/exit transition override for this toast\n- `theme` (ToastThemeProps, optional): Theme overrides for this toast alone, layered over the `<Toaster theme>` object (`base` classes are appended, so the per-toast ones win)\n- `dedupe` (boolean, optional, default true): Without an `id`, a toast whose color, title and description match one still on screen updates that toast (its countdown restarts) instead of stacking a duplicate, so a repeated submission shows once. It compares plain-text titles and descriptions only; a snippet, or a toast with no text, is always added. Pass `false` to opt out. An explicit `id` always wins\n- `id` (string, optional): Custom ID for the toast. Auto-generated if not provided. Calling a creator again with an id that is still on screen updates that toast instead of adding another (see Updating by id)\n- `onAfterOpen` (function, optional): Called once the toast finishes entering: `(payload: Toast) => void`\n- `onDismiss` (function, optional): Called on manual dismiss (close button, an action, or `toast.remove()`). Not called on timeout: `(payload: Toast) => void`\n- `onAutoDismiss` (function, optional): Called only when the toast times out after `duration`. Put deferred irreversible work here; it never runs if the toast is dismissed first: `(payload: Toast) => void`\n\n### Undo / deferred-commit pattern\n\nRemove the item from the UI immediately, defer the real irreversible action to `onAutoDismiss`, and offer an `Undo` action. Undo dismisses the toast manually, so `onAutoDismiss` never fires:\n\n```ts\nfunction deleteItemWithUndo(item) {\n  removeFromUI(item);                       // optimistic\n  toast.neutral({\n    title: `Deleted \"${item.name}\"`,\n    duration: 5000,\n    actions: [{ content: 'Undo', onclick: () => restore(item) }],\n    onAutoDismiss: () => commitDelete(item)   // runs only if not undone\n  });\n}\n```\n\n**Updating by id:** a creator called with the `id` of a toast that is still on screen updates that toast in place and returns the same `Toast` handle. The new options merge over the previous ones (keys you leave out keep their value; pass `undefined` to clear one), the color follows the creator you call, and the auto-dismiss timer restarts from the full `duration`. A toast with that id that is still animating out, or that was removed earlier in the same tick, is replaced by a new `Toast`: it takes the leaving toast's place a microtask later, plays its entry transition from wherever the exit had reached, and fires its own `onAfterOpen`. The old handle no longer controls it. Toasts queued before a `<Toaster />` mounts merge by id the same way.\n\n```ts\ntoast.primary({ id: 'save', title: 'Saving\u2026', loading: true, duration: false });\n// later \u2014 same id, so the toast updates in place:\ntoast.success({ id: 'save', title: 'Saved', loading: false, duration: 3000 });\n```\n\n**Changing a toast: `toast.update`, `toast.dismiss`, `toast.promise`**\n\n`update`, `dismiss` and `promise` are reserved names, not colors.\n\n- `toast.update(id, patch)` changes the toast with that id that is on screen and returns its `Toast` handle (`undefined` when there is none). `patch` is an options object, or a function that receives the toast's current options (Toaster defaults included) and returns one. Keys left out keep their value, the timer restarts from the full `duration`, and the toast's `data-update-key` attribute changes. The handle has the same method: `handle.update(patch)`. A toast that was dismissed stays dismissed: updating it does nothing, so a result that arrives after the user closed the toast never brings it back.\n- `toast.dismiss(id?)` dismisses one toast, or every toast on screen (and any still waiting for a Toaster) when called without an id. Each fires `onDismiss` once.\n- `toast.promise(promise, { loading, success, error, id? })` shows a loading toast (a spinner, no timeout, color `primary`), then turns it into the success toast (color `success`) or error toast (color `danger`) when the promise settles. Each stage is a title string, an options object, or, for `success` and `error`, a function of the result or the rejection that returns either. The text and actions of the loading stage never carry over to the result. It returns the original promise, so it can be awaited, and a rejection still rejects for the caller.\n\n```ts\nimport { toast } from 'entasis/toast';\n\nasync function save(saveRows: () => Promise<number>) {\n  const rows = await toast.promise(saveRows(), {\n    loading: { title: 'Saving\u2026', description: 'Hold on' },\n    success: (count) => ({ title: `Saved ${count} rows` }),\n    error: (error) => ({ title: 'Save failed', description: (error as Error).message })\n  });\n  return rows;\n}\n\ntoast.update('batch', (current) => ({ title: current.title + '!' }));\ntoast.dismiss(); // closes every toast\n```\n\n**Mounting order:** `toast()` never throws when no `<Toaster />` is mounted yet \u2014 the toast is queued and shown by the first Toaster that mounts. In development, a single `console.warn` reports a queue that is still waiting a tick later. Dismissing a queued toast drops it from the queue, and a `toast()` call made during SSR is discarded instead of queued.\n\n**Returns:**\nA `Toast` instance that you can use to programmatically control the root:\n- `toast.remove()` - Remove the toast manually\n- `toast.update(patch)` - Update the toast in place (see Changing a toast); ignored once the toast was dismissed\n- `toast.updateKey` - Number of updates received, rendered as `data-update-key`\n- `toast.dismissed` - Whether the toast was dismissed\n- `toast.id` - Unique identifier\n- `toast.opts` - Toast options\n\n**Notes:**\n- Toasts are non-blocking and don't prevent user interaction\n- The toaster is a `role=\"region\"` landmark named \"Notifications\" (not a `<dialog>`), always rendered and empty while no toast shows; pressing F6 anywhere moves focus into it, and Tab then reaches the toasts. Toasts are announced through two live regions inside it that exist before the first toast: a polite one, and an assertive one for `important` toasts. The text announced is the toast's rendered title and description, again whenever the toast is updated. Each toast is a labelled `role=\"group\"` (named by its title, described by its description), not a live region of its own\n- When the focused toast is dismissed, or is pushed past `visibleToasts` and turns inert, focus moves to the nearest toast that stays visible, else back to the element that was focused before F6, else to the region, instead of dropping to the page\n- Toasts stacked away behind the front one are `inert` (rather than `aria-hidden`), so they take no clicks or tab stops until they surface\n- Multiple toasts can be displayed simultaneously and will stack based on position\n- Toasts pause their auto-close timer while the pointer is over their stack (a touch tap is not a hover), while keyboard focus (`:focus-visible`) is on the stack (a mouse click or tap that focuses a toast does not pause anything), while a press or swipe is on one of its toasts, and while the browser window is blurred or its tab is hidden. The timers resume only when none of these holds them, with the time they had left. A toast shown while any of them applies starts paused\n- Toasts can be dismissed by clicking the close icon, clicking the toast (if `closeOnClick` is true), or automatically after the duration expires\n\n## Toaster props\n\n- `direction` (`'ltr' | 'rtl'`, optional): sets `dir` on the notification region, so the toasts' text and layout follow it. Inherited from the page when omitted. Positions stay physical: `left` and `right` are screen sides.\n\n## Theme Customization\n\nThe Toast component uses a theme object that can be customized using the `theme` prop in toast options or by setting a global theme.\n\n### Theme Structure\n\nThe theme object contains the following parts:\n- **motion**: Enter/exit transition preset, keyed by `position` (each toast flies in from the\n  edge it is pinned to). Takes `in` / `out` FSO params plus a `duration` / `easing` motion\n  token; overrides ladder `<Theme components={{ toast }}>` \u2192 `setToastTheme` \u2192 `theme.motion`\n  \u2192 the Toaster's `transition` prop \u2192 a toast's own `transition`\n- **root**: Main toast container styles\n- **prefix**: Prefix icon/content styles\n- **suffix**: Suffix content styles\n- **content**: Content wrapper styles\n- **closeIcon**: Close button icon styles\n- **title**: Title text styles\n- **description**: Description text styles\n\n### Available Variants\n\n**root**:\n- base: Base classes for toast container\n- Variants:\n  - richColors: boolean - Rich color variant styling\n  - color: Color variants\n  - size: 'small' | 'normal' | 'large' - Toast size\n\n**prefix**:\n- base: Base classes for prefix content\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Icon size\n  - color: Color variants\n  - richColors: boolean - Rich color variant styling\n\n**suffix**:\n- base: Base classes for suffix content\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Content size\n  - color: Color variants\n  - richColors: boolean - Rich color variant styling\n\n**content**:\n- base: Base classes for content wrapper\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Content size\n  - color: Color variants\n  - richColors: boolean - Rich color variant styling\n\n**closeIcon**:\n- base: Base classes for close button\n- Variants:\n  - richColors: boolean - Rich color variant styling\n  - color: Color variants\n\n**title**:\n- base: Base classes for title text\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Text size\n  - color: Color variants\n  - richColors: boolean - Rich color variant styling\n\n**description**:\n- base: Base classes for description text\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Text size\n  - color: Color variants\n  - richColors: boolean - Rich color variant styling\n\n### Usage Examples\n\n**Basic Theme Override**:\n```typescript\nimport { toast } from 'entasis/toast';\n\ntoast.success({\n  title: 'Success',\n  description: 'Operation completed',\n  theme: {\n    root: {\n      base: 'rounded-xl raised-5',\n      size: {\n        normal: 'px-4 py-3'\n      }\n    }\n  }\n});\n```\n\n**Custom Toast Styling**:\n```typescript\ntoast.danger({\n  title: 'Error',\n  description: 'Something went wrong',\n  theme: {\n    root: {\n      base: 'border-2 border-red-500',\n      richColors: {\n        true: 'bg-red-50 border-red-500'\n      }\n    },\n    title: {\n      base: 'font-bold text-red-900'\n    }\n  }\n});\n```\n\n**Global Theme Setting**:\n```svelte\n<script>\n  import { setToastTheme } from './index.ts';\n  \n  setToastTheme({\n    root: {\n      base: 'rounded-lg raised-4',\n      size: {\n        normal: 'px-3 py-2'\n      }\n    },\n    title: {\n      base: 'font-semibold'\n    }\n  });\n</script>\n```\n";

package/dist/components/Toast/toast.mcp.js

@@ -59,8 +59,8 @@ toast.warning({
 - \`dismissible\` (boolean, optional): If false, prevents user from dismissing. Default: inherited from Toaster
 - \`richColors\` (boolean, optional): If true, uses richer color variants. Default: inherited from Toaster
 - \`loading\` (boolean, optional): If true, shows a loading spinner using Theme's global \`spinnerVariant\`
-- \`progress\` (boolean, optional): If true, shows a bar counting down the remaining duration (pauses on hover). Only appears when the toast has a finite \`duration\`. Can also be set on \`<Toaster progress />\` as a default.
-- \`swipeToDismiss\` (boolean, optional, default true): Drag the toast toward its anchored screen edge (down for bottom-*, up for top-*) past a threshold to dismiss it; dragging the other way rubber-bands. A manual dismiss fires \`onDismiss\`, not \`onAutoDismiss\`.
+- \`progress\` (boolean, optional): If true, shows a bar counting down the remaining duration (pauses on hover, keyboard focus, a press or swipe, and while the window is inactive). Only appears when the toast has a finite \`duration\`. Can also be set on \`<Toaster progress />\` as a default.
+- \`swipeToDismiss\` (boolean, optional, default true): Drag the toast toward its anchored screen edge (down for bottom-*, up for top-*) past a threshold, or flick it that way, to dismiss it; dragging the other way rubber-bands. Only the primary button drags, and only from the toast's surface: a press on an action button, the close button, a link or any \`[data-swipe-ignore]\` element never starts a drag. A press that travels mostly across the swipe axis never moves the toast, so the page keeps scrolling along that direction (a swipeable toast sets \`touch-action\` to \`pan-y\` when it swipes sideways and \`pan-x\` when it swipes vertically, so a touch drag along the swipe axis of a center or banner toast swipes it instead of scrolling the page); the stack stays expanded and its timers paused while a toast is dragged; a cancelled touch snaps it back, and a mouse released outside the window ends the drag where the button was last held (it dismisses or snaps back by the same rule as a normal release); and the click that ends a drag is not a \`closeOnClick\` press. A manual dismiss fires \`onDismiss\`, not \`onAutoDismiss\`.
 - \`closeOnClick\` (boolean, optional, default false): Dismiss when the toast body is clicked. Off by default now that swipe-to-dismiss exists; the close icon and swipe are the primary dismiss affordances.
 - \`size\` (Sizes, optional): Size of the toast — scales padding, corner radius, type and icon. Options: \`'small'\`, \`'normal'\`, \`'large'\` (default \`'normal'\`). Can be defaulted for all toasts with \`<Toaster size="..." />\`.
 - \`prefix\` (Slot | false, optional): Content before the text. \`false\` hides the default icon
@@ -68,10 +68,11 @@ toast.warning({
 - \`actions\` (ToastAction[], optional): Buttons rendered inside the toast. \`ToastAction\` is full Button props plus \`content\` (the label) and \`dismiss\` (default true — clicking dismisses the toast). Each button's \`onclick\` runs with the native MouseEvent, then the toast fires \`onDismiss\`.
 - \`closeIcon\` (Slot, optional): Custom close button component
 - \`icon\` (string, optional): Icon name to display before the toast text
-- \`important\` (boolean, optional): Uses \`role="alert"\` + assertive announcements for screen readers
+- \`important\` (boolean, optional): Announced through the assertive live region instead of the polite one, so screen readers interrupt for it
 - \`transition\` (FSOProps, optional): Enter/exit transition override for this toast
 - \`theme\` (ToastThemeProps, optional): Theme overrides for this toast alone, layered over the \`<Toaster theme>\` object (\`base\` classes are appended, so the per-toast ones win)
-- \`id\` (string, optional): Custom ID for the toast. Auto-generated if not provided
+- \`dedupe\` (boolean, optional, default true): Without an \`id\`, a toast whose color, title and description match one still on screen updates that toast (its countdown restarts) instead of stacking a duplicate, so a repeated submission shows once. It compares plain-text titles and descriptions only; a snippet, or a toast with no text, is always added. Pass \`false\` to opt out. An explicit \`id\` always wins
+- \`id\` (string, optional): Custom ID for the toast. Auto-generated if not provided. Calling a creator again with an id that is still on screen updates that toast instead of adding another (see Updating by id)
 - \`onAfterOpen\` (function, optional): Called once the toast finishes entering: \`(payload: Toast) => void\`
 - \`onDismiss\` (function, optional): Called on manual dismiss (close button, an action, or \`toast.remove()\`). Not called on timeout: \`(payload: Toast) => void\`
 - \`onAutoDismiss\` (function, optional): Called only when the toast times out after \`duration\`. Put deferred irreversible work here; it never runs if the toast is dismissed first: \`(payload: Toast) => void\`
@@ -92,22 +93,62 @@ function deleteItemWithUndo(item) {
 }
 \`\`\`
 
+**Updating by id:** a creator called with the \`id\` of a toast that is still on screen updates that toast in place and returns the same \`Toast\` handle. The new options merge over the previous ones (keys you leave out keep their value; pass \`undefined\` to clear one), the color follows the creator you call, and the auto-dismiss timer restarts from the full \`duration\`. A toast with that id that is still animating out, or that was removed earlier in the same tick, is replaced by a new \`Toast\`: it takes the leaving toast's place a microtask later, plays its entry transition from wherever the exit had reached, and fires its own \`onAfterOpen\`. The old handle no longer controls it. Toasts queued before a \`<Toaster />\` mounts merge by id the same way.
+
+\`\`\`ts
+toast.primary({ id: 'save', title: 'Saving…', loading: true, duration: false });
+// later — same id, so the toast updates in place:
+toast.success({ id: 'save', title: 'Saved', loading: false, duration: 3000 });
+\`\`\`
+
+**Changing a toast: \`toast.update\`, \`toast.dismiss\`, \`toast.promise\`**
+
+\`update\`, \`dismiss\` and \`promise\` are reserved names, not colors.
+
+- \`toast.update(id, patch)\` changes the toast with that id that is on screen and returns its \`Toast\` handle (\`undefined\` when there is none). \`patch\` is an options object, or a function that receives the toast's current options (Toaster defaults included) and returns one. Keys left out keep their value, the timer restarts from the full \`duration\`, and the toast's \`data-update-key\` attribute changes. The handle has the same method: \`handle.update(patch)\`. A toast that was dismissed stays dismissed: updating it does nothing, so a result that arrives after the user closed the toast never brings it back.
+- \`toast.dismiss(id?)\` dismisses one toast, or every toast on screen (and any still waiting for a Toaster) when called without an id. Each fires \`onDismiss\` once.
+- \`toast.promise(promise, { loading, success, error, id? })\` shows a loading toast (a spinner, no timeout, color \`primary\`), then turns it into the success toast (color \`success\`) or error toast (color \`danger\`) when the promise settles. Each stage is a title string, an options object, or, for \`success\` and \`error\`, a function of the result or the rejection that returns either. The text and actions of the loading stage never carry over to the result. It returns the original promise, so it can be awaited, and a rejection still rejects for the caller.
+
+\`\`\`ts
+import { toast } from './index.ts';
+
+async function save(saveRows: () => Promise<number>) {
+  const rows = await toast.promise(saveRows(), {
+    loading: { title: 'Saving…', description: 'Hold on' },
+    success: (count) => ({ title: \`Saved \${count} rows\` }),
+    error: (error) => ({ title: 'Save failed', description: (error as Error).message })
+  });
+  return rows;
+}
+
+toast.update('batch', (current) => ({ title: current.title + '!' }));
+toast.dismiss(); // closes every toast
+\`\`\`
+
 **Mounting order:** \`toast()\` never throws when no \`<Toaster />\` is mounted yet — the toast is queued and shown by the first Toaster that mounts. In development, a single \`console.warn\` reports a queue that is still waiting a tick later. Dismissing a queued toast drops it from the queue, and a \`toast()\` call made during SSR is discarded instead of queued.
 
 **Returns:**
 A \`Toast\` instance that you can use to programmatically control the root:
 - \`toast.remove()\` - Remove the toast manually
+- \`toast.update(patch)\` - Update the toast in place (see Changing a toast); ignored once the toast was dismissed
+- \`toast.updateKey\` - Number of updates received, rendered as \`data-update-key\`
+- \`toast.dismissed\` - Whether the toast was dismissed
 - \`toast.id\` - Unique identifier
 - \`toast.opts\` - Toast options
 
 **Notes:**
 - Toasts are non-blocking and don't prevent user interaction
-- The toaster is a \`role="region"\` landmark named "Notifications" (not a \`<dialog>\`); pressing F6 anywhere moves focus into it. Each toast is \`role="status"\`, or \`role="alert"\` when \`important\`
+- The toaster is a \`role="region"\` landmark named "Notifications" (not a \`<dialog>\`), always rendered and empty while no toast shows; pressing F6 anywhere moves focus into it, and Tab then reaches the toasts. Toasts are announced through two live regions inside it that exist before the first toast: a polite one, and an assertive one for \`important\` toasts. The text announced is the toast's rendered title and description, again whenever the toast is updated. Each toast is a labelled \`role="group"\` (named by its title, described by its description), not a live region of its own
+- When the focused toast is dismissed, or is pushed past \`visibleToasts\` and turns inert, focus moves to the nearest toast that stays visible, else back to the element that was focused before F6, else to the region, instead of dropping to the page
 - Toasts stacked away behind the front one are \`inert\` (rather than \`aria-hidden\`), so they take no clicks or tab stops until they surface
 - Multiple toasts can be displayed simultaneously and will stack based on position
-- Toasts pause their auto-close timer when hovered
+- Toasts pause their auto-close timer while the pointer is over their stack (a touch tap is not a hover), while keyboard focus (\`:focus-visible\`) is on the stack (a mouse click or tap that focuses a toast does not pause anything), while a press or swipe is on one of its toasts, and while the browser window is blurred or its tab is hidden. The timers resume only when none of these holds them, with the time they had left. A toast shown while any of them applies starts paused
 - Toasts can be dismissed by clicking the close icon, clicking the toast (if \`closeOnClick\` is true), or automatically after the duration expires
 
+## Toaster props
+
+- \`direction\` (\`'ltr' | 'rtl'\`, optional): sets \`dir\` on the notification region, so the toasts' text and layout follow it. Inherited from the page when omitted. Positions stay physical: \`left\` and \`right\` are screen sides.
+
 ## Theme Customization
 
 The Toast component uses a theme object that can be customized using the \`theme\` prop in toast options or by setting a global theme.