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

package/src/Resizable/useResizable.ts

@@ -306,6 +306,34 @@ const SERVER_BASIS = 1200;
 
 /** A store that never changes on its own; the snapshot is re-read on render. */
 const noopSubscribe = () => () => {};
+
+// The window snapshots are module functions, so their identity is stable:
+// React re-reads a snapshot after the commit whenever getSnapshot is a new
+// function, and a window size read after the DOM changed forces a layout of
+// the whole page. With these, the window is read during render only.
+
+/** The viewport width, the basis without a container. */
+function readViewportBasis(): number {
+  return typeof window === 'undefined' ? SERVER_BASIS : window.innerWidth;
+}
+
+function readServerBasis(): number {
+  return SERVER_BASIS;
+}
+
+/** The window's extent along a horizontal hook's axis. */
+function readWindowWidth(): number | null {
+  return typeof window === 'undefined' ? null : window.innerWidth;
+}
+
+/** The window's extent along a vertical hook's axis. */
+function readWindowHeight(): number | null {
+  return typeof window === 'undefined' ? null : window.innerHeight;
+}
+
+function readNoWindowExtent(): null {
+  return null;
+}
 const DEFAULT_SIZE_FALLBACK = 250;
 const RESIZABLE_SIZE_GUIDANCE =
   'Use a non-negative number of pixels, an exact "Npx" string, an exact ' +
@@ -698,8 +726,8 @@ function useSingleResizable(config: UseResizableSingleConfig): ResizableRegion {
   );
   const viewportBasis = useSyncExternalStore(
     subscribeToViewport,
-    () => (typeof window === 'undefined' ? SERVER_BASIS : window.innerWidth),
-    () => SERVER_BASIS,
+    readViewportBasis,
+    readServerBasis,
   );
 
   // The window's extent along the hook's axis, for the REPORTED maximum of an
@@ -710,13 +738,8 @@ function useSingleResizable(config: UseResizableSingleConfig): ResizableRegion {
   // (component:Resizable Performance and resources).
   const windowExtent = useSyncExternalStore(
     noopSubscribe,
-    () =>
-      typeof window === 'undefined'
-        ? null
-        : direction === 'vertical'
-          ? window.innerHeight
-          : window.innerWidth,
-    () => null,
+    direction === 'vertical' ? readWindowHeight : readWindowWidth,
+    readNoWindowExtent,
   );
 
   // With a container, its content box is the basis; without one, the released
@@ -742,10 +765,14 @@ function useSingleResizable(config: UseResizableSingleConfig): ResizableRegion {
   // otherwise move the bound under the pointer; the new basis applies once the
   // gesture ends.
   const gestureBasisRef = useRef<number | null>(null);
-  // Only forces the render that releases the frozen basis when a gesture ends.
+  // Only forces the render that ends a gesture: it releases the frozen basis,
+  // and its commit writes the size the gesture settled on.
   const [gestureTick, setGestureTick] = useState(0);
   void gestureTick;
   const basis = gestureBasisRef.current ?? liveBasis;
+  // The frozen basis also marks a gesture in flight, from `_onResizeStart`
+  // until `_onResizeEnd` or `_onResizeCancel`.
+  const isGestureActive = gestureBasisRef.current != null;
 
   const didWarnMinRef = useRef(false);
   const didWarnMaxRef = useRef(false);
@@ -922,15 +949,52 @@ function useSingleResizable(config: UseResizableSingleConfig): ResizableRegion {
     }
   }, [resolvedMin, resolvedMax]);
 
+  // The size a gesture in flight has reached, for a region that unmounts
+  // before the gesture ends.
+  const pendingWriteRef = useRef<{
+    key: string;
+    state: PersistedResizableState;
+  } | null>(null);
+
   useEffect(() => {
+    // Synchronizes the `autoSaveId` entry in localStorage with the size.
     // Nothing is written while the basis is still the temporary stand-in. The
     // size on such a render is a placeholder, and persisting it overwrites the
     // real saved size with a value derived from a basis that was never real
     // (AST-010 Platform support, FR9).
-    if (autoSaveId && isBasisMeasured) {
-      persistState(autoSaveId, {size, isCollapsed});
+    if (!autoSaveId || !isBasisMeasured) {
+      pendingWriteRef.current = null;
+      return;
     }
-  }, [size, isCollapsed, autoSaveId, isBasisMeasured]);
+    // Nor while a gesture is in flight. A drag commits a new size on every
+    // pointer move, and each write reaches every other open document of the
+    // origin as a `storage` event.
+    if (isGestureActive) {
+      pendingWriteRef.current = {key: autoSaveId, state: {size, isCollapsed}};
+      return;
+    }
+    // A gesture's one write happens here, in the commit that applies its
+    // release, not in the handler that ended it: this render is the first to
+    // know the final size. A basis that changed mid-gesture applies only at
+    // the release and can re-clamp the size (AST-010 FR7), and a move the
+    // release arrived before renders together with it. The handler sees
+    // neither.
+    pendingWriteRef.current = null;
+    persistState(autoSaveId, {size, isCollapsed});
+  }, [size, isCollapsed, autoSaveId, isBasisMeasured, isGestureActive]);
+
+  // A region that unmounts mid-gesture never commits a release, so the size
+  // the gesture reached is written on the way out.
+  useEffect(
+    () => () => {
+      const pending = pendingWriteRef.current;
+      pendingWriteRef.current = null;
+      if (pending != null) {
+        persistState(pending.key, pending.state);
+      }
+    },
+    [],
+  );
 
   const collapse = useCallback(() => {
     // The already-collapsed guard keeps a repeated call from re-notifying a
@@ -1026,7 +1090,7 @@ function useSingleResizable(config: UseResizableSingleConfig): ResizableRegion {
   );
 
   // Releasing the frozen basis needs a render to apply whatever the basis
-  // became during the gesture.
+  // became during the gesture; that render's commit writes the final size.
   const releaseGestureBasis = useCallback(() => {
     if (gestureBasisRef.current != null) {
       gestureBasisRef.current = null;
@@ -1035,7 +1099,8 @@ function useSingleResizable(config: UseResizableSingleConfig): ResizableRegion {
   }, []);
 
   const onResizeEnd = useCallback(() => {
-    // Sizes are already committed during move; only the basis is held.
+    // Sizes are already committed during move; the basis is held, and the
+    // commit that releases it writes the final size to storage.
     releaseGestureBasis();
   }, [releaseGestureBasis]);
 
@@ -1043,7 +1108,8 @@ function useSingleResizable(config: UseResizableSingleConfig): ResizableRegion {
   // capture, a handle unmounted mid-drag — is still over. It does not signal a
   // resize end (that is #5297's contract, and the sizes were committed during
   // move anyway), but the basis it froze has to come back, or every later
-  // percentage bound stays pinned to the container size at grab time.
+  // percentage bound stays pinned to the container size at grab time, and the
+  // size it reached has to reach storage.
   const onResizeCancel = releaseGestureBasis;
 
   // The maximum a handle REPORTS (End uses only a configured maximum). A

package/src/SegmentedControl/SegmentedControlItem.tsx

@@ -210,11 +210,17 @@ export function SegmentedControlItem({
 
   // Consumer-first: a consumer onClick can call preventDefault() to opt out of
   // selection; otherwise selection proceeds when enabled and not selected.
-  const handleClick = composeEventHandlers(onClickProp, () => {
-    if (!isItemDisabled && !isSelected) {
-      ctx.onChange(value);
-    }
-  });
+  // A disabled segment invokes no caller callback (spec:AST-085 FR2), so the
+  // consumer onClick is left out while it is disabled, including the selected
+  // segment of a group disabled with a reason, which stays focusable.
+  const handleClick = composeEventHandlers(
+    isItemDisabled ? undefined : onClickProp,
+    () => {
+      if (!isItemDisabled && !isSelected) {
+        ctx.onChange(value);
+      }
+    },
+  );
 
   const iconElement = icon ? (
     <span {...stylex.props(styles.icon, iconSizeStyles[size])}>{icon}</span>

package/src/Selector/Selector.tsx

@@ -1060,11 +1060,9 @@ export function Selector<T extends SelectorOptionType>(
   useBusyAnnouncement(isBusy, t('@astryx.spinner.loading'), triggerRef);
   const announce = useAnnounce();
 
-  // Disabled-reason tooltip. Disabled controls swallow pointer events, so the
-  // tooltip listeners attach to the trigger container (which already exists)
-  // and the trigger button stays perceivable via aria-disabled instead of the
-  // disabled attribute. Activation is blocked by the isDisabled guards in
-  // useCombobox (onTriggerClick / onKeyDown).
+  // Disabled-reason tooltip. The container receives hover and bubbled focus
+  // while the trigger stays focusable via aria-disabled. Opening and selection
+  // are guarded independently, including options in an already-open surface.
   const showsDisabledMessage = isDisabled && !!disabledMessage;
   const disabledMessageTooltip = useTooltip({
     placement: 'above',
@@ -1327,6 +1325,11 @@ export function Selector<T extends SelectorOptionType>(
 
   const commitValue = useCallback(
     (newValue: string) => {
+      // A surface or pointer gesture can outlive the enabled state that opened
+      // it. Enforce current availability before callbacks or optimistic state.
+      if (isDisabled || isEffectivelyReadOnly) {
+        return;
+      }
       onChange?.(newValue);
       if (changeAction) {
         startTransition(async () => {
@@ -1335,7 +1338,14 @@ export function Selector<T extends SelectorOptionType>(
         });
       }
     },
-    [onChange, changeAction, startTransition, setOptimisticValue],
+    [
+      isDisabled,
+      isEffectivelyReadOnly,
+      onChange,
+      changeAction,
+      startTransition,
+      setOptimisticValue,
+    ],
   );
 
   // Selector behavior (keyboard nav, selection)

package/src/Selector/hooks.ts

@@ -301,13 +301,13 @@ export function useCombobox<T extends ComboboxOption = SelectorOptionData>({
 
   const selectItem = useCallback(
     (item: T) => {
-      if (item.disabled) {
+      if (isDisabled || item.disabled) {
         return;
       }
       onSelect?.(item.value);
       closeAndReset();
     },
-    [onSelect, closeAndReset],
+    [isDisabled, onSelect, closeAndReset],
   );
 
   const onTriggerClick = useCallback(() => {

package/src/Selector/useSelectorPresentation.ts

@@ -34,6 +34,13 @@ interface UseSelectorPresentationOptions {
   onShow: () => void;
   popoverOptions: Omit<UsePopoverOptions, 'onHide' | 'onShow'>;
   triggerRef: RefObject<HTMLElement | null>;
+  /**
+   * Return focus to the trigger on every close, even when a press already
+   * moved focus to another element. A caller-rendered trigger needs this
+   * (spec:AST-055 AR3); the built-in trigger leaves focus where the press put
+   * it (spec:Popover AR4).
+   */
+  isFocusReturnAlways?: boolean;
 }
 
 interface SelectorPresentationController {
@@ -55,6 +62,7 @@ export function useSelectorPresentation({
   onShow,
   popoverOptions,
   triggerRef,
+  isFocusReturnAlways = false,
 }: UseSelectorPresentationOptions): SelectorPresentationController {
   const resolvedPresentation = useAdaptivePresentation(presentation);
   const activePresentationRef =
@@ -68,6 +76,9 @@ export function useSelectorPresentation({
   const onHideRef = useRef(onHide);
   const onShowRef = useRef(onShow);
   const didShowPopoverRef = useRef(false);
+  // The open list's container, read when the popover hides to tell focus that
+  // is still inside the list from focus that moved to another element.
+  const popoverContentRef = useRef<HTMLDivElement | null>(null);
   const {
     isFocusRingSuppressed,
     onFocusReturnTargetFocus,
@@ -78,10 +89,26 @@ export function useSelectorPresentation({
   onShowRef.current = onShow;
 
   const handlePopoverHide = useCallback(() => {
-    prepareFocusReturn();
     onHideRef.current();
-    triggerRef.current?.focus();
-  }, [prepareFocusReturn, triggerRef]);
+    const trigger = triggerRef.current;
+    // A light dismiss caused by pressing another focusable element has already
+    // moved focus there; taking it back would leave the next key on this
+    // closed Selector (spec:Popover AR4 returns focus only when it would
+    // otherwise be lost). Escape, a choice in the list, or a press on nothing
+    // focusable still returns focus to the trigger.
+    const active = document.activeElement;
+    const focusLandedElsewhere =
+      !isFocusReturnAlways &&
+      active instanceof HTMLElement &&
+      active !== document.body &&
+      active !== trigger &&
+      !popoverContentRef.current?.contains(active);
+    if (focusLandedElsewhere) {
+      return;
+    }
+    prepareFocusReturn();
+    trigger?.focus();
+  }, [isFocusReturnAlways, prepareFocusReturn, triggerRef]);
   const handlePopoverShow = useCallback(() => {
     didShowPopoverRef.current = true;
     resetFocusReturn();
@@ -92,6 +119,7 @@ export function useSelectorPresentation({
     onHide: handlePopoverHide,
     onShow: handlePopoverShow,
   });
+  popoverContentRef.current = popover.contentRef.current;
   const {hide: hidePopover, show: showPopover} = popover;
 
   const show = useCallback((): boolean => {

package/src/SideNav/SideNavItem.spec.md

@@ -39,7 +39,7 @@ system_specs: [spec:AST-085]
 | Behavior                | One SideNav row: a link or button with optional icon and passive end content, optional row-level actions beside it, and optional nested children that can expand and collapse. In a collapsed rail it is icon-only with a tooltip or a flyout.                |
 | End-user impact         | Users see and hear the current page, reach row actions before nested items, expand or collapse groups without navigating, and return to the page after choosing a destination in the mobile drawer.                                                           |
 | Builder impact          | None.                                                                                                                                                                                                                                                         |
-| Compatibility/readiness | Records shipped behavior; no public change. Four implementation gaps (see Current-state impact).                                                                                                                                                              |
+| Compatibility/readiness | Records shipped behavior; no public change. Three implementation gaps (see Current-state impact).                                                                                                                                                             |
 | Review checks           | Reject an interactive control rendered inside the primary element, a link that also toggles collapse, a toggle or action that activates the row, collapsed children that stay reachable, or a drawer activation that leaves the drawer open after navigating. |
 | Governing rules         | `component:SideNav` FR1–FR5, DD1 (nesting and row geometry); `family:navigation-destinations`; `architecture:interaction-modality`; `architecture:public-component-api`.                                                                                      |
 
@@ -68,10 +68,6 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ## Current-state impact
 
-- **A disabled item leaves the tab order.** A disabled item renders a
-  `<button>` with the native `disabled` attribute, so it is skipped by Tab and
-  exposes no focusable disabled state. `spec:AST-085` FR1 has a disabled control
-  expose `aria-disabled="true"` and keep its tab stop.
 - **A disabled parent stays operable in a collapsed rail.** In a collapsed rail,
   a disabled item with children renders its flyout trigger with neither
   `disabled` nor `aria-disabled`, so it keeps its tab stop and announces no
@@ -125,7 +121,7 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 | ID   | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Basis                    |
 | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
-| FR1  | The primary element is the `as` component, else the `LinkProvider` link, else `<a>`, when `href` is set and the item is enabled; otherwise a `<button type="button">`. A disabled item MUST stay focusable with `aria-disabled="true"` and keep its tab stop (`spec:AST-085` FR1). Implementation gap: a disabled item renders native `disabled` instead, which removes it from the tab order. It shows the icon (`selectedIcon` when selected and given), the label, `endContent`, and, for a whole-row collapsible item, a chevron. `endContent` is passive and renders inside the primary element.                                                                       | Current source and tests |
+| FR1  | The primary element is the `as` component, else the `LinkProvider` link, else `<a>`, when `href` is set and the item is enabled; otherwise a `<button type="button">`. A disabled item stays focusable with `aria-disabled="true"`, keeps its tab stop, and keeps focus when it becomes disabled (`spec:AST-085` FR1, FR4). It shows the icon (`selectedIcon` when selected and given), the label, `endContent`, and, for a whole-row collapsible item, a chevron. `endContent` is passive and renders inside the primary element.                                                                                                                                          | Current source and tests |
 | FR2  | In an expanded rail and on a collapsed leaf, `isSelected` sets `aria-current="page"` on the primary element, never on a row wrapper. A collapsed parent's flyout trigger carries no `aria-current`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Current source and tests |
 | FR3  | A disabled item does not fire `onClick` or navigate. Its row actions stay operable.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Current source and tests |
 | FR4  | `actions` render as siblings of the primary element at the row's trailing edge, after the toggle and before nested children in DOM and focus order, at the row's control size (`sm`) unless a control sets its own (`architecture:component-size-cascade`). Clicking an action neither activates nor toggles the row. A row wrapper exists only when there are actions or an independent toggle; a falsy `actions` adds none.                                                                                                                                                                                                                                               | Current source and tests |
@@ -146,16 +142,16 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ### Representative states
 
-| State                      | Required invariant                                                                     | Allowed variation |
-| -------------------------- | -------------------------------------------------------------------------------------- | ----------------- |
-| Link, selected             | `aria-current="page"` on the link; selected icon if given.                             | Fill.             |
-| Disabled button            | `aria-disabled`; focusable; no `onClick`. Implementation gap: native `disabled` (FR1). | Muted styling.    |
-| Collapsible without action | Whole row toggles; chevron turns.                                                      | —                 |
-| Collapsible with `href`    | Link navigates; separate toggle button collapses.                                      | —                 |
-| Actions                    | Actions after toggle, before children; never activate the row.                         | Action content.   |
-| Collapsed rail leaf        | Icon-only; tooltip with label.                                                         | —                 |
-| Collapsed rail parent      | Icon-only trigger; flyout with header and children.                                    | Delay.            |
-| Mobile drawer              | Activation closes the drawer.                                                          | —                 |
+| State                      | Required invariant                                             | Allowed variation |
+| -------------------------- | -------------------------------------------------------------- | ----------------- |
+| Link, selected             | `aria-current="page"` on the link; selected icon if given.     | Fill.             |
+| Disabled button            | `aria-disabled`; focusable; no `onClick`.                      | Muted styling.    |
+| Collapsible without action | Whole row toggles; chevron turns.                              | —                 |
+| Collapsible with `href`    | Link navigates; separate toggle button collapses.              | —                 |
+| Actions                    | Actions after toggle, before children; never activate the row. | Action content.   |
+| Collapsed rail leaf        | Icon-only; tooltip with label.                                 | —                 |
+| Collapsed rail parent      | Icon-only trigger; flyout with header and children.            | Delay.            |
+| Mobile drawer              | Activation closes the drawer.                                  | —                 |
 
 ### Transformation and precedence order
 
@@ -211,16 +207,10 @@ is recorded. Row geometry visual intent is `component:SideNav` DD1.
 | FR11          | `SideNav.test.tsx` focus ring suite                                 | Plain, split, actions rows                                                                                                | Missing shared ring classes fail.                                                 | `audit:SideNavItem/accessibility` |
 | FR3, FR7, FR9 | `SideNav.test.tsx` keyboard operation and focus management suites   | Tab order, Enter/Space toggle, flyout Escape                                                                              | Lost order, a stranded focus, or no focus return fails.                           | `audit:SideNavItem/accessibility` |
 
-Pending conformance: the SideNavItem suite's native-`disabled` assertion and
-the keyboard suite's disabled Tab-skip assertion pin FR1's implementation gap;
-they change when disabled items follow `spec:AST-085`.
-
 Read from source, with no focused test yet:
 
-- FR1 and ORD1–ORD2: a disabled item with `href` rendering a button, the
-  required focusable `aria-disabled` shape (no item renders it yet), the
-  button's `type="button"`, the icon, the selected-icon swap, and the whole-row
-  chevron.
+- FR1 and ORD1–ORD2: the button's `type="button"`, the icon, the
+  selected-icon swap, and the whole-row chevron.
 - FR4: the actions' trailing-edge placement and the wrapper for an independent
   toggle without actions.
 - FR5: the forwarded `ref` and `xstyle` on the outer box.

package/src/SideNav/SideNavItem.tsx

@@ -13,8 +13,8 @@
  * provided and fall back to `label` when it is missing or blank. Their label
  * tooltip binds to the interactive control through a callback ref, so hover,
  * keyboard focus, and `aria-describedby` follow the control from the first
- * collapsed render. A disabled control takes neither pointer nor focus, so its
- * row is the tooltip's trigger instead.
+ * collapsed render. A disabled control takes no pointer, so its row listens
+ * for the tooltip instead, while the control keeps focus and the description.
  *
  * Collapsed items with children open their submenu flyout through
  * `useMenuHover`, the shared hover-intent hook (same one `SideNavHeading` and
@@ -74,6 +74,7 @@ import {
 import {useSideNavRenderMode} from './SideNavRenderContext';
 import {useAppShellMobile} from '../AppShell/AppShellMobileContext';
 import {themeProps} from '../utils/themeProps';
+import {disabledInteractionProps} from '../utils/disabledInteraction';
 import {useTranslator} from '../i18n';
 
 import {useMergedRefs} from '../hooks/useMergedRefs';
@@ -324,6 +325,8 @@ interface NavItemElementProps {
 /**
  * Renders `<a>` (via LinkComponent) when `href` is set, otherwise `<button>`.
  * Centralizes the link-vs-button decision used across all SideNavItem paths.
+ * A disabled item is a `<button>` that keeps its tab stop and exposes
+ * `aria-disabled`, but is inert (spec:AST-085 FR1, FR2).
  */
 function NavItemElement({
   href,
@@ -351,8 +354,16 @@ function NavItemElement({
       ref={ref as React.Ref<HTMLButtonElement>}
       type="button"
       onClick={onClick}
-      disabled={isDisabled}
-      {...rest}>
+      {...rest}
+      {...(isDisabled
+        ? {
+            'aria-disabled': true,
+            ...disabledInteractionProps(
+              rest.onKeyDown as
+                React.KeyboardEventHandler<HTMLButtonElement> | undefined,
+            ),
+          }
+        : null)}>
       {children}
     </button>
   );
@@ -539,6 +550,10 @@ export function SideNavItem({
   const isRailLeaf = isCollapsed && !hasChildren;
   const railTooltip = useTooltip({
     placement: 'end',
+    // A disabled leaf's row is the trigger (see the collapsed path). It is not
+    // focusable itself, so `auto` would never hear the focus that bubbles up
+    // from its control.
+    focusTrigger: 'always',
     isEnabled: isRailLeaf,
     isOpen: isRailLeaf ? undefined : false,
   });
@@ -702,14 +717,17 @@ export function SideNavItem({
 
     // Items without children: icon-only link or button, its label in a
     // tooltip. The control is the trigger, so the element that takes focus is
-    // the one described. A disabled control takes neither pointer
-    // (`navItemStyles.disabled`) nor focus, so its row is the trigger instead.
+    // the one described. A disabled control takes no pointer
+    // (`navItemStyles.disabled`), so its row listens for the tooltip instead;
+    // the control still takes focus (focusin reaches the row) and stays the
+    // element described (spec:AST-085 FR5).
     const isRowTrigger = isDisabled;
     const collapsedAriaProps = {
       'aria-current': isSelected ? ('page' as const) : undefined,
-      'aria-describedby': isRowTrigger
-        ? rest['aria-describedby']
-        : joinIds(rest['aria-describedby'], railTooltip.describedBy),
+      'aria-describedby': joinIds(
+        rest['aria-describedby'],
+        railTooltip.describedBy,
+      ),
       'aria-disabled': isDisabled || undefined,
       'aria-label': collapsedAccessibleLabel,
       'data-testid': testId,
@@ -732,7 +750,6 @@ export function SideNavItem({
     return (
       <div
         ref={isRowTrigger ? railTooltip.ref : undefined}
-        aria-describedby={isRowTrigger ? railTooltip.describedBy : undefined}
         {...stylex.props(styles.root, xstyle)}>
         {collapsedElement}
         {railTooltip.renderTooltip(label)}

package/src/Skeleton/Skeleton.tsx

@@ -97,7 +97,9 @@ const styles = stylex.create({
   },
   animate: {
     animationDirection: 'alternate',
-    animationDuration: durationVars['--duration-medium-max'],
+    // The loop reads the duration before a theme's tempo scales it
+    // (spec:AST-108 FR4).
+    animationDuration: `var(--_astryx-pre-tempo-duration-medium-max, ${durationVars['--duration-medium-max']})`,
     animationIterationCount: 'infinite',
     // Disable the pulse under reduced-motion; the static placeholder still
     // reads as loading (complex-20).

package/src/Slider/Slider.spec.md

@@ -78,13 +78,14 @@ modes, states, and usage remain documented in `Slider.doc.mjs`.
 
 ## Behavioral and layout contract
 
-| ID  | Candidate invariant                                                                                                                                                                                                                                                                                                                                                                                                                          | Basis                                   | Review state                                       |
-| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | -------------------------------------------------- |
-| FR1 | The current render places a filled range, one or two thumbs, and optional tick marks over the background track.                                                                                                                                                                                                                                                                                                                              | Current source, docs, and focused tests | Verified current behavior; no new behavior decided |
-| FR2 | `Slider`, `Interactive control`, `Track`, and `Thumb` carry the `slider`, `slider-control`, `slider-track`, and `slider-thumb` targets respectively.                                                                                                                                                                                                                                                                                         | Current source, public docs, and DEC-1  | Approved additive target contract                  |
-| FR3 | Filled range, tick marks, mark labels, and adjacent text value display are stable rendered parts without their own current Slider target.                                                                                                                                                                                                                                                                                                    | Current source and public docs          | Verified current asymmetry; not ratified as policy |
-| FR4 | Label and status presentation continue to use Field and FieldStatus; value tooltips continue to use Tooltip.                                                                                                                                                                                                                                                                                                                                 | Current source and focused tests        | Verified composition boundary                      |
-| FR5 | `onChangeEnd` fires once when an interaction ends — a pointer drag or track press is released or cancelled, or a keyboard step (arrow, Page, Home, End) completes — and carries the value the owner renders after its synchronous response to that interaction's `onChange` calls, including any clamp, snap, or rejection; it never carries a value Slider emitted that the owner did not render. A range reports both values the same way. | Maintainer decision (DEC-3)             | Approved                                           |
+| ID  | Candidate invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Basis                                   | Review state                                       |
+| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | -------------------------------------------------- |
+| FR1 | The current render places a filled range, one or two thumbs, and optional tick marks over the background track.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Current source, docs, and focused tests | Verified current behavior; no new behavior decided |
+| FR2 | `Slider`, `Interactive control`, `Track`, and `Thumb` carry the `slider`, `slider-control`, `slider-track`, and `slider-thumb` targets respectively.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Current source, public docs, and DEC-1  | Approved additive target contract                  |
+| FR3 | Filled range, tick marks, mark labels, and adjacent text value display are stable rendered parts without their own current Slider target.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Current source and public docs          | Verified current asymmetry; not ratified as policy |
+| FR4 | Label and status presentation continue to use Field and FieldStatus; value tooltips continue to use Tooltip.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Current source and focused tests        | Verified composition boundary                      |
+| FR5 | `onChangeEnd` fires once when an interaction ends — a pointer drag or track press is released or cancelled, or a keyboard step (arrow, Page, Home, End) completes — and carries the value the owner renders after its synchronous response to that interaction's `onChange` calls, including any clamp, snap, or rejection; it never carries a value Slider emitted that the owner did not render. A range reports both values the same way.                                                                                                                                                                                                                                                                                                                                                                                                             | Maintainer decision (DEC-3)             | Approved                                           |
+| FR6 | When both thumbs of a range share a value, a pointer press takes the thumb that can travel toward the pointer: a press on the track beside them takes the thumb on its side, and a press on the thumbs or on their shared value, such as its mark label, moves neither until the pointer moves, when the direction of that first movement picks the thumb, which takes the drag's focus, pressed state and value tooltip. Until then the upper thumb, drawn over the lower one, holds the press, its focus and its pressed state, so a press that never moves changes no value and leaves focus on the upper thumb. A drag that began on the shared thumbs and comes back past their value moves the other thumb: the dragged thumb stops against it and the other follows the pointer, so with both at 80 a drag to 95 and back to 50 ends at [50, 80]. | Current source and focused tests        | Accepted contract                                  |
 
 ### Observed current target asymmetry
 
@@ -225,15 +226,16 @@ separately listed value tooltip retains Tooltip's target.
 
 ## Verification map
 
-| Contract            | Verification                                                                                                                                                                                                                                                                                                                                                                                                                 | Representative states                                                                       | Mutation or failure expectation                                                                                                                                       | Audit section                |
-| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
-| FR1                 | `Slider.test.tsx` structure, range, and marks suites                                                                                                                                                                                                                                                                                                                                                                         | Single, range, horizontal, vertical, marks                                                  | Removing or misaligning stable parts breaks existing role, position, or mark assertions.                                                                              | `audit:Slider/anatomy`       |
-| AR1                 | Slider accessibility contract (`internal/a11y-spec`, pending) bound to Slider; disabled-thumb Tab stop pending conformance; in jsdom and Chromium; `Slider.test.tsx` keyboard suites, including "follows the mirrored track under RTL: ArrowLeft increases, ArrowRight decreases, Up/Down unchanged" and "keeps ArrowLeft decreasing on a vertical track under RTL"; the Page, Home/End and Up/Down cases under the contract | Single and range; horizontal LTR and RTL; vertical; disabled; formatted value               | A thumb loses its role, name or value properties; an arrow, Page, Home or End key stops stepping or steps against the mirrored track; a range thumb crosses the other | `audit:Slider/accessibility` |
-| FR2                 | `Slider.test.tsx`, `themingTargets.test.ts`, generated probe theme, and Chromium                                                                                                                                                                                                                                                                                                                                             | Root, horizontal/vertical control, disabled control, track, and thumb                       | A target class/state is missing, undocumented, or placed outside its owning anatomy.                                                                                  | `audit:Slider/theming`       |
-| FR3                 | Source and consumer-doc review                                                                                                                                                                                                                                                                                                                                                                                               | Filled range, marks, labels, adjacent text value                                            | A missing target is inaccurately documented as present or intentionally permanent.                                                                                    | `audit:Slider/theming`       |
-| FR4                 | Source inspection; focused tests cover label, status, and disabled-reason Tooltip only                                                                                                                                                                                                                                                                                                                                       | Label, status, value tooltip, disabled reason                                               | Shared composition or its accessible association disappears; value-tooltip composition still lacks focused coverage.                                                  | `audit:Slider/anatomy`       |
-| FR5                 | Pending: `Slider.test.tsx` change-end cases driven by an owner that renders, clamps, or rejects the emitted value (not yet in the suite)                                                                                                                                                                                                                                                                                     | Single and range; pointer release before and after the owner re-renders; each keyboard step | `onChangeEnd` reports a value the owner did not render, fires more than once per interaction, or skips a completed keyboard step                                      | `audit:Slider/accessibility` |
-| Theming anatomy map | `scripts/check-knowledge.mjs`                                                                                                                                                                                                                                                                                                                                                                                                | Canonical anatomy and four current local targets                                            | Missing, extra, prefixed, stale, or unclaimed mappings fail repository validation.                                                                                    | `audit:Slider/theming`       |
+| Contract            | Verification                                                                                                                                                                                                                                                                                                                                                                                                                 | Representative states                                                                                                                                                                                                                                                 | Mutation or failure expectation                                                                                                                                                                                                                | Audit section                |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
+| FR1                 | `Slider.test.tsx` structure, range, and marks suites                                                                                                                                                                                                                                                                                                                                                                         | Single, range, horizontal, vertical, marks                                                                                                                                                                                                                            | Removing or misaligning stable parts breaks existing role, position, or mark assertions.                                                                                                                                                       | `audit:Slider/anatomy`       |
+| AR1                 | Slider accessibility contract (`internal/a11y-spec`, pending) bound to Slider; disabled-thumb Tab stop pending conformance; in jsdom and Chromium; `Slider.test.tsx` keyboard suites, including "follows the mirrored track under RTL: ArrowLeft increases, ArrowRight decreases, Up/Down unchanged" and "keeps ArrowLeft decreasing on a vertical track under RTL"; the Page, Home/End and Up/Down cases under the contract | Single and range; horizontal LTR and RTL; vertical; disabled; formatted value                                                                                                                                                                                         | A thumb loses its role, name or value properties; an arrow, Page, Home or End key stops stepping or steps against the mirrored track; a range thumb crosses the other                                                                          | `audit:Slider/accessibility` |
+| FR2                 | `Slider.test.tsx`, `themingTargets.test.ts`, generated probe theme, and Chromium                                                                                                                                                                                                                                                                                                                                             | Root, horizontal/vertical control, disabled control, track, and thumb                                                                                                                                                                                                 | A target class/state is missing, undocumented, or placed outside its owning anatomy.                                                                                                                                                           | `audit:Slider/theming`       |
+| FR3                 | Source and consumer-doc review                                                                                                                                                                                                                                                                                                                                                                                               | Filled range, marks, labels, adjacent text value                                                                                                                                                                                                                      | A missing target is inaccurately documented as present or intentionally permanent.                                                                                                                                                             | `audit:Slider/theming`       |
+| FR4                 | Source inspection; focused tests cover label, status, and disabled-reason Tooltip only                                                                                                                                                                                                                                                                                                                                       | Label, status, value tooltip, disabled reason                                                                                                                                                                                                                         | Shared composition or its accessible association disappears; value-tooltip composition still lacks focused coverage.                                                                                                                           | `audit:Slider/anatomy`       |
+| FR5                 | Pending: `Slider.test.tsx` change-end cases driven by an owner that renders, clamps, or rejects the emitted value (not yet in the suite)                                                                                                                                                                                                                                                                                     | Single and range; pointer release before and after the owner re-renders; each keyboard step                                                                                                                                                                           | `onChangeEnd` reports a value the owner did not render, fires more than once per interaction, or skips a completed keyboard step                                                                                                               | `audit:Slider/accessibility` |
+| FR6                 | `Slider.test.tsx` coincident range thumbs cases                                                                                                                                                                                                                                                                                                                                                                              | Both thumbs at the minimum, the maximum and mid-range; a track press on each side; a press on the thumbs moved either way; a press that never moves, on the thumbs and on the mark label of their value; a drag that passes back over the shared value; right to left | A press or drag on coincident thumbs moves neither thumb, moves the thumb that cannot travel toward the pointer, keeps its focus, pressed state or tooltip on a thumb the drag has left, or leaves a press that never moves on the lower thumb | `audit:Slider/anatomy`       |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                                                                                                                                                                                                                                                                                                                                                                                | Canonical anatomy and four current local targets                                                                                                                                                                                                                      | Missing, extra, prefixed, stale, or unclaimed mappings fail repository validation.                                                                                                                                                             | `audit:Slider/theming`       |
 
 The focused Slider suite asserts the `slider-control` target's orientation and
 disabled state. Source/metadata guards cover all four target declarations. The