@astryxdesign/core 0.7.5 → 0.7.6-canary.0bd3b37

package/src/Toast/Toast.spec.md

@@ -50,7 +50,7 @@ system_specs:
 | Behavior                | A stack of non-modal notification cards at one viewport corner. Each toast is announced once, can auto-hide (pausing while hovered, focused, touched, or the window is blurred), and dismisses by its button, a vertical swipe toward its edge, or code. F6 moves focus into the newest toast.                                                                                                                                                         |
 | End-user impact         | Users get brief notices without losing their place; screen-reader users hear each toast once; keyboard users reach toast controls with F6 and land somewhere sensible after dismissing; touch users swipe toasts away.                                                                                                                                                                                                                                 |
 | Builder impact          | None.                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| Compatibility/readiness | Records shipped behavior; no public change. Twenty-one implementation gaps, listed under Current-state impact.                                                                                                                                                                                                                                                                                                                                         |
+| Compatibility/readiness | Records shipped behavior; no public change. Nineteen implementation gaps, listed under Current-state impact.                                                                                                                                                                                                                                                                                                                                           |
 | Review checks           | Reject a toast announced more than once per show, a dismissal that drops focus to the body, an auto-hide that runs while the user is reading or interacting, or a swipe as the only way to dismiss.                                                                                                                                                                                                                                                    |
 | Governing rules         | `spec:AST-086` FR1; `spec:AST-003` (modal rehosting); `spec:AST-094`; `spec:AST-100`; `spec:AST-059` FR6; `architecture:layer-runtime`; `design:bidirectionality`; `design:reduced-motion`.                                                                                                                                                                                                                                                            |
 
@@ -93,12 +93,9 @@ Consumer migration instructions belong in consumer docs and release notes.
   once at release on projected travel and cancel a release moving back, and
   `spec:AST-100` FR1, FR2, and FR4 take the release velocity from the shared
   tracker.
-- **The auto-hide pause is one flag.** Any pause condition ending, the pointer
-  leaving, focus leaving, or the window regaining focus, resumes the timer
-  while another still holds, so a toast can auto-hide with focus on its action
-  or with the pointer over it. A toast raised while the window is already
-  blurred starts its timer and can auto-hide unseen, since only a later blur
-  pauses it.
+- **A toast raised while the window is blurred runs its timer.** Only a later
+  blur pauses it, so a toast raised while the user is in another window can
+  auto-hide unseen.
 - **A control-free toast cannot take focus.** With no control in the newest
   toast, F6 leaves focus where it was; dismissing a focused toast beside a
   control-free one drops focus to the page body.
@@ -111,9 +108,6 @@ Consumer migration instructions belong in consumer docs and release notes.
 - **A hidden toast's overwrite is announced unseen.** Overwriting, through
   `uniqueID`, a toast hidden by the cap announces the new text while it is not
   shown, and nothing is announced when it surfaces.
-- **Focus can drop after Tab entry.** Dismissing the last toast after reaching
-  it with Tab rather than F6 leaves no remembered element, so focus lands on
-  the page body.
 - **Custom content without a control has only the swipe.** A `renderContent`
   toast that renders no control can be dismissed only by a swipe, and an error
   toast does not auto-hide. `spec:AST-094` FR39 keeps every drag action
@@ -121,9 +115,9 @@ Consumer migration instructions belong in consumer docs and release notes.
 - **Some modals supply no outlet.** A modal Drawer, Lightbox, or MobileNav
   opens without supplying an outlet, so toasts stay behind it; `spec:AST-003`
   FR18 rehosts globally hosted layers above every native modal.
-- **A toast pushed out mid-collapse can linger.** A toast that a new toast
-  pushes past the cap during its collapse, or that is still collapsing when
-  its viewport moves into or out of any outlet FR12 names, comes back as an invisible zero-height row that never unmounts: it
+- **A toast collapsing through an outlet move can linger.** A toast that is
+  still collapsing when its viewport moves into or out of any outlet FR12
+  names comes back as an invisible zero-height row that never unmounts: it
   keeps the notifications landmark exposed and F6 focuses its hidden dismiss
   button, and it holds one of the `maxVisible` places. With no provider
   above the caller a dismissal called before the fallback viewport
@@ -143,9 +137,6 @@ Consumer migration instructions belong in consumer docs and release notes.
 - **The action row does not track a held pointer.** A press that slides across
   the row's sibling actions does not act on the action it lifts on;
   `family:action-groups` has the row use the shared press tracking.
-- **Same-handler `ignore` toasts both announce.** Two `ignore` toasts with one
-  `uniqueID` raised before the first renders are both announced, and the
-  second replaces the first (FR8, ORD1).
 - **Nested viewports can show two landmarks.** An outer and an inner viewport
   that each hold a toast expose two notifications landmarks (FR11).
 - **Reduced motion is instant on every pointer.** Under reduced motion the
@@ -192,15 +183,15 @@ Consumer migration instructions belong in consumer docs and release notes.
 | ID   | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Basis                    |
 | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
 | FR1  | A card carries `toast` with `type` and shows `body` and, on its first line, `endContent` then a dismiss Button named by `@astryx.toast.dismiss`; long body text wraps below. `renderContent` replaces that layout, receives `body`, `endContent`, `type`, timing, and a `dismiss` function, and gets no injected dismiss control.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Current source and tests |
-| FR2  | With auto-hide on (the default for `info`, off for `error`), the card dismisses with reason `auto` after `autoHideDuration` ms. The timer pauses while the pointer is over the card, focus is inside it, a touch or pen gesture is active, or the window is blurred, and resumes with the remaining time (at least 1 s). Implementation gaps: the pause is one flag, so any pause condition ending resumes the timer while another still holds, and a toast raised while the window is already blurred starts its timer (Current-state impact).                                                                                                                                                                                                                                                                                           | Current source and tests |
+| FR2  | With auto-hide on (the default for `info`, off for `error`), the card dismisses with reason `auto` after `autoHideDuration` ms. The timer pauses while the pointer is over the card, focus is inside it, a touch or pen gesture is active, or the window is blurred, and resumes with the remaining time (at least 1 s). Each pause condition holds the timer on its own: one ending resumes it only when no other still holds, and focus moving between the card's own controls keeps it held. Implementation gap: a toast raised while the window is already blurred starts its timer (Current-state impact).                                                                                                                                                                                                                           | Current source and tests |
 | FR3  | The dismiss button, a swipe, a `dismiss` call, or the returned dismiss function dismiss with reason `manual`; `onHide` fires at most once, when the toast is dismissed, even when dismissed twice during its exit. Implementation gap: with no provider above the caller, a dismissal called before the fallback viewport mounts does nothing, so the toast shows and stays unless it auto-hides (Current-state impact). A toast replaced through `uniqueID` is not dismissed and reports no `onHide`.                                                                                                                                                                                                                                                                                                                                    | Current source and tests |
 | FR4  | A drag toward the position's block edge, from any pointer (`spec:AST-094` FR43), decides once, at release, per `spec:AST-094` FR36–FR37: projected travel past the commit point dismisses, and a release moving back toward the start cancels. A short drag snaps back; horizontal intent, a second touch, or a gesture starting on an interactive descendant does not dismiss. Native page scrolling continues until touch intent matches the dismiss edge. In the default layout the visible dismiss button stays as a non-gesture alternative; custom content supplies its own. Implementation gaps: the shipped rule dismisses on net travel past a distance threshold or a fast flick timed by its own average speed, even after the finger moves back, and recognizes only touch and pen drags, not a mouse (Current-state impact). | Current source and tests |
 | FR5  | A new card slides in from its edge and fades in; a dismissed card collapses and fades before it unmounts; both slide only along the block axis. A dismissal without a swipe uses theme timing; a swipe's commit and snap-back start at the release velocity (`spec:AST-094` FR38). Under reduced motion the entrance and dismissal are an opacity-only fade of 200 ms or less on a coarse pointer or after a touch release (`design:reduced-motion` DR2) and immediate otherwise (DR3), and the card still unmounts. Implementation gaps: a swipe's settle is a CSS transition at theme timing, and under reduced motion every transition, including the row collapse and the swipe's throw, runs for 0.01 ms on every pointer (Current-state impact).                                                                                    | Current source and tests |
 | FR6  | The viewport stacks toasts at `position`, newest nearest the configured edge, with an 8 px gap and no extra space at the edge beyond the safe-area gutter it keeps; it spans the inline axis within its inset, honoring start and end insets in either direction. Each edge sits at the provider's `layerInset`, and a `toast.inset` edge, when set, replaces it (`spec:AST-059` FR6). Implementation gaps: a `toast.inset` edge set to 0 does not replace the provider's value, and an edge opposite the position, such as `top` for a bottom stack, moves the stack to that edge (Current-state impact).                                                                                                                                                                                                                                | Current source and tests |
 | FR7  | With `maxVisible` of 1 or more, at most that many toasts show; when more are raised, the oldest wait hidden and return as visible toasts leave. `maxVisible={0}` shows every toast.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Current source and tests |
-| FR8  | A toast whose `uniqueID` matches a toast the viewport holds, whether shown, hidden by the cap, or exiting, replaces it in place under `overwrite` (and is announced again; the card remounts, so focus inside it drops to the page body), and is dropped unshown and unannounced under `ignore` once the first has rendered. Implementation gaps: two `ignore` toasts with one `uniqueID` raised before the first renders are both announced and the second replaces the first; overwriting a toast hidden by the cap announces it while it is not shown, and nothing is announced when it surfaces (Current-state impact).                                                                                                                                                                                                               | Current source and tests |
+| FR8  | A toast whose `uniqueID` matches a toast the viewport holds, whether shown, hidden by the cap, or exiting, replaces it in place under `overwrite` (and is announced again; the card remounts, so focus inside it drops to the page body), and is dropped unshown and unannounced under `ignore`, even when both are raised before the first renders. Implementation gap: overwriting a toast hidden by the cap announces it while it is not shown, and nothing is announced when it surfaces (Current-state impact).                                                                                                                                                                                                                                                                                                                      | Current source and tests |
 | FR9  | Each shown toast has one announcement owner (`spec:AST-086` FR1): the viewport announces it once, when it is shown, `error` assertively and `info` politely, using the toast's text content, through its own persistent polite and assertive containers, which move with it into a modal (`spec:AST-086` FR10). Unrelated renders do not re-announce. Implementation gaps: the viewport announces through the shared body-level channel, which a modal hides, and announces at dispatch rather than when a toast appears (Current-state impact).                                                                                                                                                                                                                                                                                          | `spec:AST-086`; tests    |
-| FR10 | F6 moves focus to the first control in the newest toast and remembers where focus was. Dismissing a toast that holds focus moves focus to a control in a remaining toast, or back to the remembered element when none remain. Implementation gap: with no control in the target toast, F6 leaves focus where it was and the handoff drops focus to the page, and dismissing the last toast after reaching it with Tab rather than F6 also drops focus to the page (Current-state impact).                                                                                                                                                                                                                                                                                                                                                 | Current source and tests |
+| FR10 | F6 moves focus to the first control in the newest toast. Focus entering the viewport, by F6, Tab or a click, records where it was. Dismissing a toast that holds focus moves focus to a control in a remaining toast, or back to the remembered element when none remain. Implementation gap: with no control in the target toast, F6 leaves focus where it was and the handoff drops focus to the page (Current-state impact).                                                                                                                                                                                                                                                                                                                                                                                                           | Current source and tests |
 | FR11 | While a toast is visible the viewport is a `region` landmark named by `@astryx.toast.viewport`, without `aria-modal`; it exposes no landmark when empty, so an empty nested viewport adds none. Implementation gap: nested viewports that each hold a toast expose two landmarks (Current-state impact).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Current source and tests |
 | FR12 | A top-layer viewport moves into the latest open Dialog, scrim sheet, or modal flow step, following the top of a stack and handing back to the one beneath when it closes, and returns to its place when none remains, keeping each toast, its timer, and focus inside the viewport. It re-enters the top layer in place when a non-modal sheet opens after it, and stays in place when rendered in place, or when an inline dialog, a sheet without a scrim, or a non-modal flow opens.                                                                                                                                                                                                                                                                                                                                                   | `spec:AST-003`; tests    |
 
@@ -221,8 +212,8 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ### Transformation and precedence order
 
-- **ORD1 — Collision.** `ignore` drops a matching toast before announcement,
-  apart from FR8's same-handler gap; `overwrite` replaces it, then announces.
+- **ORD1 — Collision.** `ignore` drops a matching toast before announcement;
+  `overwrite` replaces it, then announces.
 
 ### Performance and resources
 
@@ -265,7 +256,7 @@ button), so no anatomy part can own the `toast` target.
 | Contract | Verification                                                                                            | Representative states                                                                              | Mutation or failure expectation                                                       | Audit section               |
 | -------- | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | --------------------------- |
 | FR1, FR3 | `ToastViewport.test.tsx` layout, custom content, and onHide tests                                       | Default, custom content, double dismiss                                                            | Dropped controls or a repeated `onHide` fails.                                        | `audit:Toast/behavior`      |
-| FR2      | `ToastViewport.test.tsx` blur-pause tests                                                               | Window blur, new toast during pause                                                                | A timer running while paused fails.                                                   | `audit:Toast/behavior`      |
+| FR2      | `ToastViewport.test.tsx` blur-pause and pause-source tests                                              | Window blur, new toast during pause, overlapping pointer/focus/window holds, focus moving inside   | A timer running while paused, or resuming while another hold remains, fails.          | `audit:Toast/behavior`      |
 | FR4, FR5 | `ToastViewport.test.tsx` gesture and motion tests                                                       | Pen and touch thresholds, short drag, horizontal intent, second touch, interactive descendant, RTL | A dismissal from a rejected gesture, a lost snap-back, or off-axis drift fails.       | `audit:Toast/behavior`      |
 | FR6–FR8  | `ToastViewport.test.tsx` placement, cap, and uniqueID tests; `Layer/LayerProvider.test.tsx` inset tests | Each position, cap 1 and an explicit cap, overwrite, ignore                                        | Wrong order, cap, or collision fails.                                                 | `audit:Toast/layout`        |
 | FR9–FR11 | `ToastViewport.test.tsx` announcement, F6, focus, landmark tests                                        | Info, error, StrictMode, nested viewports                                                          | A repeated or wrong-urgency announcement, or focus to the body after F6 entry, fails. | `audit:Toast/accessibility` |
@@ -274,8 +265,8 @@ button), so no anatomy part can own the `toast` target.
 Read from source, with no focused test yet:
 
 - FR1: the `toast` target and its `type` state.
-- FR2: pausing while the pointer is over the card, focus is inside it, or a
-  touch gesture is active, and the 1 s minimum on resume.
+- FR2: pausing while a touch gesture is active, and the 1 s minimum on
+  resume.
 - FR4: a mouse drag dismissing, and a release moving back cancelling; the
   gesture tests assert today's touch-and-pen-only, net-travel rule.
 - FR5: a swipe's settle starting at the release velocity, and the

package/src/Toast/Toast.tsx

@@ -18,7 +18,7 @@
  */
 
 import {useCallback, useEffect, useRef} from 'react';
-import type {ReactNode} from 'react';
+import type {FocusEvent, ReactNode, RefObject} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {Button} from '../Button';
 import {Icon} from '../Icon';
@@ -172,6 +172,9 @@ export function Toast(props: ToastProps) {
   return <ToastSurface {...props} gestureDirection={1} />;
 }
 
+/** A condition that holds a toast's auto-hide timer. */
+type PauseSource = 'pointer' | 'focus' | 'gesture' | 'window';
+
 export function ToastSurface({
   type,
   body,
@@ -185,7 +188,13 @@ export function ToastSurface({
 }: ToastSurfaceProps) {
   const t = useTranslator();
   const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-  const isPausedRef = useRef(false);
+  // Every condition that holds the auto-hide timer (pointer over the card,
+  // focus inside it, a touch or pen gesture, the window blurred) is tracked on
+  // its own, so one ending resumes the timer only when no other still holds.
+  const pauseSourcesRef = useRef<Set<PauseSource>>(new Set());
+  // The card's root, read when a hold ends to drop a focus hold whose focused
+  // control was removed: an unmounting control fires no blur.
+  const cardRootRef = useRef<RefObject<HTMLDivElement | null> | null>(null);
   const remainingRef = useRef(autoHideDuration);
   // Will be initialized by startTimer when actually used
   const startTimeRef = useRef<number | null>(null);
@@ -197,7 +206,7 @@ export function ToastSurface({
   onDismissRef.current = onDismiss;
 
   const startTimer = useCallback(() => {
-    if (!isAutoHide || isPausedRef.current) {
+    if (!isAutoHide || pauseSourcesRef.current.size > 0) {
       return;
     }
     if (timerRef.current) {
@@ -209,28 +218,53 @@ export function ToastSurface({
     }, remainingRef.current);
   }, [isAutoHide]);
 
-  const pauseTimer = useCallback(() => {
-    if (!isAutoHide || isPausedRef.current) {
-      return;
-    }
-    isPausedRef.current = true;
-    if (timerRef.current) {
-      clearTimeout(timerRef.current);
-      timerRef.current = null;
-    }
-    if (startTimeRef.current != null) {
-      const elapsed = Date.now() - startTimeRef.current;
-      remainingRef.current = Math.max(remainingRef.current - elapsed, 1000);
-    }
-  }, [isAutoHide]);
+  const pauseTimer = useCallback(
+    (source: PauseSource) => {
+      if (!isAutoHide) {
+        return;
+      }
+      const sources = pauseSourcesRef.current;
+      const wasRunning = sources.size === 0;
+      sources.add(source);
+      if (!wasRunning) {
+        return;
+      }
+      if (timerRef.current) {
+        clearTimeout(timerRef.current);
+        timerRef.current = null;
+      }
+      if (startTimeRef.current != null) {
+        const elapsed = Date.now() - startTimeRef.current;
+        remainingRef.current = Math.max(remainingRef.current - elapsed, 1000);
+      }
+    },
+    [isAutoHide],
+  );
 
-  const resumeTimer = useCallback(() => {
-    if (!isAutoHide || !isPausedRef.current) {
-      return;
-    }
-    isPausedRef.current = false;
-    startTimer();
-  }, [isAutoHide, startTimer]);
+  const resumeTimer = useCallback(
+    (source: PauseSource) => {
+      if (!isAutoHide) {
+        return;
+      }
+      const sources = pauseSourcesRef.current;
+      if (!sources.delete(source)) {
+        return;
+      }
+      const root = cardRootRef.current?.current;
+      if (
+        sources.has('focus') &&
+        root != null &&
+        !root.contains(document.activeElement)
+      ) {
+        sources.delete('focus');
+      }
+      if (sources.size > 0) {
+        return;
+      }
+      startTimer();
+    },
+    [isAutoHide, startTimer],
+  );
 
   useEffect(() => {
     remainingRef.current = autoHideDuration;
@@ -250,15 +284,48 @@ export function ToastSurface({
     if (!isAutoHide) {
       return;
     }
-    window.addEventListener('blur', pauseTimer);
-    window.addEventListener('focus', resumeTimer);
+    const pauseForWindow = () => pauseTimer('window');
+    const resumeForWindow = () => resumeTimer('window');
+    window.addEventListener('blur', pauseForWindow);
+    window.addEventListener('focus', resumeForWindow);
     return () => {
-      window.removeEventListener('blur', pauseTimer);
-      window.removeEventListener('focus', resumeTimer);
+      window.removeEventListener('blur', pauseForWindow);
+      window.removeEventListener('focus', resumeForWindow);
     };
   }, [isAutoHide, pauseTimer, resumeTimer]);
 
-  const isTimerPaused = useCallback(() => isPausedRef.current, []);
+  const isGesturePausing = useCallback(
+    () => pauseSourcesRef.current.has('gesture'),
+    [],
+  );
+  const pauseForGesture = useCallback(
+    () => pauseTimer('gesture'),
+    [pauseTimer],
+  );
+  const resumeForGesture = useCallback(
+    () => resumeTimer('gesture'),
+    [resumeTimer],
+  );
+  const pauseForPointer = useCallback(
+    () => pauseTimer('pointer'),
+    [pauseTimer],
+  );
+  const resumeForPointer = useCallback(
+    () => resumeTimer('pointer'),
+    [resumeTimer],
+  );
+  const pauseForFocus = useCallback(() => pauseTimer('focus'), [pauseTimer]);
+  const resumeForFocus = useCallback(
+    (event: FocusEvent<HTMLDivElement>) => {
+      // Focus moving between controls inside the card keeps it held.
+      const next = event.relatedTarget;
+      if (next instanceof Node && event.currentTarget.contains(next)) {
+        return;
+      }
+      resumeTimer('focus');
+    },
+    [resumeTimer],
+  );
   const dismissFromGesture = useCallback(() => {
     onDismissRef.current('manual');
   }, []);
@@ -266,12 +333,13 @@ export function ToastSurface({
     direction: gestureDirection,
     enabled: !isExiting,
     canPauseTimer: isAutoHide,
-    isTimerPaused,
-    pauseTimer,
-    resumeTimer,
+    isTimerPaused: isGesturePausing,
+    pauseTimer: pauseForGesture,
+    resumeTimer: resumeForGesture,
     dismiss: dismissFromGesture,
     shouldIgnoreTarget: isInteractiveTarget,
   });
+  cardRootRef.current = rootRef;
 
   const handleDismiss = useCallback(() => {
     onDismiss('manual');
@@ -290,10 +358,10 @@ export function ToastSurface({
       role={isError ? 'alert' : 'status'}
       aria-live={isError ? 'assertive' : 'polite'}
       aria-atomic="true"
-      onMouseEnter={pauseTimer}
-      onMouseLeave={resumeTimer}
-      onFocusCapture={pauseTimer}
-      onBlurCapture={resumeTimer}
+      onMouseEnter={pauseForPointer}
+      onMouseLeave={resumeForPointer}
+      onFocusCapture={pauseForFocus}
+      onBlurCapture={resumeForFocus}
       {...gestureBindings}
       {...mergeProps(
         themeProps('toast', {type}),

package/src/Toast/ToastViewport.tsx

@@ -15,7 +15,6 @@
  */
 
 import {
-  isValidElement,
   useCallback,
   useEffect,
   useLayoutEffect,
@@ -28,6 +27,7 @@ import {createPortal} from 'react-dom';
 import * as stylex from '@stylexjs/stylex';
 import {spacingVars, durationVars, easeVars} from '../theme/tokens.stylex';
 import {mergeProps} from '../utils';
+import {getNodeText} from '../utils/getNodeText';
 import {INTERACTIVE_SELECTORS} from '../hooks/useClickableContainer';
 import {useAnnounce} from '../hooks/useAnnounce';
 import {layerTextReset} from '../Layer/layerTextReset.stylex';
@@ -172,29 +172,6 @@ const styles = stylex.create({
   },
 });
 
-// Flatten a toast's rendered content (title, description, etc.) to the plain
-// text that should be spoken by a screen reader. Only text is announced —
-// interactive endContent is deliberately excluded (it is reachable via F6).
-function getNodeText(node: ReactNode): string {
-  if (node == null || typeof node === 'boolean') {
-    return '';
-  }
-  if (typeof node === 'string') {
-    return node;
-  }
-  if (typeof node === 'number') {
-    return String(node);
-  }
-  if (Array.isArray(node)) {
-    return node.map(getNodeText).filter(Boolean).join(' ');
-  }
-  if (isValidElement(node)) {
-    const {children} = node.props as {children?: ReactNode};
-    return getNodeText(children);
-  }
-  return '';
-}
-
 export interface ToastViewportProps {
   position?: ToastPosition;
   /** Maximum number of visible toasts. @default 5 */
@@ -344,6 +321,19 @@ export function ToastViewport({
   const [exitingIds, setExitingIds] = useState<Set<string>>(new Set());
   const toastsRef = useRef(toasts);
   toastsRef.current = toasts;
+  // The list as last rendered: addToast moves toastsRef ahead of it within
+  // a batch, so this tells a rendered toast from one raised since.
+  const renderedToastsRef = useRef(toasts);
+  renderedToastsRef.current = toasts;
+  // Read by removeToast, which keeps one identity across renders.
+  const maxVisibleRef = useRef(maxVisible);
+  maxVisibleRef.current = maxVisible;
+  // Rendered entries a repeat has replaced in this batch: still found by a
+  // dismissal in the same handler, as before the swap. One replaced before it
+  // rendered was never shown and reports no onHide (Toast.spec.md FR3). A
+  // render starts a new batch.
+  const replacedRef = useRef<Map<string, ToastEntry>>(new Map());
+  replacedRef.current.clear();
 
   const viewportRef = useRef<HTMLDivElement>(null);
   // Toast ids whose exit has begun — guards onHide from double-firing (see
@@ -352,10 +342,13 @@ export function ToastViewport({
   // Toasts dispatched since the last commit, by id: a dismiss() called
   // before the toast first renders still finds it (and its onHide).
   const pendingEntriesRef = useRef<Map<string, ToastEntry>>(new Map());
-  // The element that was focused before the user jumped into the viewport
-  // (via F6). Used to restore focus once all toasts are dismissed so focus
-  // never falls to <body>.
+  // The element that was focused before focus entered the viewport, by F6,
+  // Tab or a click. Used to restore focus once all toasts are dismissed so
+  // focus never falls to <body> (FR10).
   const prevFocusRef = useRef<HTMLElement | null>(null);
+  // The element focus last reached inside the viewport's React tree,
+  // portaled toast content included.
+  const lastFocusedWithinRef = useRef<EventTarget | null>(null);
   // When a toast is dismissed while focus lives inside it, we need to move
   // focus to a sensible neighbor after that toast unmounts. This holds the
   // id of the toast whose removal should trigger a focus handoff.
@@ -410,6 +403,10 @@ export function ToastViewport({
   const addToast = useCallback(
     (entry: ToastEntry) => {
       const {uniqueID, collisionBehavior = 'overwrite'} = entry.options;
+      // A toast holds its uniqueID until it unmounts, leaving included
+      // (Toast.spec.md FR8): an overwrite replaces it in place, and an ignored
+      // namesake is dropped.
+      const holdsUniqueID = (t: ToastEntry) => t.options.uniqueID === uniqueID;
       // Resolve an ignored collision synchronously against the committed list
       // so a suppressed toast is neither shown nor announced. The remaining
       // announce + setToasts run outside the setToasts updater, which React may
@@ -417,16 +414,46 @@ export function ToastViewport({
       if (
         uniqueID &&
         collisionBehavior === 'ignore' &&
-        toastsRef.current.some(t => t.options.uniqueID === uniqueID)
+        toastsRef.current.some(holdsUniqueID)
       ) {
         return;
       }
+      // Only text is announced; interactive endContent is reachable via F6.
       const text = getNodeText(entry.options.body);
       if (text) {
         // Error toasts map to the assertive region (role="alert"); everything
         // else to the polite region (role="status") — mirrors Toast.tsx.
         announce(text, entry.options.type === 'error' ? 'assertive' : 'polite');
       }
+      // A leaving toast that a new one pushes out of the visible window can no
+      // longer finish its exit on screen, so it leaves the list now (it
+      // already reported onHide); otherwise its row would come back collapsed
+      // when the window reached it again, holding a slot and the landmark.
+      const committed = toastsRef.current;
+      const overwritten = uniqueID ? committed.find(holdsUniqueID) : undefined;
+      if (overwritten && renderedToastsRef.current.includes(overwritten)) {
+        replacedRef.current.set(overwritten.id, overwritten);
+      }
+      const projected = overwritten
+        ? committed.map(t => (t === overwritten ? entry : t))
+        : [...committed, entry];
+      // `maxVisible={0}` shows every toast (FR7): nothing leaves the window.
+      const firstVisible = maxVisible > 0 ? projected.length - maxVisible : 0;
+      const cutIds = new Set(
+        projected
+          .filter((t, i) => i < firstVisible && exitingIdsRef.current.has(t.id))
+          .map(t => t.id),
+      );
+      if (cutIds.size > 0) {
+        // Gone from every list, so a later dismissal reports nothing more.
+        for (const id of cutIds) {
+          exitingIdsRef.current.delete(id);
+          pendingEntriesRef.current.delete(id);
+        }
+        setExitingIds(prev => new Set([...prev].filter(id => !cutIds.has(id))));
+      }
+      // Later toasts in the same batch see this one before the next render.
+      toastsRef.current = projected.filter(t => !cutIds.has(t.id));
       const pending = pendingEntriesRef.current;
       if (uniqueID) {
         // An overwrite replaces a toast that has not rendered yet too.
@@ -442,17 +469,17 @@ export function ToastViewport({
       // dismissed. Its settled id is dropped by the prune below, which covers
       // every silent exit with one rule rather than one branch per path.
       setToasts(prev => {
-        if (uniqueID) {
-          const existing = prev.find(t => t.options.uniqueID === uniqueID);
-          if (existing) {
-            // An ignored collision already returned above; overwrite in place.
-            return prev.map(t => (t.options.uniqueID === uniqueID ? entry : t));
-          }
-        }
-        return [...prev, entry];
+        // The cut entries go first, then the choice the projection above made
+        // (by identity): a dismissal in the same handler may have marked the
+        // replaced namesake as leaving since, which must not turn the
+        // overwrite into an append. An ignored collision already returned.
+        const kept = prev.filter(t => !cutIds.has(t.id));
+        return overwritten && kept.includes(overwritten)
+          ? kept.map(t => (t === overwritten ? entry : t))
+          : [...kept, entry];
       });
     },
-    [announce],
+    [announce, maxVisible],
   );
 
   const removeToast = useCallback((id: string, reason: ToastDismissReason) => {
@@ -465,6 +492,7 @@ export function ToastViewport({
     }
     const entry =
       toastsRef.current.find(t => t.id === id) ??
+      replacedRef.current.get(id) ??
       pendingEntriesRef.current.get(id);
     if (entry == null) {
       // Already gone: nothing to hide or report.
@@ -485,29 +513,54 @@ export function ToastViewport({
       dismissedNode.contains(active)
     ) {
       focusHandoffIdRef.current = id;
-      // Pick the neighbor to receive focus while the DOM is still intact:
-      // prefer the next toast, then the previous, else restore.
-      const remaining = toastsRef.current.filter(t => t.id !== id);
-      if (remaining.length > 0) {
-        const dismissedIndex = toastsRef.current.findIndex(t => t.id === id);
-        const next =
-          toastsRef.current[dismissedIndex + 1] ??
-          toastsRef.current[dismissedIndex - 1];
-        pendingFocusRef.current = next ? next.id : 'restore';
-      } else {
-        pendingFocusRef.current = 'restore';
-      }
+      // Pick the toast to receive focus while the DOM is still intact: the
+      // nearest one after it, then before it, that shows once it is gone
+      // (FR10), else restore. The list may already run ahead of the render
+      // within this handler: a toast a repeat replaced has left it, and the
+      // replacement holds its place, so the neighbors are taken around the
+      // replacement, which takes focus only when no neighbor shows.
+      const list = toastsRef.current;
+      const {uniqueID} = entry.options;
+      const ownIndex = list.findIndex(t => t.id === id);
+      const placeIndex =
+        ownIndex >= 0 || uniqueID == null
+          ? ownIndex
+          : list.findIndex(t => t.options.uniqueID === uniqueID);
+      const remaining = list.filter(t => t.id !== id);
+      const max = maxVisibleRef.current;
+      const shown = new Set(max > 0 ? remaining.slice(-max) : remaining);
+      const isShown = (t: ToastEntry) => shown.has(t);
+      const replacement = ownIndex < 0 ? list[placeIndex] : undefined;
+      const next =
+        placeIndex < 0
+          ? undefined
+          : (list.slice(placeIndex + 1).find(isShown) ??
+            list.slice(0, placeIndex).reverse().find(isShown) ??
+            (replacement != null && isShown(replacement)
+              ? replacement
+              : undefined));
+      pendingFocusRef.current = next ? next.id : 'restore';
     }
-    if (dismissedNode == null) {
-      // No row is mounted for it: it is hidden past `maxVisible`, or it has
-      // not rendered yet. Nothing animates out, so it leaves the list now.
+    // A toast this handler has already pushed out of the visible window still
+    // has its row now, but loses it when the batch renders.
+    const index = toastsRef.current.findIndex(t => t.id === id);
+    const isPushedOut =
+      maxVisibleRef.current > 0 &&
+      index >= 0 &&
+      index < toastsRef.current.length - maxVisibleRef.current;
+    if (dismissedNode == null || isPushedOut) {
+      // No row is mounted for it, or none will be: it is hidden past
+      // `maxVisible`, or it has not rendered yet. Nothing animates out, so it
+      // leaves the list now.
       // Waiting for its row to finish exiting would keep it forever: when it
       // surfaced, its row would mount already collapsed, with no transition
       // left to end, and hold a visible slot as an empty row.
       // It leaves the committed list now too, so a second dismissal before
-      // the next render finds nothing to report.
+      // the next render finds nothing to report (nor does a toast a repeat
+      // replaced in this batch).
       exitingIdsRef.current.delete(id);
       pendingEntriesRef.current.delete(id);
+      replacedRef.current.delete(id);
       toastsRef.current = toastsRef.current.filter(t => t.id !== id);
       setToasts(prev => prev.filter(t => t.id !== id));
       return;
@@ -731,6 +784,21 @@ export function ToastViewport({
   const viewport = (
     <div
       ref={viewportRef}
+      onFocus={event => {
+        // Focus entering from outside, however it came, is where a dismissal
+        // of the last toast returns it. React also delivers focus inside a
+        // toast's portaled content here, so focus coming back from the last
+        // element focused within is not an entry, though it sits outside
+        // this element.
+        const from = event.relatedTarget;
+        const fromWithin =
+          from === lastFocusedWithinRef.current ||
+          (from instanceof Node && event.currentTarget.contains(from));
+        lastFocusedWithinRef.current = event.target;
+        if (from instanceof HTMLElement && !fromWithin) {
+          prevFocusRef.current = from;
+        }
+      }}
       role={hasToasts ? 'region' : undefined}
       aria-label={hasToasts ? t('@astryx.toast.viewport') : undefined}
       tabIndex={hasToasts ? -1 : undefined}