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

package/src/Timestamp/Timestamp.spec.md

@@ -44,7 +44,7 @@ system_specs: [spec:AST-009, spec:AST-085]
 | Behavior                | Relative output carries the full absolute date as its default accessible name; relative output, or configured `tooltipEntries`, attach a keyboard-reachable hover card of copyable rows.                                           |
 | End-user impact         | Readers see compact or exact times in their locale; screen-reader users hear the full date and time zone; keyboard users can open and copy the exact time.                                                                         |
 | Builder impact          | None; the record describes shipped behavior.                                                                                                                                                                                       |
-| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. Four implementation gaps are listed under Current-state impact.                                                                                         |
+| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. Three implementation gaps are listed under Current-state impact.                                                                                        |
 | Review checks           | Reject a relative timestamp without the full absolute name when the caller names nothing, a hover card without a tab stop, a change that makes more server markup depend on the server's zone, or a crash on an unparseable value. |
 | Governing rules         | `architecture:internationalization/INV4,INV8,INV10`; `architecture:react-component-runtime/INV1,INV3,INV5`; `architecture:public-component-api/INV5,INV6,INV8`.                                                                    |
 
@@ -70,11 +70,6 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ## Current-state impact
 
-- **Caller name and tab stop replaced (FR5, FR9).** On relative output the
-  full-date name replaces a caller `aria-label`, and while a card is attached
-  the component's `tabIndex={0}` replaces a caller `tabIndex`, where
-  `architecture:public-component-api` INV5 lets a caller's explicit input reach
-  the element.
 - **Focus lost when the card attaches (FR6, AR3).** While the card module
   loads, a fallback `time` with the tab stop renders; when the card attaches it
   replaces that element, so keyboard focus placed on it falls to the page body
@@ -129,11 +124,11 @@ Consumer migration instructions belong in consumer docs and release notes.
 | FR2 | `auto` shows `relative` when the instant is within `autoThreshold` seconds of now (default seven days) and `date_time` otherwise. `relative` uses the locale's long relative phrase and `relative_short` its narrow phrase; a value a few seconds in the future reads as "now". Absolute formats use the shared instant formatter in the provider locale with Gregorian years; `system_*` formats are machine-readable, and `unix_seconds` is zone-independent. `isTimezoneShown` appends the zone abbreviation to `date_time` and `time` only.                                                                                                                                                                                                                                                                                                                | Current source and tests |
 | FR3 | Server markup does not depend on the server's time zone and hydrates without a mismatch. A format that needs the clock renders `date_time` in UTC with the zone shown until the client can read the clock; the client then shows the resolved format without committing the UTC placeholder. Implementation gap: absolute formats other than `unix_seconds` render in the host's time zone, so their server markup depends on the server's zone and hydrating it in another zone produces a text mismatch (Current-state impact).                                                                                                                                                                                                                                                                                                                              | Current source and tests |
 | FR4 | With `isLive` and relative output, the clock refreshes every second under a minute old, every 30 seconds under an hour, every minute under a day, and every five minutes beyond; the timer is cleared on unmount or when the inputs change. Locale changes update the output live.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Current source and tests |
-| FR5 | Relative output is named by the full absolute date and the long time-zone name unless a caller names the element; absolute output adds no name. A caller's explicit `aria-label` reaches the element (`architecture:public-component-api` INV5). Implementation gap: the component's full-date name replaces a caller `aria-label` on relative output (Current-state impact).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Current source and tests |
+| FR5 | Relative output is named by the full absolute date and the long time-zone name unless a caller names the element; absolute output adds no name. A caller's explicit `aria-label` reaches the element (`architecture:public-component-api` INV5).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Current source and tests |
 | FR6 | When `hasTooltip` is true and the output is relative or `tooltipEntries` is non-empty, a lazily loaded HoverCard named "Timestamp details" attaches above the timestamp, opening on hover and on keyboard focus; the `time` element gains `tabIndex={0}`. Otherwise no card renders and no tab stop is added. Focus placed on the timestamp stays there when the card attaches (`spec:AST-085` FR4). Implementation gap: while the card module loads, a fallback `time` with the tab stop renders, and attaching the card replaces it, so focus placed on it falls to the page body and no card opens (Current-state impact).                                                                                                                                                                                                                                  | Current source and tests |
 | FR7 | The card is a description list in a grid: an optional label column (present when any row has a label), the value column, and a trailing action column (present when any row is copyable). Without entries it has one copyable row with the full absolute time in the viewer's zone. Each configured entry is one row in the given order, rendered in its own time zone and format, read-only unless `isCopyable`. An unknown time zone does not crash. A description list holds only name-value groups (WCAG 2.2 1.3.1). Implementation gaps: once any row is copyable, every row carries an action-cell `div` inside its row group (empty on read-only rows), so the open card fails the `definition-list` structure check, and a card with no labelled rows, the default card included, renders each row as a lone `dd` with no `dt` (Current-state impact). | Current source and tests |
 | FR8 | A copy button is a small ghost IconButton on the `timestamp-copy-button` target, named "Copy {value}" with a "Copy" tooltip; activating it writes the row's value to the clipboard, switches to a check icon and the "Copied" name and tooltip for 1.5 seconds, and announces "Copied" politely. A clipboard rejection does nothing.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Current source and tests |
-| FR9 | `ref`, `data-testid`, and other supported DOM, ARIA, data, and event props reach the `time` element; `xstyle`, `className`, and `style` reach the Text wrapper. A caller `aria-labelledby` names the element in place of FR5's name. A caller's explicit `tabIndex` reaches the element (`architecture:public-component-api` INV5). Implementation gap: while a card is attached, the component's `tabIndex={0}` replaces a caller `tabIndex` (Current-state impact).                                                                                                                                                                                                                                                                                                                                                                                          | Current source and tests |
+| FR9 | `ref`, `data-testid`, and other supported DOM, ARIA, data, and event props reach the `time` element; `xstyle`, `className`, and `style` reach the Text wrapper. A caller `aria-labelledby` names the element in place of FR5's name. A caller's explicit `tabIndex` reaches the element (`architecture:public-component-api` INV5).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Current source and tests |
 
 ### Allowed variation
 
@@ -161,8 +156,7 @@ Consumer migration instructions belong in consumer docs and release notes.
 - **ORD2 — Card rows.** Non-empty `tooltipEntries` → the default full-date row.
 - **ORD3 — Time element attributes.** `datetime` and `data-testid` are set,
   then caller props; the relative name and the card's tab stop apply only
-  where the caller sets no `aria-label` or `tabIndex` (today they overwrite
-  the caller's, the FR5 and FR9 gaps).
+  where the caller sets no `aria-label` or `tabIndex`.
 
 ### Performance and resources
 
@@ -230,10 +224,10 @@ Consumer migration instructions belong in consumer docs and release notes.
 | FR1, FR2            | `Timestamp.test.tsx` format, auto, locale, and invalid-value tests; stable visual baseline `core-timestamp--default` | Every format; thresholds; locales; unparseable values; default | A wrong phrase, a crossed tier, a non-Gregorian year, a missing `time` element or `datetime`, a crash, or a missing development warning for an unparseable value fails; a changed default type or color comes back changed for review. Gap: no test asserts the `timestamp` target or its format reflection.                                                                                                                                              | `audit:Timestamp/behavior` |
 | FR3                 | `Timestamp.test.tsx` server-rendering suite                                                                          | Server zones; hydration                                        | Zone-dependent markup, a hydration mismatch, or a committed placeholder fails. Gap: no test covers an absolute format rendered on a server in another zone.                                                                                                                                                                                                                                                                                               | `audit:Timestamp/behavior` |
 | FR4, PR1            | `Timestamp.test.tsx` live-update and locale tests                                                                    | Live relative output; locale change                            | A missing refresh or a stale locale fails. Gap: the per-tier refresh intervals and the timer cleanup on unmount or input change have no automated check.                                                                                                                                                                                                                                                                                                  | `audit:Timestamp/behavior` |
-| FR5, AR2            | `Timestamp.test.tsx` naming tests                                                                                    | Relative, absolute, time-zone spelling                         | A missing or short-zone name, or a name on absolute output, fails. The pass-through test "keeps its own spelled-out label on a relative timestamp" pins the caller-`aria-label` replacement, which is the recorded gap, not the contract.                                                                                                                                                                                                                 | `audit:Timestamp/a11y`     |
+| FR5, AR2            | `Timestamp.test.tsx` naming tests                                                                                    | Relative, absolute, time-zone spelling                         | A missing or short-zone name, or a name on absolute output, fails. A caller `aria-label` replaced on relative output fails.                                                                                                                                                                                                                                                                                                                               | `audit:Timestamp/a11y`     |
 | FR6, AR3            | `Timestamp.test.tsx` keyboard-reachability suite                                                                     | Relative, absolute, disabled, entries removed                  | A missing tab stop, `aria-expanded` on the trigger, or a stray tab stop fails. The aria-expanded test also pins `aria-haspopup` on the Text wrapper, which is current behavior, not contract. Gap: no test covers focus on the timestamp while the card module loads, or `aria-controls`.                                                                                                                                                                 | `audit:Timestamp/a11y`     |
 | FR7, FR8, AR4       | `Timestamp.test.tsx` hover-card suites; `tooltipEntries.test.ts`; `useClipboard.test.tsx`                            | Default row, entries, copyable rows, unknown zone              | A wrong row count or order, an unpaired label, a copy button on a read-only row, a wrong copied value, a missing copied state, or a missing announcement fails. Gap: no check runs the `definition-list` structure rule on the open card (the recorded gap); the grid columns and the 1.5-second reset have no automated check; `useClipboard.test.tsx` covers the clipboard-rejection no-op. The lone-`dd` rows of a label-less card are also unchecked. | `audit:Timestamp/behavior` |
-| FR9                 | `Timestamp.test.tsx` ref, test-id, and pass-through tests                                                            | Ref, test id, caller props                                     | A ref, test id, or caller prop missing from the `time` element fails. Gap: no test asserts that `xstyle`, `className`, and `style` reach the Text wrapper, or covers a caller `aria-labelledby` or `tabIndex`.                                                                                                                                                                                                                                            | `audit:Timestamp/behavior` |
+| FR9                 | `Timestamp.test.tsx` ref, test-id, and pass-through tests                                                            | Ref, test id, caller props                                     | A ref, test id, or caller prop missing from the `time` element fails. A caller `tabIndex` replaced while a card is attached fails. Gap: no test asserts that `xstyle`, `className`, and `style` reach the Text wrapper, or covers a caller `aria-labelledby`.                                                                                                                                                                                             | `audit:Timestamp/behavior` |
 | Theming anatomy map | `scripts/check-knowledge.mjs`                                                                                        | Consumer anatomy, targets, HoverCard delegate                  | Missing, extra, or stale mappings fail repository validation.                                                                                                                                                                                                                                                                                                                                                                                             | `audit:Timestamp/theming`  |
 | AR1                 | `Timestamp.test.tsx` `datetime` tests                                                                                | `date_time`; `date`                                            | A missing or wrong ISO `datetime` on `date_time`, or a missing one on `date`, fails. Gap: no test asserts the exact `datetime` on relative or other absolute formats.                                                                                                                                                                                                                                                                                     | `audit:Timestamp/a11y`     |
 | AR2, AR4            | Accessibility-tree evidence (`spec:AST-009` FR3)                                                                     | Relative output; copy buttons                                  | Gap: no accessibility-tree check proves the computed name of relative output or the copy-button names; the unit tests query the DOM.                                                                                                                                                                                                                                                                                                                      | `audit:Timestamp/a11y`     |

package/src/Timestamp/Timestamp.test.tsx

@@ -768,6 +768,20 @@ describe('Timestamp', () => {
       HTMLElement.prototype.hidePopover = originalHidePopover;
     });
 
+    it("keeps a caller's tabIndex while the hover card is attached (FR9)", async () => {
+      render(
+        <Timestamp
+          value={Date.now() / 1000 - 3600}
+          format="relative"
+          tabIndex={-1}
+          data-testid="ts"
+        />,
+      );
+      expect(screen.getByTestId('ts')).toHaveAttribute('tabindex', '-1');
+      await openTimestampHoverCard();
+      expect(screen.getByTestId('ts')).toHaveAttribute('tabindex', '-1');
+    });
+
     it('makes the <time> element focusable while the hover card is attached', () => {
       render(
         <Timestamp
@@ -1449,7 +1463,7 @@ describe('Timestamp pass-through props', () => {
     expect(time).toHaveAttribute('data-source', 'cms');
   });
 
-  it('keeps its own spelled-out label on a relative timestamp', () => {
+  it("keeps a caller's aria-label on a relative timestamp (FR5)", () => {
     render(
       <Timestamp
         value={Date.now()}
@@ -1463,10 +1477,21 @@ describe('Timestamp pass-through props', () => {
     expect({
       ariaLabel: stamp.getAttribute('aria-label'),
       dataSource: stamp.getAttribute('data-source'),
-    }).toEqual({
-      ariaLabel: expect.not.stringMatching(/^Caller label$/),
-      dataSource: 'cms',
-    });
+    }).toEqual({ariaLabel: 'Caller label', dataSource: 'cms'});
+  });
+
+  it('names a relative timestamp by the full date when the caller names nothing (FR5)', () => {
+    render(
+      <Timestamp
+        value={Date.now()}
+        format="relative"
+        aria-label={undefined}
+        data-testid="stamp"
+      />,
+    );
+    expect(screen.getByTestId('stamp').getAttribute('aria-label')).toMatch(
+      /\d{4}/,
+    );
   });
 });
 

package/src/Timestamp/Timestamp.tsx

@@ -443,7 +443,10 @@ export function Timestamp({
         // before rendering — but keep the guard local: an empty aria-label
         // must be omitted entirely (not rendered as aria-label="") so AT
         // falls back to reading the visible <time> content.
-        {...(isRelativeFormat(effectiveFormat) && ariaLabelText !== ''
+        // A caller's own name wins (`component:Timestamp` FR5).
+        {...(isRelativeFormat(effectiveFormat) &&
+        ariaLabelText !== '' &&
+        rest['aria-label'] == null
           ? {'aria-label': ariaLabelText}
           : {})}
         // The hover card is anchored here with focusTrigger="always", which
@@ -454,7 +457,8 @@ export function Timestamp({
         // gratuitous tab stops otherwise. The card carries its own
         // dashed-underline hover indication as the affordance, so the anchor
         // needs no separate focus outline.
-        {...(showTooltip ? {tabIndex: 0} : {})}>
+        // A caller's own tabIndex wins (`component:Timestamp` FR9).
+        {...(showTooltip && rest.tabIndex == null ? {tabIndex: 0} : {})}>
         {displayText}
       </time>
     </Text>

package/src/Timestamp/TimestampHoverCard.tsx

@@ -26,11 +26,11 @@
 import type {ReactNode} from 'react';
 import {useCallback} from 'react';
 import * as stylex from '@stylexjs/stylex';
-import {HoverCard} from '../HoverCard';
-import {IconButton} from '../IconButton';
-import {Icon} from '../Icon';
+import {HoverCard} from '../HoverCard/HoverCard';
+import {IconButton} from '../IconButton/IconButton';
+import {Icon} from '../Icon/Icon';
 import {useClipboard} from '../hooks/useClipboard';
-import {useTranslator} from '../i18n';
+import {useTranslator} from '../i18n/useTranslator';
 import {themeProps} from '../utils/themeProps';
 import {
   colorVars,

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}),