@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/DropdownMenu/modules/useMenuPress.spec.md

@@ -35,15 +35,15 @@ references:
 
 ## Contract at a glance
 
-| Area                    | Contract                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | New public hook `useMenuPress` and the pure `menuPressStep` machine it drives, exported from `@astryxdesign/core/hooks`; the marker `data-astryx-menu-press` on every menu or listbox root that mounts it; PROPOSED in this change: the hook's trigger half (`onTriggerPress`, `triggerProps`, `isTriggerClickFromPress`, `longPressDelayMs`). No consumer prop of DropdownMenu, ContextMenu, DropdownMenuSubMenu or Selector changes.                                                                                                                                                                                |
-| Behavior                | The row under the pointer when it is RELEASED is the row that acts; the highlight follows a held mouse, finger or pen; a mouse released outside closes the menu and a finger leaves it open; the browser's stray click for a tracked gesture never acts; the menu root declares `touch-action` by overflow. PROPOSED (FR8, FR9, DEC-4): a mouse opens a DropdownMenu on press-down and a finger held on its trigger opens it after the long-press delay, with a settle rule on the opening release.                                                                                                                   |
-| End-user impact         | A finger that lands on one menu row and lifts on another acts on the second, once, instead of on the first; a drag inside an open menu picks where it lets go; a mouse that lets go outside dismisses, a finger does not. PROPOSED: a mouse can press the trigger, drag into the menu and let go on a row in one gesture; a finger held on the trigger opens the menu without lifting. Keyboard behavior and sub-menu hover are unchanged.                                                                                                                                                                            |
-| Builder impact          | None for consumers of the five surfaces: they mount the model themselves. A component CAN adopt this model only when it meets the eligibility criteria below, and its component contract MUST explicitly name this module and the governed surfaces before mounting `useMenuPress`. The builder supplies an enabled-row selector and a `touch-action` declaration.                                                                                                                                                                                                                                                    |
-| Compatibility/readiness | Additive public hook; existing consumer props unchanged; shipped keyboard behavior unchanged. Shipped-behavior changes: DEC-3 (current; a mouse released outside a menu dismisses it) and PROPOSED DEC-4 (a mouse opens the menu on press rather than click; a tap is unchanged). jsdom evidence is complete and real-Chromium evidence covers the touch pan, the finger slide and its stray click; iOS WebKit evidence is not required for this module. Authority: current for FR1–FR7, DEC-3, DEC-6, DEC-7 (`cixzhang`, 2026-10-02); FR8, FR9 and DEC-4 are proposed in this change and await the same owner (OQ1). |
-| Review checks           | Reject a row that acts on `pointerdown` or from the browser's click after a tracked release; a second activation reaching a row for one gesture; a highlight that lights two rows; a finger release outside that closes the menu, or a mouse release outside that leaves it open; a menu root without a `touch-action` declaration; a picker whose listbox takes DOM focus for the highlight; an opening release that acts before the pointer entered the menu or the press settled; a trigger whose press and click both toggle in one gesture.                                                                      |
-| Governing rules         | `architecture:interaction-modality` INV2–INV4 (one operable path per modality, hover as enhancement, menus may move focus with the pointer); `architecture:public-component-api` for the new public hook; `architecture:layer-runtime` for the native light dismiss the model leaves in place; `family:overlay-dismissal` for Escape ordering, which this module does not change.                                                                                                                                                                                                                                     |
+| Area                    | Contract                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | New public hook `useMenuPress` and the pure `menuPressStep` machine it drives, exported from `@astryxdesign/core/hooks`; the marker `data-astryx-menu-press` on every menu or listbox root that mounts it; the hook's trigger half (`onTriggerPress`, `triggerProps`, `isTriggerClickFromPress`, `longPressDelayMs`), released in 0.6.6. No consumer prop of DropdownMenu, ContextMenu, DropdownMenuSubMenu or Selector changes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| Behavior                | The row under the pointer when it is RELEASED is the row that acts; the highlight follows a held mouse; a mouse released outside closes the menu; the browser's stray click for a tracked gesture never acts; the menu root declares `touch-action` by overflow. A finger or pen's press follows `spec:AST-094` FR26–FR30 under every primary pointer. PROPOSED (FR8, DEC-4): a mouse opens a DropdownMenu on press-down, with a settle rule on the opening release.                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| End-user impact         | A finger that lands on one menu row and lifts on another acts on the second, once, instead of on the first; a drag inside an open menu picks where it lets go; a mouse that lets go outside dismisses, a finger does not. PROPOSED: a mouse can press the trigger, drag into the menu and let go on a row in one gesture. Opening under a finger is `spec:AST-094` FR29's. Keyboard behavior and sub-menu hover are unchanged.                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| Builder impact          | None for consumers of the five surfaces: they mount the model themselves. A component CAN adopt this model only when it meets the eligibility criteria below, and its component contract MUST explicitly name this module and the governed surfaces before mounting `useMenuPress`. The builder supplies an enabled-row selector and a `touch-action` declaration.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| Compatibility/readiness | Additive public hook; existing consumer props unchanged; shipped keyboard behavior unchanged. Shipped-behavior changes: FR6's mouse row press through the press controller (`spec:AST-094` DEC-21; evidence pending), DEC-3 (current; a mouse released outside a menu dismisses it) and PROPOSED DEC-4 (a mouse opens the menu on press rather than click; under a finger, `spec:AST-094` FR29). jsdom evidence is complete for FR1–FR7, and real-Chromium evidence covers the touch pan, the finger slide and its stray click; FR10's resting finger, FR11's handoff and AR5's single open and close need real-browser evidence; iOS WebKit evidence is not required for this module. Authority: current for FR1–FR7, DEC-3, DEC-6, DEC-7 (`cixzhang`, 2026-10-02) and FR10, FR11, AR5, DEC-8 (`cixzhang`, 2026-10-25); FR8 and DEC-4 are proposed in this change and await the same owner (OQ1). |
+| Review checks           | Reject a row that acts on `pointerdown` or from the browser's click after a tracked release; a second activation reaching a row for one gesture; a highlight that lights two rows; a finger release outside that closes the menu, or a mouse release outside that leaves it open; a menu root without a `touch-action` declaration; a picker whose listbox takes DOM focus for the highlight; an opening release that acts before the pointer entered the menu or the press settled; a trigger whose press and click both toggle in one gesture.                                                                                                                                                                                                                                                                                                                                                   |
+| Governing rules         | `architecture:interaction-modality` INV2–INV4 (one operable path per modality, hover as enhancement, menus may move focus with the pointer); `architecture:public-component-api` for the new public hook; `architecture:layer-runtime` for the native light dismiss the model leaves in place; `family:overlay-dismissal` for Escape ordering, which this module does not change.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 
 This table is a review projection; the body below is authoritative.
 
@@ -60,8 +60,9 @@ carries a separate press controller for an eligible surface.
 
 The module contracts the press model only. Menu anatomy, theming,
 presentation policy, keyboard navigation and item semantics stay with the
-owning component records; trigger opening by keyboard and by a finger's tap
-stays with the component that renders the trigger.
+owning component records; trigger opening by keyboard stays with the component
+that renders the trigger, and opening under a finger follows `spec:AST-094`
+FR29.
 
 ### Adoption eligibility
 
@@ -80,13 +81,18 @@ adopter.
 
 ## Compatibility and migration
 
-- Released default preserved: `no` for one behavior (DEC-3: a mouse released
-  outside a menu now dismisses it); `yes` for every consumer prop and every
-  item, divider, section and presentation API
+- Released default preserved: `no` for two behaviors: DEC-3 (a mouse
+  released outside a menu now dismisses it), and an unset `longPressDelayMs`,
+  whose released 500 ms wait gives way to `spec:AST-094` FR29's timing
+  under a finger;
+  `yes` for every consumer prop and every item, divider, section and
+  presentation API
 - Compatibility class: additive public hook and types; behavior change inside
   the menu family
 - Migration decision: `module:DropdownMenu/useMenuPress/DEC-3`; proposed
-  `module:DropdownMenu/useMenuPress/DEC-4` (pending owner review)
+  `module:DropdownMenu/useMenuPress/DEC-4` (pending owner review);
+  `spec:AST-094` FR25 (a caller that needs the released 500 ms wait passes
+  `longPressDelayMs: 500`)
 
 Consumer migration instructions belong in consumer docs and release notes.
 
@@ -121,8 +127,8 @@ Consumer migration instructions belong in consumer docs and release notes.
   scroll and never listens for `scroll`.
 - Native light dismiss, Escape ordering and focus trapping — owned by
   `architecture:layer-runtime` and `family:overlay-dismissal`.
-- Opening a menu from its trigger by keyboard or by a finger's tap — owned by the
-  component that renders the trigger.
+- Opening a menu from its trigger by keyboard — owned by the component that
+  renders the trigger; under a finger, `spec:AST-094` FR29 governs it.
 - Keyboard navigation, typeahead and Enter/Space activation — owned by
   `useListFocus`, `useTypeahead` and the component records.
 - Hover-to-open of sub-menu flyouts — owned by `useMenuHover`.
@@ -130,32 +136,34 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ## Public API and concepts
 
-| Concept                  | Closed values or states                                        | Meaning                                                                                                                                                                                  | Default                       | Owner                              | Stability |
-| ------------------------ | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | ---------------------------------- | --------- |
-| gesture phase            | `idle`, `tracking`; proposed `triggerPress`, `open`            | where the press in flight stands                                                                                                                                                         | `idle`                        | `module:DropdownMenu/useMenuPress` | stable    |
-| effect                   | `none`, `highlight`, `clear`, `act`, `settle`; proposed `open` | what one event makes the host do; `open` asks the trigger to open the menu under the held pointer; `settle` carries `stray` (swallow the browser's click) and `dismiss` (close the menu) | —                             | `module:DropdownMenu/useMenuPress` | stable    |
-| pointer type             | `mouse`, `touch`, `pen`                                        | the gesture's own pointer; `touch` and `pen` are "a finger"                                                                                                                              | from the event                | `module:DropdownMenu/useMenuPress` | stable    |
-| enabled-row selector     | caller string                                                  | the rows a release may act on; anything else inside the root highlights nothing                                                                                                          | required                      | `module:DropdownMenu/useMenuPress` | stable    |
-| highlight                | DOM focus, or a caller callback                                | one lit row; focus with `preventScroll` in a menu, `aria-activedescendant` in a picker                                                                                                   | focus                         | `module:DropdownMenu/useMenuPress` | stable    |
-| stray-click window       | 400 ms, or the next `pointerdown`                              | how long after a tracked release the browser's click is still swallowed                                                                                                                  | `MENU_PRESS_STRAY_CLICK_MS`   | `module:DropdownMenu/useMenuPress` | stable    |
-| settle time              | 300 ms                                                         | proposed: how long an opening press must last before its release may act                                                                                                                 | `MENU_PRESS_SETTLE_MS`        | `module:DropdownMenu/useMenuPress` | proposed  |
-| long-press delay         | 500 ms                                                         | proposed: how long a finger rests on the trigger before the menu opens under it                                                                                                          | `longPressDelayMs`            | `module:DropdownMenu/useMenuPress` | proposed  |
-| `data-astryx-menu-press` | present or absent                                              | the root carries this model; a host controller of its own stands aside                                                                                                                   | present on every mounted root | `module:DropdownMenu/useMenuPress` | stable    |
-| activation click         | `click` with `detail: 0`, the release's button and modifiers   | how the model acts on a row, marked for the synchronous extent by `isMenuPressActivation()`; `detail === 0` alone therefore no longer means "keyboard" on a menu row                     | —                             | `module:DropdownMenu/useMenuPress` | stable    |
+| Concept                  | Closed values or states                                                                                       | Meaning                                                                                                                                                                                                                   | Default                       | Owner                              | Stability |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | ---------------------------------- | --------- |
+| gesture phase            | `idle`, `tracking`; proposed `triggerPress`, `open`                                                           | where the press in flight stands                                                                                                                                                                                          | `idle`                        | `module:DropdownMenu/useMenuPress` | stable    |
+| effect                   | `none`, `highlight`, `clear`, `act`, `settle`; proposed `open`                                                | what one event makes the host do; `open` asks the trigger to open the menu under the held pointer; `settle` carries `stray` (swallow the browser's click) and `dismiss` (close the menu)                                  | —                             | `module:DropdownMenu/useMenuPress` | stable    |
+| pointer type             | `mouse`, `touch`, `pen`                                                                                       | the gesture's own pointer; `touch` and `pen` are "a finger"                                                                                                                                                               | from the event                | `module:DropdownMenu/useMenuPress` | stable    |
+| enabled-row selector     | caller string                                                                                                 | the rows a release may act on; anything else inside the root highlights nothing                                                                                                                                           | required                      | `module:DropdownMenu/useMenuPress` | stable    |
+| highlight                | DOM focus, or a caller callback                                                                               | one lit row; focus with `preventScroll` in a menu, `aria-activedescendant` in a picker                                                                                                                                    | focus                         | `module:DropdownMenu/useMenuPress` | stable    |
+| stray-click window       | 400 ms, or the next `pointerdown`                                                                             | how long after a tracked release the browser's click is still swallowed                                                                                                                                                   | `MENU_PRESS_STRAY_CLICK_MS`   | `module:DropdownMenu/useMenuPress` | stable    |
+| settle time              | 300 ms                                                                                                        | proposed: how long an opening press must last before its release may act                                                                                                                                                  | `MENU_PRESS_SETTLE_MS`        | `module:DropdownMenu/useMenuPress` | proposed  |
+| long-press delay         | released 500 ms when set; unset, as `spec:AST-094` FR29 states (none in a fixed bar; 150 ms in a scroll view) | how long a held finger waits on a trigger before the menu opens. A caller that sets `longPressDelayMs` gets that wait in a fixed bar and in a scroll view alike, which keeps the released behavior (`spec:AST-094` FR25). | `longPressDelayMs`            | `module:DropdownMenu/useMenuPress` | stable    |
+| `data-astryx-menu-press` | present or absent                                                                                             | the root carries this model; a host controller of its own stands aside                                                                                                                                                    | present on every mounted root | `module:DropdownMenu/useMenuPress` | stable    |
+| activation click         | `click` with `detail: 0`, the release's button and modifiers                                                  | how the model acts on a row, marked for the synchronous extent by `isMenuPressActivation()`; `detail === 0` alone therefore no longer means "keyboard" on a menu row                                                      | —                             | `module:DropdownMenu/useMenuPress` | stable    |
 
 ## Behavioral contract
 
-| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Basis                                                                                                                                                                           | Verification state             |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
-| FR1 | A row MUST act when a press is released over it, never because the press began on it. A press that never left its row is a tap and acts on that row.                                                                                                                                                                                                                                                                                                                      | macOS and iOS menu behavior; `menuPressGesture.test.ts`, `useMenuPress.test.tsx`                                                                                                | verify                         |
-| FR2 | While a press is held inside a menu, the highlighted row MUST be the enabled row under the pointer, and nothing MUST be highlighted over a divider, a heading, a disabled row, or outside the menu. A mouse moving with no button down moves the highlight the same way (existing hover-to-focus).                                                                                                                                                                        | `architecture:interaction-modality` allowed variation for menus; `useMenuPress.test.tsx`                                                                                        | verify                         |
-| FR3 | A press that began inside a menu and is released outside it MUST act on nothing. Under a mouse the menu MUST then close; under a finger or pen it MUST stay open.                                                                                                                                                                                                                                                                                                         | DEC-3; `useMenuPress.test.tsx`, `DropdownMenu.test.tsx`, `Selector.test.tsx`                                                                                                    | verify                         |
-| FR4 | A menu whose rows fit MUST declare `touch-action: pinch-zoom`; one that scrolls MUST declare `touch-action: pan-y pinch-zoom` and `overscroll-behavior: contain`. Neither admits a one-finger pan the menu does not scroll, and both leave a two-finger pinch to the browser, so the page stays zoomable over an open menu. The model MUST treat `pointercancel` and a second pointer as the end of the gesture with nothing acting, and MUST NOT re-implement scrolling. | Browser scroll ownership; WCAG 2.2 SC 1.4.4 under `spec:AST-020` FR1; `DropdownMenu.test.tsx` touch-action case, `useMenuPress.test.tsx`, `MenuPinchZoom.a11y.chromium.spec.ts` | verify                         |
-| FR5 | The click the browser reports for a gesture this model tracked MUST NOT act on any row; only the release acts. A click with no tracked gesture behind it, or one whose `detail` is 0, MUST act on its target as before. The swallower arms at a tracked release and disarms at the next `pointerdown` or after the stray-click window.                                                                                                                                    | One gesture, one activation; `useMenuPress.test.tsx` FR5 suite                                                                                                                  | verify                         |
-| FR6 | At most one row of a menu is lit. Under a finger the row a press began on MUST NOT keep a pressed or hovered look once the pointer left it, so menu rows paint `:active` only under `(hover: hover)`.                                                                                                                                                                                                                                                                     | `DropdownMenuItem.tsx` styles                                                                                                                                                   | verify                         |
-| FR7 | While a press is tracked in a menu that scrolls, a pointer resting within the edge zone of the menu's top or bottom MUST scroll the menu toward that edge and re-read the row under the pointer as the rows move.                                                                                                                                                                                                                                                         | `useMenuPress.test.tsx` autoscroll case                                                                                                                                         | verify                         |
-| FR8 | On a mouse a DropdownMenu trigger MUST open its menu on press-down (button 0, no Control), and a drag from the trigger into the menu that releases over an enabled row MUST act on it. The opening gesture's release MUST act only if the pointer entered the menu or the press lasted the settle time; otherwise nothing acts and the menu stays open. Pressing the trigger of an open menu MUST close it and MUST NOT reopen it in the same gesture.                    | Proposed DEC-4; `DropdownMenu.test.tsx` press model suite, `menuPressGesture.test.ts` trigger states                                                                            | proposed; pending owner review |
-| FR9 | Under a finger a tap on the trigger MUST open the menu through its click. A press held on the trigger for the long-press delay MUST open the menu with the finger down, prevent the default of the finger's later `touchmove`s until the gesture ends, and continue under FR1–FR4 with the same settle rule.                                                                                                                                                              | Proposed DEC-4; `DropdownMenu.test.tsx` held-touch case, `useMenuPress.test.tsx`                                                                                                | proposed; pending owner review |
+| ID   | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Basis                                                                                                                                                                           | Verification state             |
+| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
+| FR1  | A row MUST act when a press is released over it, never because the press began on it; a press that never left its row is a tap or click on that row. A finger or pen follows `spec:AST-094` FR26 instead, under every primary pointer (`spec:AST-094` FR43); a mouse keeps this rule.                                                                                                                                                                                                                                                      | macOS and iOS menu behavior; `menuPressGesture.test.ts`, `useMenuPress.test.tsx`                                                                                                | verify                         |
+| FR2  | While a press is held inside a menu, the highlighted row MUST be the enabled row under the pointer, and nothing MUST be highlighted over a divider, a heading, a disabled row, or outside the menu. A mouse moving with no button down moves the highlight the same way (existing hover-to-focus). A finger or pen follows `spec:AST-094` FR27 and FR11's cell profile instead, under every primary pointer, and a second finger ends the gesture (FR4); a mouse keeps this rule.                                                          | `architecture:interaction-modality` allowed variation for menus; `useMenuPress.test.tsx`                                                                                        | verify                         |
+| FR3  | A press that began inside a menu and is released outside it MUST act on nothing. Under a mouse the menu MUST then close; under a finger or pen it MUST stay open (`spec:AST-094` FR28).                                                                                                                                                                                                                                                                                                                                                    | DEC-3; `useMenuPress.test.tsx`, `DropdownMenu.test.tsx`, `Selector.test.tsx`                                                                                                    | verify                         |
+| FR4  | A menu whose rows fit MUST declare `touch-action: pinch-zoom`; one that scrolls MUST declare `touch-action: pan-y pinch-zoom` and `overscroll-behavior: contain`. Neither admits a one-finger pan the menu does not scroll, and both leave a two-finger pinch to the browser, so the page stays zoomable over an open menu. The model MUST treat `pointercancel` and a second pointer as the end of the gesture with nothing acting, and MUST NOT re-implement scrolling.                                                                  | Browser scroll ownership; WCAG 2.2 SC 1.4.4 under `spec:AST-020` FR1; `DropdownMenu.test.tsx` touch-action case, `useMenuPress.test.tsx`, `MenuPinchZoom.a11y.chromium.spec.ts` | verify                         |
+| FR5  | The click the browser reports for a gesture this model tracked MUST NOT act on any row; only the release acts. A click with no tracked gesture behind it, or one whose `detail` is 0, MUST act on its target as before. The swallower arms at a tracked release and disarms at the next `pointerdown` or after the stray-click window.                                                                                                                                                                                                     | One gesture, one activation; `useMenuPress.test.tsx` FR5 suite                                                                                                                  | verify                         |
+| FR6  | At most one row of a menu is lit. Under a finger the row a press began on MUST NOT keep a pressed or hovered look once the pointer left it. A finger or pen follows `spec:AST-094` FR27 and FR11 instead, under every primary pointer; under a mouse a row paints its press at once through the press controller (`spec:AST-094` FR11's fine-pointer profile, DEC-21).                                                                                                                                                                     | `DropdownMenuItem.tsx` styles; `spec:AST-094` DEC-21 for the mouse row press (not implemented: a mouse row still paints `:active`)                                              | verify                         |
+| FR7  | While a press is tracked in a menu that scrolls, a pointer resting within the edge zone of the menu's top or bottom MUST scroll the menu toward that edge and re-read the row under the pointer as the rows move. A finger or pen follows `spec:AST-094` FR30 instead, under every primary pointer; a mouse keeps this rule.                                                                                                                                                                                                               | `useMenuPress.test.tsx` autoscroll case                                                                                                                                         | verify                         |
+| FR8  | On a mouse a DropdownMenu trigger MUST open its menu on press-down (button 0, no Control), and a drag from the trigger into the menu that releases over an enabled row MUST act on it. The opening gesture's release MUST act only if the pointer entered the menu or the press lasted the settle time; otherwise nothing acts and the menu stays open. Pressing the trigger of an open menu MUST close it and MUST NOT reopen it in the same gesture. A mouse pointer handed to the menu as it opens (FR11) follows the same settle rule. | Proposed DEC-4; `DropdownMenu.test.tsx` press model suite, `menuPressGesture.test.ts` trigger states                                                                            | proposed; pending owner review |
+| FR9  | Opening a menu from its trigger under a finger and the opening finger's handoff are governed by `spec:AST-094` FR29, under every primary pointer (`spec:AST-094` FR43).                                                                                                                                                                                                                                                                                                                                                                    | `spec:AST-094` FR29                                                                                                                                                             | as `spec:AST-094` states       |
+| FR10 | A finger released on a sub-menu's row MUST open that sub-menu, as the row's own click would (the lift acts, `spec:AST-094` FR26; on a compact touch screen an `adaptive` row drills in, FR34); a finger resting on the row MUST NOT open it. A finger that slides from a row onto the rows of an open flyout picks there under ORD1.                                                                                                                                                                                                       | DEC-8; `DropdownMenuSubMenu.test.tsx` press cases                                                                                                                               | verify                         |
+| FR11 | A pointer that went down elsewhere, such as a context menu's long press, and is handed to the menu as it opens MUST be the opening press. Under every primary pointer, a finger picks only after the handoff distance, counted from the first position the menu sees after it opened as `spec:AST-094` FR33 counts it, and its lift before that acts on nothing and leaves the menu open.                                                                                                                                                  | DEC-8; `useMenuPress.test.tsx` continuation suite                                                                                                                               | verify                         |
 
 ### Transformation and precedence order
 
@@ -211,12 +219,17 @@ Consumer migration instructions belong in consumer docs and release notes.
 - **AR4 — Focus after a pick is the component's.** The model activates the
   row as its own click would; where focus goes once the menu closes stays
   with the owning component record and is unchanged by this module.
+- **AR5 — One open, one close.** A finger opens a menu once, through
+  `spec:AST-094` FR29's opening, a context menu's long press (`spec:AST-094`
+  FR33), FR9's held press, or a tap's click, and nothing withdraws
+  an open: a screen reader hears the menu open once, and close once at a
+  pick, a dismissal or Escape (DEC-8).
 
 ## Design relationships
 
-No visual representation is introduced. FR6 removes the coarse-pointer
-pressed paint from menu rows so the single focus highlight is the only lit
-row under a finger; the highlight paint itself is the existing focus overlay
+No visual representation is introduced. FR6 keeps a finger's row press on
+`spec:AST-094` FR11's cell profile so the single focus highlight is the only
+lit row under a finger; the highlight paint itself is the existing focus overlay
 owned by the item components.
 
 ## Parent and system relationships
@@ -237,16 +250,17 @@ owned by the item components.
 
 ## Verification map
 
-| Contract               | Verification                                                                                                               | Representative states                                                                                                                                    | Mutation or failure expectation                                                                                                 |
-| ---------------------- | -------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| FR1–FR3, FR5           | `menuPressGesture.test.ts` (one case per transition of the diagram)                                                        | idle, tracking; mouse and touch; releases over a row, over chrome, on the trigger, outside; cancel                                                       | Acting on the press row, on the stray click, or dismissing under a finger fails a transition case                               |
-| FR1–FR5, FR7, AR1, AR3 | `useMenuPress.test.tsx` with an injected hit test                                                                          | release over another row, tap, stray click, `detail: 0`, mouse/finger outside, pointercancel, second pointer, autoscroll                                 | A second activation, a swallowed assistive click, a wrong dismissal, or a dead autoscroll fails                                 |
-| FR1, FR3–FR5           | `DropdownMenu.test.tsx`, `DropdownMenuSubMenu.test.tsx`, `ContextMenu.test.tsx` press suites                               | finger slide across rows, outside release by mouse and finger, `touch-action`, flyout release, root marker                                               | Each removed behavior fails its named case                                                                                      |
-| FR1, FR3, AR2          | `Selector.test.tsx` press model suite                                                                                      | finger release over another option, finger/mouse release outside, listbox marker                                                                         | A listbox that takes focus, acts on the press option, or closes under a finger fails                                            |
-| FR4 (scroll)           | `MenuPress.a11y.chromium.spec.ts` (real Chromium)                                                                          | Chromium touch pan in an overflowing menu; touch-action by overflow; finger slide and its stray click                                                    | Not provable in jsdom; a pan that acts on a row, or a slide that acts on the press row, fails                                   |
-| FR4 (pinch)            | `MenuPinchZoom.a11y.chromium.spec.ts` (real Chromium, phone emulation)                                                     | two-finger pinch over a menu whose rows fit, over one that scrolls, and over a picker listbox                                                            | Not provable in jsdom; a pinch that leaves the page at scale 1, or acts on a row, fails                                         |
-| FR8, FR9 (proposed)    | `menuPressGesture.test.ts` trigger states; `useMenuPress.test.tsx` trigger suite; `DropdownMenu.test.tsx` press-open cases | mouse opens at once, finger tap, held finger, settle before/after, cancel; press-open + drag-release, unsettled release, trigger toggle, held touch, tap | A menu that does not open on a mouse press, an unsettled release that acts, or a trigger that reopens in the same gesture fails |
-| ORD1a (proposed)       | `DropdownMenuSubMenu.test.tsx` press cases; `SubMenuHeaderFooter.a11y.chromium.spec.ts` press-drag case                    | a mouse press on a menu row released on a row of a sub-menu rendered beside the menu; the same press released on that sub-menu's header field            | A release on such a row that acts on nothing or closes the menu, or a release on its header field that acts, fails.             |
+| Contract               | Verification                                                                                                                                                                                                    | Representative states                                                                                                                                                               | Mutation or failure expectation                                                                                                                     |
+| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| FR1–FR3, FR5           | `menuPressGesture.test.ts` (one case per transition of the diagram)                                                                                                                                             | idle, tracking; mouse and touch; releases over a row, over chrome, on the trigger, outside; cancel                                                                                  | Acting on the press row, on the stray click, or dismissing under a finger fails a transition case                                                   |
+| FR1–FR5, FR7, AR1, AR3 | `useMenuPress.test.tsx` with an injected hit test                                                                                                                                                               | release over another row, tap, stray click, `detail: 0`, mouse/finger outside, pointercancel, second pointer, autoscroll                                                            | A second activation, a swallowed assistive click, a wrong dismissal, or a dead autoscroll fails                                                     |
+| FR1, FR3–FR5           | `DropdownMenu.test.tsx`, `DropdownMenuSubMenu.test.tsx`, `ContextMenu.test.tsx` press suites                                                                                                                    | finger slide across rows, outside release by mouse and finger, `touch-action`, flyout release, root marker                                                                          | Each removed behavior fails its named case                                                                                                          |
+| FR1, FR3, AR2          | `Selector.test.tsx` press model suite                                                                                                                                                                           | finger release over another option, finger/mouse release outside, listbox marker                                                                                                    | A listbox that takes focus, acts on the press option, or closes under a finger fails                                                                |
+| FR4 (scroll)           | `MenuPress.a11y.chromium.spec.ts` (real Chromium)                                                                                                                                                               | Chromium touch pan in an overflowing menu; touch-action by overflow; finger slide and its stray click                                                                               | Not provable in jsdom; a pan that acts on a row, or a slide that acts on the press row, fails                                                       |
+| FR4 (pinch)            | `MenuPinchZoom.a11y.chromium.spec.ts` (real Chromium, phone emulation)                                                                                                                                          | two-finger pinch over a menu whose rows fit, over one that scrolls, and over a picker listbox                                                                                       | Not provable in jsdom; a pinch that leaves the page at scale 1, or acts on a row, fails                                                             |
+| FR8 (proposed), FR9    | `menuPressGesture.test.ts` trigger states; `useMenuPress.test.tsx` trigger suite; `DropdownMenu.test.tsx` press-open cases                                                                                      | mouse opens at once, settle before/after, cancel; finger opening per `spec:AST-094` FR29; press-open + drag-release, unsettled release, trigger toggle, held touch, tap             | A menu that does not open on a mouse press, an unsettled release that acts, or a trigger that reopens in the same gesture fails                     |
+| FR10, FR11, AR5        | `DropdownMenuSubMenu.test.tsx` press cases and a real-browser finger case for the resting row; `useMenuPress.test.tsx` continuation suite plus a real-browser handoff case; open and close event counts for AR5 | a finger released on and resting on a sub-menu row; a continued finger, the distance from the first sample, a lift before it, a mouse; the menu's open and close each observed once | A sub-menu that opens on a resting finger, a continued finger that picks before the handoff, or an open withdrawn, or opened or closed twice, fails |
+| ORD1a (proposed)       | `DropdownMenuSubMenu.test.tsx` press cases; `SubMenuHeaderFooter.a11y.chromium.spec.ts` press-drag case                                                                                                         | a mouse press on a menu row released on a row of a sub-menu rendered beside the menu; the same press released on that sub-menu's header field                                       | A release on such a row that acts on nothing or closes the menu, or a release on its header field that acts, fails.                                 |
 
 ## Decision log
 
@@ -261,14 +275,13 @@ outside dismisses. Each pointer keeps its platform's answer. Closing for both
 would make a finger that slid off need a second gesture to reopen; staying
 open for both would surprise a mouse user.
 
-### DEC-4 (proposed) — A mouse opens on press-down, a finger on a tap, with a settle rule
+### DEC-4 (proposed) — A mouse opens on press-down, with a settle rule
 
 **Reference:** `module:DropdownMenu/useMenuPress/DEC-4`
 **Decider:** proposed by `vjeux`, `2026-09-27`; pending owner review
 
-Press-to-open with drag-release is the macOS menu. A finger opens on a tap
-because a page under a finger must stay scrollable; a held press opens with
-the finger down so the fast path exists too. The release of the opening
+Press-to-open with drag-release is the macOS menu. Opening under a finger
+follows `spec:AST-094` FR29 and DEC-4. The release of the opening
 gesture acts only after the pointer has entered the menu or the press has
 settled (300 ms), as a native pop-up button's does; otherwise a menu that
 opens under the pointer would pick a row nobody chose.
@@ -281,8 +294,8 @@ opens under the pointer would pick a row nobody chose.
 Menus already keep one highlight by moving focus on hover; the finger moves
 the same focus with `preventScroll`, so keyboard, mouse and touch share one
 state and one paint. A picker's list belongs to a combobox and must not take
-focus from it. The coarse-pointer pressed paint on menu rows is dropped
-because it would light a second row (FR6). This record does not decide where
+focus from it. A row a finger left keeps no pressed paint, because it
+would light a second row (FR6). This record does not decide where
 focus goes after a pick.
 
 ### DEC-7 — Eligibility permits adoption; component contracts opt in
@@ -298,12 +311,27 @@ not eligible. Eligibility never causes adoption: each component contract names
 this module and the surfaces and claims it governs. The public hook's
 availability alone does not make a component an adopter.
 
+### DEC-8 — A finger opens a sub-menu by lifting, and a handed-off finger is the opening press
+
+**Reference:** `module:DropdownMenu/useMenuPress/DEC-8`
+**Decider:** `cixzhang`, `2026-10-25`
+
+A finger that lifts on a sub-menu's row opens it, as a tap would, and a finger
+resting on the row never opens it, so a sub-menu does not open from under a
+finger that is still choosing. A finger handed to a menu as it opens, such as
+the long press that opened a context menu, is that menu's opening press: it picks once it has travelled the handoff
+distance, so the press that opened the
+menu never picks by itself. A finger opens a menu once, and nothing withdraws
+the open, so a screen reader hears one open and one close.
+
+Rejected: opening a sub-menu when a finger rests on its row.
+
 ## Open questions
 
 - **OQ1 — Is press-to-open the menu family's trigger model?** (`human-design`)
-  The one owner decision this change needs: proposed FR8, FR9 and DEC-4 — a
-  mouse opens a DropdownMenu on press-down with the settle rule, a finger on
-  a tap or a held press. Until the owner rules, the current record's FR1–FR7
+  The one owner decision this change needs: proposed FR8 and DEC-4 — a
+  mouse opens a DropdownMenu on press-down with the settle rule. Opening under
+  a finger is `spec:AST-094` FR29's. Until the owner rules, the current record's FR1–FR7
   stand on their own.
 
 The former browser-evidence question is resolved: the touch pan, the finger

package/src/DropdownMenu/useMenuDrillIn.tsx

@@ -23,20 +23,21 @@
 import {useCallback, useMemo, useState, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import type {DropdownMenuDrillIn} from './DropdownMenuContext';
-import {COMPACT_TOUCH_PRESENTATION_QUERY} from '../hooks/useAdaptivePresentation';
+import {useCompactDefinition} from '../utils/touchPresentation';
 
 /**
- * The same query the root presentation uses to decide the bottom sheet, so
+ * The same compact-touch condition the root presentation uses to decide the
+ * bottom sheet (the active theme's, spec:AST-012 FR9), so
  * one component carries one meaning of "adaptive". A bare `(pointer: coarse)`
  * would disagree with it on a large touch tablet: the menu would stay an
  * anchored popover while its sub-menus replaced rows in place, a combination
  * nobody designed.
  */
-function matchesCompactTouch(): boolean {
+function matchesCompactTouch(query: string): boolean {
   return (
     typeof window !== 'undefined' &&
     typeof window.matchMedia === 'function' &&
-    window.matchMedia(COMPACT_TOUCH_PRESENTATION_QUERY).matches
+    window.matchMedia(query).matches
   );
 }
 
@@ -70,6 +71,7 @@ export interface UseMenuDrillInReturn {
  *   opens and the stack empties when it closes.
  */
 export function useMenuDrillIn(isOpen: boolean): UseMenuDrillInReturn {
+  const compactTouchQuery = useCompactDefinition().coarsePointerQuery;
   const [isCompactTouch, setIsCompactTouch] = useState(false);
   const [viewStack, setViewStack] = useState<ReadonlyArray<string>>([]);
   const [host, setHost] = useState<HTMLElement | null>(null);
@@ -81,7 +83,7 @@ export function useMenuDrillIn(isOpen: boolean): UseMenuDrillInReturn {
   if (wasOpen !== isOpen) {
     setWasOpen(isOpen);
     if (isOpen) {
-      setIsCompactTouch(matchesCompactTouch());
+      setIsCompactTouch(matchesCompactTouch(compactTouchQuery));
     } else if (viewStack.length > 0) {
       setViewStack([]);
     }

package/src/EmptyState/EmptyState.announce.test.tsx

@@ -0,0 +1,227 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file EmptyState.announce.test.tsx
+ * @input A fresh EmptyState module with the document's load held back
+ * @output spec:AST-086 FR11/FR12 tests for EmptyState's announcement
+ * @position Component test for EmptyState's announcement
+ */
+
+import {act, StrictMode, useState} from 'react';
+import {afterEach, describe, expect, it, vi} from 'vitest';
+import {createRoot, hydrateRoot} from 'react-dom/client';
+import {createPortal} from 'react-dom';
+import {renderToString} from 'react-dom/server';
+import {renderedText} from '../hooks/useAnnounceRenderedText';
+
+// The document is "loading" until `paint()`; a render before it is part of the
+// page load, one after it is inserted later (spec:AST-086 FR11).
+async function importEmptyState() {
+  let readyState: DocumentReadyState = 'loading';
+  vi.spyOn(document, 'readyState', 'get').mockImplementation(() => readyState);
+  const {EmptyState} = await import('./EmptyState');
+  return {EmptyState, paint: () => (readyState = 'complete')};
+}
+
+const nextFrame = async () =>
+  new Promise<void>(resolve => requestAnimationFrame(() => resolve()));
+const settle = async () => {
+  await act(nextFrame);
+  await act(nextFrame);
+};
+
+const POLITE = '[data-astryx-live-region="polite"]';
+
+/** Every write to the shared polite region, one entry per write. */
+function recordPolite() {
+  const spoken: string[] = [];
+  const observer = new MutationObserver(records => {
+    for (const {target, addedNodes} of records) {
+      const text = addedNodes.length ? target.textContent?.trim() : '';
+      if (text && (target as Element).matches?.(POLITE)) {
+        spoken.push(text);
+      }
+    }
+  });
+  observer.observe(document.body, {subtree: true, childList: true});
+  return {spoken, stop: () => observer.disconnect()};
+}
+
+const mount = () =>
+  createRoot(document.body.appendChild(document.createElement('div')));
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  document.body.replaceChildren();
+});
+
+describe('EmptyState announcement (spec:AST-086 FR2)', () => {
+  it('announces nothing when it renders with the page', async () => {
+    const {EmptyState, paint} = await importEmptyState();
+    const polite = recordPolite();
+    const root = mount();
+    await act(async () => {
+      root.render(<EmptyState title="No projects" description="Create one." />);
+    });
+    paint();
+    await settle();
+    polite.stop();
+    expect(polite.spoken).toEqual([]);
+    await act(async () => root.unmount());
+  });
+
+  it('announces its message once when it appears later', async () => {
+    const {EmptyState, paint} = await importEmptyState();
+    paint();
+    let showEmpty!: () => void;
+    function Results() {
+      const [isEmpty, setIsEmpty] = useState(false);
+      showEmpty = () => setIsEmpty(true);
+      return isEmpty ? (
+        <EmptyState
+          icon={<span>icon</span>}
+          title="No results"
+          description="Try another search."
+          actions={<button type="button">Clear filters</button>}
+        />
+      ) : (
+        <p>Searching</p>
+      );
+    }
+    const polite = recordPolite();
+    const root = mount();
+    await act(async () => {
+      root.render(
+        <StrictMode>
+          <Results />
+        </StrictMode>,
+      );
+    });
+    await act(async () => showEmpty());
+    await settle();
+    polite.stop();
+    expect(polite.spoken).toEqual(['No results Try another search.']);
+    await act(async () => root.unmount());
+  });
+
+  it('announces when it appears later in a same-origin iframe it is portaled into', async () => {
+    const {EmptyState, paint} = await importEmptyState();
+    paint();
+    const frame = document.body.appendChild(document.createElement('iframe'));
+    const frameBody = frame.contentDocument!.body;
+    let showEmpty!: () => void;
+    function Results() {
+      const [isEmpty, setIsEmpty] = useState(false);
+      showEmpty = () => setIsEmpty(true);
+      return isEmpty
+        ? createPortal(
+            <EmptyState title="No results" description="Try another search." />,
+            frameBody,
+          )
+        : null;
+    }
+    const polite = recordPolite();
+    const root = mount();
+    await act(async () => root.render(<Results />));
+    await act(async () => showEmpty());
+    await settle();
+    polite.stop();
+    expect(polite.spoken).toEqual(['No results Try another search.']);
+    await act(async () => root.unmount());
+  });
+
+  it('leaves an empty state inside a live container to that container (spec:AST-086 FR4)', async () => {
+    const {EmptyState, paint} = await importEmptyState();
+    paint();
+    let showEmpty!: () => void;
+    function Log() {
+      const [isEmpty, setIsEmpty] = useState(false);
+      showEmpty = () => setIsEmpty(true);
+      return (
+        <div role="log" aria-live="polite">
+          {isEmpty ? <EmptyState title="No messages yet" /> : null}
+        </div>
+      );
+    }
+    const polite = recordPolite();
+    const root = mount();
+    await act(async () => root.render(<Log />));
+    await act(async () => showEmpty());
+    await settle();
+    polite.stop();
+    expect(polite.spoken).toEqual([]);
+    await act(async () => root.unmount());
+  });
+
+  it('announces once when the message changes after the page loaded, not while it loads', async () => {
+    const {EmptyState, paint} = await importEmptyState();
+    let setTitle!: (title: string) => void;
+    function Search() {
+      const [title, set] = useState('No saved searches');
+      setTitle = set;
+      return <EmptyState title={title} />;
+    }
+    const polite = recordPolite();
+    const root = mount();
+    await act(async () => root.render(<Search />));
+    await act(async () => setTitle('No matches yet'));
+    paint();
+    await act(async () => setTitle('No results'));
+    await settle();
+    polite.stop();
+    expect(polite.spoken).toEqual(['No results']);
+    await act(async () => root.unmount());
+  });
+
+  it('announces nothing from a server render or its hydration (FR12)', async () => {
+    const {EmptyState, paint} = await importEmptyState();
+    const tree = <EmptyState title="No projects" />;
+    const container = document.createElement('div');
+    container.innerHTML = renderToString(tree);
+    document.body.appendChild(container);
+    paint();
+    const polite = recordPolite();
+    const root = await act(async () => hydrateRoot(container, tree));
+    await settle();
+    polite.stop();
+    expect(polite.spoken).toEqual([]);
+    await act(async () => root.unmount());
+  });
+
+  it('reads blocks apart and leaves hidden text out of the message', () => {
+    const element = document.createElement('div');
+    element.innerHTML = '<p>Try again.</p><p>Later.</p><b hidden>No</b>';
+    expect(renderedText(element)).toBe('Try again. Later.');
+  });
+
+  it('stays silent while hidden (attribute or CSS) or revealed during load; announces once when shown later (FR12)', async () => {
+    const {EmptyState, paint} = await importEmptyState();
+    // jsdom has no checkVisibility; this one honors an inline display: none.
+    HTMLElement.prototype.checkVisibility = function (this: HTMLElement) {
+      return this.closest('[style*="none"]') == null;
+    };
+    const polite = recordPolite();
+    const root = mount();
+    const show = async (hidden: boolean, display?: string) =>
+      act(async () =>
+        root.render(
+          <div style={{display}}>
+            <EmptyState title="No results" hidden={hidden} />
+          </div>,
+        ),
+      );
+    await show(true);
+    await show(false);
+    paint();
+    await show(true);
+    await show(false, 'none');
+    await act(nextFrame);
+    expect(polite.spoken).toEqual([]);
+    await show(false);
+    await settle();
+    polite.stop();
+    expect(polite.spoken).toEqual(['No results']);
+    delete (HTMLElement.prototype as Partial<HTMLElement>).checkVisibility;
+    await act(async () => root.unmount());
+  });
+});

package/src/EmptyState/EmptyState.doc.mjs

@@ -81,7 +81,7 @@ export const docs = {
       { guidance: false, description: 'Use an EmptyState for error messages that require immediate action; use a Banner instead.' },
     ],
     anatomy: [
-      {name: 'Container', required: true, description: 'The centered status region that owns spacing, reading order, and the compact layout variant.'},
+      {name: 'Container', required: true, description: 'The centered root that owns spacing, reading order, and the compact layout variant.'},
       {name: 'Icon', required: false, description: 'A visual cue above the title that reinforces the context, like a search icon for no results.'},
       {name: 'Title', required: true, description: 'Primary message explaining what is empty: "No projects yet" not "No data".'},
       {name: 'Description', required: false, description: 'Additional context explaining why it is empty or what the user can do.'},