entasis 0.11.0 → 0.12.0

package/dist/components/Theme/theme.mcp.d.ts

@@ -1 +1 @@
-export declare const themeDescription = "\n# Theme\n\n`Theme` owns global theme selection, runtime design tokens, shared overlay state, and theme\ntransitions. Wrap the application once and use the `ThemeState` received by the children snippet.\nComponents below it read the same state with `useTheme()` from `entasis/theme`, called during\ncomponent initialisation; it throws when no `Theme` is above. For a palette computed at runtime,\nsee `generateColorPalette` in `entasis/color-palette`.\n\n## Runtime design tokens\n\n```svelte\n<script lang=\"ts\">\n\timport { Theme, type ThemeDesignTokenMap } from 'entasis/theme';\n\n\tlet spacing = $state<'small' | 'normal' | 'large'>('normal');\n\tconst designTokens = $derived({\n\t\tlight: {\n\t\t\tspacing,\n\t\t\tspacingScale: { xs: 1, sm: 1.5, md: 2, lg: 3, xl: 4 },\n\t\t\tradius: 'normal',\n\t\t\ttypeScale: 'default',\n\t\t\traisedWithBorder: true,\n\t\t\tdefaultColor: 'neutral'\n\t\t},\n\t\tdark: {\n\t\t\tspacing,\n\t\t\tspacingScale: { xs: 1, sm: 1.5, md: 2, lg: 3, xl: 4 },\n\t\t\tradius: 'small',\n\t\t\ttypeScale: 'compact',\n\t\t\traisedWithBorder: false,\n\t\t\tdefaultColor: 'neutral'\n\t\t}\n\t} satisfies ThemeDesignTokenMap<readonly ['light', 'dark']>);\n</script>\n\n<Theme {designTokens} transition=\"radial-top-right\">\n\t{#snippet children(theme)}\n\t\t<button onclick={() => (spacing = spacing === 'small' ? 'large' : 'small')}>\n\t\t\tChange density\n\t\t</button>\n\t\t<button onclick={() => (theme.theme = theme.resolvedTheme === 'dark' ? 'light' : 'dark')}>\n\t\t\tToggle color scheme\n\t\t</button>\n\t{/snippet}\n</Theme>\n```\n\n`designTokens` is keyed by logical theme name and respects the `attribute` and `value` props.\nEleven presets ship as `themePresets` (`dense`, `compact`, `balanced`, `comfortable`, `spacious`,\n`sharp`, `rounded`, `display`, `editorial`, `glass`, `terminal`): `designTokens={{ light: themePresets.glass.tokens, dark: themePresets.glass.tokens }}`.\nChanging the controlled object updates already-rendered Tailwind utilities without rebuilding CSS.\n\n### ThemeDesignTokens\n\n- `spacing`: `'small' | 'normal' | 'large' | number`. Globally scales density.\n- `spacingScale`: partial overrides for the strictly increasing `xs`, `sm`, `md`, `lg`,\n  and `xl` spacing multipliers. Defaults to 1/1.5/2/3/4.\n- `radius`: `'none' | 'subtile' | 'small' | 'normal' | 'large' | 'round' | number`.\n  Controls take the full multiplier; surface steps (`lg` and up) stop at `large` (1.5\u00D7).\n- `typeScale`: `'compact' | 'default' | 'comfortable' | 'large' | TypeScaleOptions`.\n- `raisedWithBorder`: toggles the border used by `raised-*` utilities.\n- `defaultColor`: `Colors` role kit chrome inherits when a control omits `color`.\n  Defaults to `neutral`. Set `primary` to restore an accent-colored kit. Compiles the\n  current-color family (`--color`, `--color-readable`, muted/contrast/light/dark variants)\n  and `--default-color` onto the theme selector. Do not set `data-color` on `html`.\n- `focusColor`, `selectedColor`, `hoverColor`, `pressedColor`: the four `Colors` **state\n  roles**. They pin, for the whole theme, what a focus ring, a persistent selection and the\n  transient hover/pressed layer look like, independently of the role of the control the state\n  lands on. They compile `--color-focus`, `--color-selected` (plus its `-contrast`,\n  `-readable` and `-muted-readable` companions), `--color-hover` and\n  `--color-pressed` onto the theme selector. There is no `--color-selected-muted`: the soft\n  fill is a translucent tint of `--color-selected` at `--state-selected-opacity`, so it reads\n  on any surface. None is declared at `:root`: every use site\n  falls back to the matching current role (`ring-focus` is\n  `var(--color-focus, var(--color))`, `bg-selected-muted` tints\n  `var(--color-selected, var(--color))`, the state layer is\n  `var(--color-hover, currentColor)` and on `:active`\n  `var(--color-pressed, var(--color-hover, currentColor))`), so leaving them unset changes\n  nothing and `data-color` keeps moving the states with `--color`. Theme-level only: there is\n  no per-component override. An unknown role throws.\n\nComponent-level density remains a local variant. It selects utility classes whose values inherit\nthe active global spacing token.\n\nGenerated interfaces should use the public `xs | sm | md | lg | xl` vocabulary through component\nprops and named gap/padding utilities. `micro` and `layout-*` are internal recipe tokens. Prefer\nparent-owned gaps over child margins; do not emit arbitrary spacing or unsupported radius values.\n\n## Theme selection\n\nThe selection props wrap `svelte-themes`: `themes`, `defaultTheme`, `forcedTheme`,\n`systemTheme`, `syncColorScheme`, `transitionOnChange`, `storageKey`, `attribute`,\n`value`, and `colorScheme`. The default themes are light and dark, with system selection\nenabled. `systemTheme`, `syncColorScheme`, and `transitionOnChange` all default to\n`true`; they map onto the library's `enableSystem`, `enableColorScheme`, and\n`disableTransitionOnChange` options.\n\n`ThemeState` exposes `theme`, `resolvedTheme`, `themes`, and `systemTheme`. Assign\n`theme.theme` to switch themes. The optional `transition` prop applies a named view transition;\nunsupported browsers and reduced-motion users switch instantly.\n\n`spinnerVariant` sets the global default spinner animation. The children snippet is required.\n\n## Motion tokens\n\nMotion is a token scale like spacing and radius: five duration steps and four easing roles.\n`motion` retunes them app-wide; an omitted token keeps its default.\n\n| Duration   | Default |     | Easing role  | Default       |\n| ---------- | ------- | --- | ------------ | ------------- |\n| `instant`  | 0ms     |     | `standard`   | `cubicInOut`  |\n| `fast`     | 100ms   |     | `enter`      | `cubicOut`    |\n| `normal`   | 200ms   |     | `exit`       | `cubicIn`     |\n| `slow`     | 300ms   |     | `emphasized` | `backOut`     |\n| `slower`   | 500ms   |     |              |               |\n\n```svelte\n<script lang=\"ts\">\n\timport { Theme } from 'entasis/theme';\n\n\tlet { children } = $props();\n</script>\n\n<Theme motion={{ duration: { normal: 150, slow: 260 }, easing: { standard: 'quintOut' } }}>\n\t{@render children()}\n</Theme>\n```\n\nThe Tailwind plugin emits the same scale as CSS variables on `html` (`--duration-normal`,\n`--ease-standard`, ...) plus the matching `duration-*` / `ease-*` utilities, so CSS transitions\nand Svelte transitions read one set of numbers. The `motion` prop rewrites those variables on\n`html` at runtime and `designTokens.motion` rewrites them again per theme, layered over the prop;\n`ThemeState.motion` resolves through the same two rungs, so the utilities and the presets never\ndisagree. `ThemeState.transition` is a deprecated alias for its `normal` duration and `standard`\neasing. Reduced motion resolves every duration to 0 and collapses the `--duration-*` variables via\nthe `data-entasis-reduce-motion` attribute on `html`.\n\nComponents keep their own transition in a reserved `motion` slot on their theme, so the `theme`\nprop covers motion as well as classes:\n\n```svelte\n<script lang=\"ts\">\n\timport { Dialog } from 'entasis/dialog';\n</script>\n\n<Dialog theme={{ motion: { duration: 'fast', easing: 'emphasized' } }} title=\"Quick\">Body</Dialog>\n```\n\n## Component theme registry\n\n`components` sets app-wide component theme defaults without a wrapper component per component:\nit is keyed by theme name (`dialog`, `button`, ...) and each entry takes the same slots as that\ncomponent's `theme` prop, the `motion` slot included. A `set<Component>Theme` call in a subtree\nbeats the registry, and an instance `theme` prop beats both \u2014 per slot: each rung layers on the one\nbelow it, so a subtree that restyles one slot keeps the registry's others.\n\n```svelte\n<script lang=\"ts\">\n\timport { Theme } from 'entasis/theme';\n\n\tlet { children } = $props();\n</script>\n\n<Theme\n\tcomponents={{\n\t\tdialog: { motion: { duration: 'fast' }, content: { base: 'rounded-2xl' } },\n\t\tbutton: { root: { base: 'tracking-wide' } }\n\t}}\n>\n\t{@render children()}\n</Theme>\n```\n\n## Reduced motion\n\n`reduceMotion` forces reduced motion on (`true`) or off (`false`) for every entasis animation,\noverriding the OS `prefers-reduced-motion` setting; omit it to follow the OS. The live result is\nexposed as `ThemeState.preferReducesMotion` (reactive, so it updates when the OS setting changes)\nand mirrored as a `data-entasis-reduce-motion` attribute on `html` for CSS-only animations.\n\n```svelte\n<script>\n\timport { Theme } from 'entasis/theme';\n\n\tlet { children } = $props();\n</script>\n\n<Theme reduceMotion>{@render children()}</Theme>\n```\n\n## Build-time boundary\n\nThe Tailwind plugin still generates color palettes and registers utility names, variants,\nkeyframes, and spinner CSS. Spacing, radius, typography scale, raised borders,\n`defaultColor` and the four state roles (`focusColor`, `selectedColor`, `hoverColor`,\n`pressedColor`) belong to `Theme.designTokens`; colors remain CSS variables and can be\noverridden directly. `ThemeState.defaultColor` exposes the active role. Kit chrome should\nresolve omitted `color` props with `useDefaultColor`.\n";
+export declare const themeDescription = "\n# Theme\n\n`Theme` owns global theme selection, runtime design tokens, shared overlay state, and theme\ntransitions. Wrap the application once and use the `ThemeState` received by the children snippet.\nComponents below it read the same state with `useTheme()` from `entasis/theme`, called during\ncomponent initialisation; it throws when no `Theme` is above. For a palette computed at runtime,\nsee `generateColorPalette` in `entasis/color-palette`.\n\n## Runtime design tokens\n\n```svelte\n<script lang=\"ts\">\n\timport { Theme, type ThemeDesignTokenMap } from 'entasis/theme';\n\n\tlet spacing = $state<'small' | 'normal' | 'large'>('normal');\n\tconst designTokens = $derived({\n\t\tlight: {\n\t\t\tspacing,\n\t\t\tspacingScale: { xs: 1, sm: 1.5, md: 2, lg: 3, xl: 4 },\n\t\t\tradius: 'normal',\n\t\t\ttypeScale: 'default',\n\t\t\traisedWithBorder: true,\n\t\t\tdefaultColor: 'neutral'\n\t\t},\n\t\tdark: {\n\t\t\tspacing,\n\t\t\tspacingScale: { xs: 1, sm: 1.5, md: 2, lg: 3, xl: 4 },\n\t\t\tradius: 'small',\n\t\t\ttypeScale: 'compact',\n\t\t\traisedWithBorder: false,\n\t\t\tdefaultColor: 'neutral'\n\t\t}\n\t} satisfies ThemeDesignTokenMap<readonly ['light', 'dark']>);\n</script>\n\n<Theme {designTokens} transition=\"radial-top-right\">\n\t{#snippet children(theme)}\n\t\t<button onclick={() => (spacing = spacing === 'small' ? 'large' : 'small')}>\n\t\t\tChange density\n\t\t</button>\n\t\t<button onclick={() => (theme.theme = theme.resolvedTheme === 'dark' ? 'light' : 'dark')}>\n\t\t\tToggle color scheme\n\t\t</button>\n\t{/snippet}\n</Theme>\n```\n\n`designTokens` is keyed by logical theme name and respects the `attribute` and `value` props.\nEleven presets ship as `themePresets` (`dense`, `compact`, `balanced`, `comfortable`, `spacious`,\n`sharp`, `rounded`, `display`, `editorial`, `glass`, `terminal`): `designTokens={{ light: themePresets.glass.tokens, dark: themePresets.glass.tokens }}`.\nChanging the controlled object updates already-rendered Tailwind utilities without rebuilding CSS.\n\n### ThemeDesignTokens\n\n- `spacing`: `'small' | 'normal' | 'large' | number`. Globally scales density.\n- `spacingScale`: partial overrides for the strictly increasing `xs`, `sm`, `md`, `lg`,\n  and `xl` spacing multipliers. Defaults to 1/1.5/2/3/4.\n- `radius`: `'none' | 'subtile' | 'small' | 'normal' | 'large' | 'round' | number`.\n  Controls take the full multiplier; surface steps (`lg` and up) stop at `large` (1.5\u00D7).\n- `typeScale`: `'compact' | 'default' | 'comfortable' | 'large' | TypeScaleOptions`.\n- `raisedWithBorder`: toggles the border used by `raised-*` utilities.\n- `defaultColor`: `Colors` role kit chrome inherits when a control omits `color`.\n  Defaults to `neutral`. Set `primary` to restore an accent-colored kit. Compiles the\n  current-color family (`--color`, `--color-readable`, muted/contrast/light/dark variants)\n  and `--default-color` onto the theme selector. Do not set `data-color` on `html`.\n- `focusColor`, `selectedColor`, `hoverColor`, `pressedColor`: the four `Colors` **state\n  roles**. They pin, for the whole theme, what a focus ring, a persistent selection and the\n  transient hover/pressed layer look like, independently of the role of the control the state\n  lands on. They compile `--color-focus`, `--color-selected` (plus its `-contrast`,\n  `-readable` and `-muted-readable` companions), `--color-hover` and\n  `--color-pressed` onto the theme selector. There is no `--color-selected-muted`: the soft\n  fill is a translucent tint of `--color-selected` at `--state-selected-opacity`, so it reads\n  on any surface. None is declared at `:root`: every use site\n  falls back to the matching current role (`ring-focus` is\n  `var(--color-focus, var(--color))`, `bg-selected-muted` tints\n  `var(--color-selected, var(--color))`, the state layer is\n  `var(--color-hover, currentColor)` and on `:active`\n  `var(--color-pressed, var(--color-hover, currentColor))`), so leaving them unset changes\n  nothing and `data-color` keeps moving the states with `--color`. Theme-level only: there is\n  no per-component override. An unknown role throws.\n\nComponent-level density remains a local variant. It selects utility classes whose values inherit\nthe active global spacing token.\n\nGenerated interfaces should use the public `xs | sm | md | lg | xl` vocabulary through component\nprops and named gap/padding utilities. `micro` and `layout-*` are internal recipe tokens. Prefer\nparent-owned gaps over child margins; do not emit arbitrary spacing or unsupported radius values.\n\n## Theme selection\n\nThe selection props wrap `svelte-themes`: `themes`, `defaultTheme`, `forcedTheme`,\n`systemTheme`, `syncColorScheme`, `transitionOnChange`, `storageKey`, `attribute`,\n`value`, and `colorScheme`. The default themes are light and dark, with system selection\nenabled. `systemTheme`, `syncColorScheme`, and `transitionOnChange` all default to\n`true`; they map onto the library's `enableSystem`, `enableColorScheme`, and\n`disableTransitionOnChange` options.\n\n`ThemeState` exposes `theme`, `resolvedTheme`, `themes`, and `systemTheme`. Assign\n`theme.theme` to switch themes. The optional `transition` prop applies a named view transition;\nunsupported browsers and reduced-motion users switch instantly.\n\n`spinnerVariant` sets the global default spinner animation. The children snippet is required.\n\n## Motion tokens\n\nMotion is a token scale like spacing and radius: five duration steps and four easing roles.\n`motion` retunes them app-wide; an omitted token keeps its default.\n\n| Duration   | Default |     | Easing role  | Default       |\n| ---------- | ------- | --- | ------------ | ------------- |\n| `instant`  | 0ms     |     | `standard`   | `cubicInOut`  |\n| `fast`     | 100ms   |     | `enter`      | `cubicOut`    |\n| `normal`   | 200ms   |     | `exit`       | `cubicIn`     |\n| `slow`     | 300ms   |     | `emphasized` | `backOut`     |\n| `slower`   | 500ms   |     |              |               |\n\n```svelte\n<script lang=\"ts\">\n\timport { Theme } from 'entasis/theme';\n\n\tlet { children } = $props();\n</script>\n\n<Theme motion={{ duration: { normal: 150, slow: 260 }, easing: { standard: 'quintOut' } }}>\n\t{@render children()}\n</Theme>\n```\n\nThe Tailwind plugin emits the same scale as CSS variables on `html` (`--duration-normal`,\n`--ease-standard`, ...) plus the matching `duration-*` / `ease-*` utilities, so CSS transitions\nand Svelte transitions read one set of numbers. The `motion` prop rewrites those variables on\n`html` at runtime and `designTokens.motion` rewrites them again per theme, layered over the prop;\n`ThemeState.motion` resolves through the same two rungs, so the utilities and the presets never\ndisagree. `ThemeState.transition` is a deprecated alias for its `normal` duration and `standard`\neasing. Reduced motion resolves every duration to 0 and collapses the `--duration-*` variables via\nthe `data-entasis-reduce-motion` attribute on `html`.\n\nComponents keep their own transition in a reserved `motion` slot on their theme, so the `theme`\nprop covers motion as well as classes:\n\n```svelte\n<script lang=\"ts\">\n\timport { Dialog } from 'entasis/dialog';\n</script>\n\n<Dialog theme={{ motion: { duration: 'fast', easing: 'emphasized' } }} title=\"Quick\">Body</Dialog>\n```\n\n## Component theme registry\n\n`components` sets app-wide component theme defaults without a wrapper component per component:\nit is keyed by theme name (`dialog`, `button`, ...) and each entry takes the same slots as that\ncomponent's `theme` prop, the `motion` slot included. A `set<Component>Theme` call in a subtree\nbeats the registry, and an instance `theme` prop beats both \u2014 per slot: each rung layers on the one\nbelow it, so a subtree that restyles one slot keeps the registry's others.\n\n```svelte\n<script lang=\"ts\">\n\timport { Theme } from 'entasis/theme';\n\n\tlet { children } = $props();\n</script>\n\n<Theme\n\tcomponents={{\n\t\tdialog: { motion: { duration: 'fast' }, content: { base: 'rounded-2xl' } },\n\t\tbutton: { root: { base: 'tracking-wide' } }\n\t}}\n>\n\t{@render children()}\n</Theme>\n```\n\n## Reduced motion\n\n`reduceMotion` forces reduced motion on (`true`) or off (`false`) for every entasis animation,\noverriding the OS `prefers-reduced-motion` setting; omit it to follow the OS. The live result is\nexposed as `ThemeState.preferReducesMotion` (reactive, so it updates when the OS setting changes)\nand mirrored as a `data-entasis-reduce-motion` attribute on `html` for CSS-only animations.\n\n```svelte\n<script>\n\timport { Theme } from 'entasis/theme';\n\n\tlet { children } = $props();\n</script>\n\n<Theme reduceMotion>{@render children()}</Theme>\n```\n\n## Content Security Policy\n\n`nonce` is stamped on every `<script>` and `<style>` the Theme and the components below it\ninject: the theme and viewport boot scripts, the design-token stylesheet, the `transitionOnChange={false}`\nstyle, and the CDN loaders of PhoneInput, Map and Mermaid (the document print frame and Mermaid's own\nsvg `<style>` too). Drag-and-drop base styles are rules in the Tailwind plugin CSS, so nothing is\ninjected for them. Generate one nonce per request in `hooks.server.ts`, send it through `locals` to\n`<Theme nonce>`, and send the Content-Security-Policy header yourself with that same nonce.\nSvelteKit's `kit.csp` cannot be used for this: it generates its own nonce per request, exposes it\nonly as `%sveltekit.nonce%` in `app.html`, and has no option to take yours, so the header would\ncarry one nonce while the Theme's tags carry another. Leave `kit.csp` unset and put the nonce on\nSvelteKit's own inline tags in `transformPageChunk`:\n\n```ts\n// doc-fence: skip (needs nonce declared on the app's App.Locals)\n// src/hooks.server.ts\nimport type { Handle } from '@sveltejs/kit';\n\nexport const handle: Handle = async ({ event, resolve }) => {\n\tconst nonce = crypto.randomUUID();\n\tevent.locals.nonce = nonce;\n\tconst response = await resolve(event, {\n\t\t// Adds the nonce to SvelteKit's inline <script> and <style> tags; tags that already carry one\n\t\t// (the Theme's) are left alone.\n\t\ttransformPageChunk: ({ html }) =>\n\t\t\thtml.replace(/<(script|style)(?=[\\s>])(?![^>]*\\snonce=)/g, `<$1 nonce=\"${nonce}\"`)\n\t});\n\tresponse.headers.set(\n\t\t'content-security-policy',\n\t\t`script-src 'self' 'nonce-${nonce}'; style-src 'self' 'nonce-${nonce}'; style-src-attr 'unsafe-inline'`\n\t);\n\treturn response;\n};\n```\n\n```ts\n// doc-fence: skip (needs nonce declared on the app's App.Locals)\n// src/routes/+layout.server.ts\nimport type { LayoutServerLoad } from './$types';\n\nexport const load: LayoutServerLoad = ({ locals }) => ({ nonce: locals.nonce });\n```\n\n```svelte\n<!-- src/routes/+layout.svelte -->\n<script lang=\"ts\">\n\timport { Theme } from 'entasis/theme';\n\n\tlet { data, children } = $props();\n</script>\n\n<Theme nonce={data.nonce}>\n\t{@render children()}\n</Theme>\n```\n\nServer-rendered `style` attributes (`style:` directives) are not covered by a nonce: allow them with\n`style-src-attr 'unsafe-inline'` (as above). `ThemeState.nonce` exposes the value to your own injected code.\n\n## Shadow DOM and portal containers\n\nDialogs, popovers, menus, tooltips and the floating-window layer mount in `document.body`. Inside a\nshadow root they mount in that root so adopted styles keep applying. `portalContainer` overrides both:\nan element or shadow root, or a function returning one for a container that is not rendered yet.\nA function that reads `$state` (as below) moves the floating-window layer in as soon as the container\nappears; a function over a plain variable is read each time a panel mounts, so the layer, which mounts\nwith the Theme, needs the container to exist by then.\nOutside presses and Escape are heard on the document a panel lives in, so a panel rendered into an\niframe's document dismisses correctly.\n\n```svelte\n<script lang=\"ts\">\n\timport { Theme } from 'entasis/theme';\n\n\tlet { children } = $props();\n\tlet host = $state<HTMLElement>();\n</script>\n\n<div bind:this={host}></div>\n<Theme portalContainer={() => host}>\n\t{@render children()}\n</Theme>\n```\n\nWhen several Themes are mounted, the most recently mounted one that sets `portalContainer` wins.\n\n## Scroll lock and viewport variables\n\nA dialog or popover locks page scroll with a `data-entasis-scroll-lock` attribute on `<html>` and one\nrule in the Tailwind plugin CSS (`overflow: hidden`); nothing is written to inline styles, so a lock a\nthird-party library holds on the same element is neither overwritten nor released early. While\nlocked, the hidden scrollbar's room is kept with `scrollbar-gutter: stable` (the lock measures the\npage and pads the scrollbar's width instead where the gutter does not hold) unless the page already reserves a gutter, so there is no double gutter. Two variables\ndescribe the viewport for your own layout:\n\n- `--entasis-scrollbar-width`: set on `<html>` while locked, the width in px of the scrollbar the\n  lock hides (`0px` with overlay scrollbars). Add it to `position: fixed` bars:\n  `padding-inline-end: var(--entasis-scrollbar-width, 0px)`.\n- `--keyboard-inset`: the height in px the on-screen keyboard covers at the bottom of the layout\n  viewport, measured from the visual viewport (`0px` without a keyboard, while pinch-zoomed, and in\n  browsers that resize the layout viewport for the keyboard). Pin a bottom bar above the keyboard with\n  `bottom: var(--keyboard-inset)`.\n\n## Build-time boundary\n\nThe Tailwind plugin still generates color palettes and registers utility names, variants,\nkeyframes, and spinner CSS. Spacing, radius, typography scale, raised borders,\n`defaultColor` and the four state roles (`focusColor`, `selectedColor`, `hoverColor`,\n`pressedColor`) belong to `Theme.designTokens`; colors remain CSS variables and can be\noverridden directly. `ThemeState.defaultColor` exposes the active role. Kit chrome should\nresolve omitted `color` props with `useDefaultColor`.\n";

package/dist/components/Theme/theme.mcp.js

@@ -189,6 +189,109 @@ and mirrored as a \`data-entasis-reduce-motion\` attribute on \`html\` for CSS-o
 <Theme reduceMotion>{@render children()}</Theme>
 \`\`\`
 
+## Content Security Policy
+
+\`nonce\` is stamped on every \`<script>\` and \`<style>\` the Theme and the components below it
+inject: the theme and viewport boot scripts, the design-token stylesheet, the \`transitionOnChange={false}\`
+style, and the CDN loaders of PhoneInput, Map and Mermaid (the document print frame and Mermaid's own
+svg \`<style>\` too). Drag-and-drop base styles are rules in the Tailwind plugin CSS, so nothing is
+injected for them. Generate one nonce per request in \`hooks.server.ts\`, send it through \`locals\` to
+\`<Theme nonce>\`, and send the Content-Security-Policy header yourself with that same nonce.
+SvelteKit's \`kit.csp\` cannot be used for this: it generates its own nonce per request, exposes it
+only as \`%sveltekit.nonce%\` in \`app.html\`, and has no option to take yours, so the header would
+carry one nonce while the Theme's tags carry another. Leave \`kit.csp\` unset and put the nonce on
+SvelteKit's own inline tags in \`transformPageChunk\`:
+
+\`\`\`ts
+// doc-fence: skip (needs nonce declared on the app's App.Locals)
+// src/hooks.server.ts
+import type { Handle } from '@sveltejs/kit';
+
+export const handle: Handle = async ({ event, resolve }) => {
+	const nonce = crypto.randomUUID();
+	event.locals.nonce = nonce;
+	const response = await resolve(event, {
+		// Adds the nonce to SvelteKit's inline <script> and <style> tags; tags that already carry one
+		// (the Theme's) are left alone.
+		transformPageChunk: ({ html }) =>
+			html.replace(/<(script|style)(?=[\\s>])(?![^>]*\\snonce=)/g, \`<$1 nonce="\${nonce}"\`)
+	});
+	response.headers.set(
+		'content-security-policy',
+		\`script-src 'self' 'nonce-\${nonce}'; style-src 'self' 'nonce-\${nonce}'; style-src-attr 'unsafe-inline'\`
+	);
+	return response;
+};
+\`\`\`
+
+\`\`\`ts
+// doc-fence: skip (needs nonce declared on the app's App.Locals)
+// src/routes/+layout.server.ts
+import type { LayoutServerLoad } from './$types';
+
+export const load: LayoutServerLoad = ({ locals }) => ({ nonce: locals.nonce });
+\`\`\`
+
+\`\`\`svelte
+<!-- src/routes/+layout.svelte -->
+<script lang="ts">
+	import { Theme } from './index.ts';
+
+	let { data, children } = $props();
+</script>
+
+<Theme nonce={data.nonce}>
+	{@render children()}
+</Theme>
+\`\`\`
+
+Server-rendered \`style\` attributes (\`style:\` directives) are not covered by a nonce: allow them with
+\`style-src-attr 'unsafe-inline'\` (as above). \`ThemeState.nonce\` exposes the value to your own injected code.
+
+## Shadow DOM and portal containers
+
+Dialogs, popovers, menus, tooltips and the floating-window layer mount in \`document.body\`. Inside a
+shadow root they mount in that root so adopted styles keep applying. \`portalContainer\` overrides both:
+an element or shadow root, or a function returning one for a container that is not rendered yet.
+A function that reads \`$state\` (as below) moves the floating-window layer in as soon as the container
+appears; a function over a plain variable is read each time a panel mounts, so the layer, which mounts
+with the Theme, needs the container to exist by then.
+Outside presses and Escape are heard on the document a panel lives in, so a panel rendered into an
+iframe's document dismisses correctly.
+
+\`\`\`svelte
+<script lang="ts">
+	import { Theme } from './index.ts';
+
+	let { children } = $props();
+	let host = $state<HTMLElement>();
+</script>
+
+<div bind:this={host}></div>
+<Theme portalContainer={() => host}>
+	{@render children()}
+</Theme>
+\`\`\`
+
+When several Themes are mounted, the most recently mounted one that sets \`portalContainer\` wins.
+
+## Scroll lock and viewport variables
+
+A dialog or popover locks page scroll with a \`data-entasis-scroll-lock\` attribute on \`<html>\` and one
+rule in the Tailwind plugin CSS (\`overflow: hidden\`); nothing is written to inline styles, so a lock a
+third-party library holds on the same element is neither overwritten nor released early. While
+locked, the hidden scrollbar's room is kept with \`scrollbar-gutter: stable\` (the lock measures the
+page and pads the scrollbar's width instead where the gutter does not hold) unless the page already reserves a gutter, so there is no double gutter. Two variables
+describe the viewport for your own layout:
+
+- \`--entasis-scrollbar-width\`: set on \`<html>\` while locked, the width in px of the scrollbar the
+  lock hides (\`0px\` with overlay scrollbars). Add it to \`position: fixed\` bars:
+  \`padding-inline-end: var(--entasis-scrollbar-width, 0px)\`.
+- \`--keyboard-inset\`: the height in px the on-screen keyboard covers at the bottom of the layout
+  viewport, measured from the visual viewport (\`0px\` without a keyboard, while pinch-zoomed, and in
+  browsers that resize the layout viewport for the keyboard). Pin a bottom bar above the keyboard with
+  \`bottom: var(--keyboard-inset)\`.
+
 ## Build-time boundary
 
 The Tailwind plugin still generates color palettes and registers utility names, variants,

package/dist/components/Theme/theme.props.d.ts

@@ -47,4 +47,20 @@ export type ThemeProps<T extends readonly string[] = readonly string[]> = Omit<S
      * A `set<Component>Theme` call or an instance `theme` prop still wins.
      */
     components?: ComponentThemeRegistry;
+    /**
+     * Content-Security-Policy nonce. Applied to every `<script>` and `<style>` the Theme and the
+     * components below it inject (the theme and viewport boot scripts, design-token CSS, and the
+     * CDN loaders of PhoneInput, Map and Mermaid). Generate one per request in `hooks.server`,
+     * pass it through `locals` and layout data, and send the Content-Security-Policy header with
+     * that same nonce yourself (`kit.csp` generates its own and cannot take this one).
+     */
+    nonce?: string;
+    /**
+     * Where portaled panels (dialogs, popovers, menus, tooltips, the floating-window layer) are
+     * mounted. Defaults to `document.body`, or to the shadow root when the Theme renders inside
+     * one. Pass an element, or a function for a container that does not exist yet at render time:
+     * a function over `$state` (`() => host`) moves the panels in when the container appears, a
+     * function over a plain variable is read when each panel mounts.
+     */
+    portalContainer?: HTMLElement | ShadowRoot | (() => HTMLElement | ShadowRoot | null | undefined);
 };

package/dist/components/Theme/theme.state.svelte.d.ts

@@ -7,11 +7,13 @@ import { SvelteMap, SvelteSet } from 'svelte/reactivity';
 import type { FSOParams, FSOProps } from '../../transitions/transition.js';
 import type { Theme as SvelteTheme } from 'svelte-themes';
 import { LayerStack } from '../../utils/layers.svelte.js';
+import { HoverIntentGroup } from '../../utils/hoverIntent.js';
 import type { TooltipOptions } from '../Tooltip/tooltip.props.js';
 import type { ConfirmationHost } from '../Confirmation/confirmation.state.svelte.js';
 import { type ThemeTransition } from './themeTransition.js';
 import { ThemeFloatingWindows } from './theme.floatingWindows.js';
 import type { Colors } from '../../types/theme.js';
+import { type PortalContainerSource } from '../../attachments/portal.js';
 type Events = 'scroll' | 'pointerdown' | 'keydown' | 'keyup';
 type EventPayload = {
     [E in Events]: E extends 'pointerdown' ? PointerEvent : E extends 'keydown' ? KeyboardEvent : E extends 'keyup' ? KeyboardEvent : E extends 'scroll' ? WheelEvent : Event;
@@ -31,13 +33,24 @@ interface ThemeOptions {
     readonly motionTokens?: DeepPartial<MotionTokens>;
     /** The `<Theme components>` registry; read by `useComponentTheme`/`useComponentMotion`. */
     readonly componentThemes?: ComponentThemeRegistry;
+    /** The `<Theme nonce>` value: the CSP nonce of every injected `<script>` and `<style>`. */
+    readonly nonce?: string;
+    /** The `<Theme portalContainer>` value: where portaled panels mount. */
+    readonly portalContainer?: PortalContainerSource;
 }
 declare const ThemeState_base: new (props: ThemeOptions) => {} & ThemeOptions;
 export declare class ThemeState extends ThemeState_base {
     tooltip: (TooltipOptions & {
         ref: HTMLElement;
     }) | null;
-    lastTooltipClosed: number | null;
+    /**
+     * Hover warm-up shared by tooltips, hover cards and hover-opened popovers: right after one
+     * of them was open, the next opens without its delay.
+     */
+    readonly hoverIntent: HoverIntentGroup;
+    /** @deprecated Read `hoverIntent.lastClosedAt`; the tooltip warm-up now lives there. */
+    get lastTooltipClosed(): number | null;
+    set lastTooltipClosed(time: number | null);
     /** DOM id of the single tooltip surface, so triggers can point `aria-describedby` at it. */
     tooltipId: string | null;
     /**

package/dist/components/Theme/theme.state.svelte.js

@@ -7,12 +7,27 @@ import { resolveMotionTokens } from '../../tailwind/scales.js';
 import { SvelteMap, SvelteSet } from 'svelte/reactivity';
 import { on } from 'svelte/events';
 import { LayerStack } from '../../utils/layers.svelte.js';
+import { HoverIntentGroup } from '../../utils/hoverIntent.js';
 import { updateThemeWithTransition } from './themeTransition.js';
 import { ThemeFloatingWindows } from './theme.floatingWindows.js';
 import { REDUCED_MOTION_QUERY, registerActiveTheme } from '../../utils/motion.svelte.js';
+import { registerCspNonce } from '../../utils/cspNonce.js';
+import { registerPortalContainer } from '../../attachments/portal.js';
 export class ThemeState extends createBindableStateClass() {
     tooltip = $state(null);
-    lastTooltipClosed = $state(null);
+    /**
+     * Hover warm-up shared by tooltips, hover cards and hover-opened popovers: right after one
+     * of them was open, the next opens without its delay.
+     */
+    hoverIntent = new HoverIntentGroup();
+    /** @deprecated Read `hoverIntent.lastClosedAt`; the tooltip warm-up now lives there. */
+    get lastTooltipClosed() {
+        return this.hoverIntent.lastClosedAt;
+    }
+    set lastTooltipClosed(time) {
+        if (time !== null)
+            this.hoverIntent.markClosed(time);
+    }
     /** DOM id of the single tooltip surface, so triggers can point `aria-describedby` at it. */
     tooltipId = $state(null);
     /**
@@ -106,6 +121,8 @@ export class ThemeState extends createBindableStateClass() {
         this.svelteTheme = svelteTheme;
         setContext('entasisTheme', this);
         onDestroy(registerActiveTheme(this));
+        onDestroy(registerCspNonce(() => this.nonce));
+        onDestroy(registerPortalContainer(() => this.portalContainer));
     }
     resolveTransitionProps = (props, defaultTransition) => {
         const responsiveTransition = this.resolveResponsiveProps(props);

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';