@astryxdesign/core 0.7.5 → 0.7.6-canary.0135af4

package/src/DropdownMenu/DropdownMenuRadioItem.spec.md

@@ -3,11 +3,11 @@ schema_version: 3
 template_version: 7
 kind: component
 id: component:DropdownMenuRadioItem
-authority: draft
+authority: current
 archive_reason: null
 superseded_by: null
-approved_by: null
-approved_at: null
+approved_by: cixzhang
+approved_at: 2026-10-31
 owners: [cixzhang]
 review_triggers: [public-api, behavior, accessibility, theming, testing]
 verified_by:
@@ -16,7 +16,6 @@ verified_by:
     packages/core/src/DropdownMenu/__tests__/Menu.a11y.test.tsx,
     packages/core/src/RadioList/__tests__/RadioGroup.a11y.test.tsx,
     packages/core/src/DropdownMenu/__tests__/DropdownMenuRadioItemAudit.a11y.chromium.spec.ts,
-    apps/storybook/stories/DropdownMenuRadioItem.stories.tsx,
     apps/storybook/rtl-audit/verified-not-applicable.json,
     scripts/check-knowledge.mjs,
   ]
@@ -31,22 +30,22 @@ architecture:
     architecture:interaction-modality,
   ]
 contributing: []
-system_specs: [spec:AST-020, spec:AST-029]
+system_specs: [spec:AST-020]
 ---
 
 # DropdownMenuRadioItem component contract
 
 ## Contract at a glance
 
-| Area                    | Contract                                                                                                                                                                                     |
-| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | One `menuitemradio` row inside a DropdownMenuRadioGroup with a required value and label, optional description, icon, end content, disabled state, root inputs, and an explicit React 19 ref. |
-| Behavior                | Enabled activation emits the row value through the group, applies the group close policy, then runs the caller click handler; disabled activation does none of these.                        |
-| End-user impact         | Assistive technology hears one radio option with its checked state; pointer and keyboard selection commit the same value, and a disabled option cannot be chosen.                            |
-| Builder impact          | Place the row inside a DropdownMenuRadioGroup and give it a unique value and a label; caller handlers run alongside the row's own behavior.                                                  |
-| Compatibility/readiness | Released subcomponent; observational draft of current behavior. Authority stays `draft` until owner approval.                                                                                |
-| Review checks           | Reject a nested semantic radio, a second keyboard owner, local selection state, a dropped caller input, or disabled activation that selects, closes, or calls the caller click handler.      |
-| Governing rules         | WAI-ARIA menu pattern; `architecture:public-component-api/INV5–INV8`; `architecture:component-theming-surface/INV4–INV6`; `spec:AST-020/FR1,FR2`.                                            |
+| Area                    | Contract                                                                                                                                                                                |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | One `menuitemradio` row inside a DropdownMenuRadioGroup with a required value and label, optional description, icon, end content, disabled state, root inputs, and a ref.               |
+| Behavior                | Enabled activation emits the row value through the group, applies the group close policy, then runs the caller click handler; disabled activation does none of these.                   |
+| End-user impact         | Assistive technology hears one radio option with its checked state; pointer and keyboard selection commit the same value, and a disabled option cannot be chosen.                       |
+| Builder impact          | Place the row inside a DropdownMenuRadioGroup and give it a unique value and a label; caller handlers run alongside the row's own behavior.                                             |
+| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change.                                                                                                                               |
+| Review checks           | Reject a nested semantic radio, a second keyboard owner, local selection state, a dropped caller input, or disabled activation that selects, closes, or calls the caller click handler. |
+| Governing rules         | `spec:AST-020` FR15; `architecture:public-component-api/INV5–INV8`; `architecture:component-theming-surface/INV4–INV6`; `spec:AST-020/FR1,FR2`.                                         |
 
 This table is a review projection; the body below is authoritative.
 
@@ -62,8 +61,8 @@ activation, and the menu lifecycle.
 ## Compatibility and migration
 
 - Released default preserved: yes (`isDisabled=false`).
-- Compatibility class: no public API change; caller `onClick` and
-  `onPointerMove` compose with the row's own behavior.
+- Compatibility class: records shipped behavior; no public prop, default,
+  export, or DOM change.
 - Controlled behavior: the checked state always derives from the group `value`;
   the row holds no selection state.
 - Migration decision: none.
@@ -106,19 +105,16 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ## Behavioral and layout contract
 
-Draft requirements identify their basis so observed code is not mistaken for an
-intentional decision.
-
-| ID  | Candidate invariant                                                                                                                                                                                                                                                                    | Basis                                                                      | Draft review state |
-| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | ------------------ |
-| FR1 | The row MUST render one element with `role="menuitemradio"` whose `aria-checked` is true exactly when the group value equals the row value. It MUST NOT nest a native or ARIA radio.                                                                                                   | WAI-ARIA menu pattern; current source and focused tests                    | verify             |
-| FR2 | Rendering the row outside a DropdownMenuRadioGroup MUST throw.                                                                                                                                                                                                                         | Current source and focused tests                                           | verify             |
-| FR3 | Enabled activation, by pointer or by the parent's synthesized Enter/Space click, MUST call the group `onChange` with the row value, then ask DropdownMenu to close when the group's close policy is on, then call the caller `onClick`.                                                | Released behavior; `architecture:public-component-api/INV7`; focused tests | verify             |
-| FR4 | A disabled row MUST expose `aria-disabled="true"`, render no `tabindex`, take no hover focus, and on any activation, including an assistive-technology click, MUST NOT call `onChange`, close the menu, or call the caller `onClick`. It paints at half opacity with a default cursor. | Current source, focused tests, and browser evidence                        | verify             |
-| FR5 | Ref, supported host attributes and handlers, `className`, `style`, and `xstyle` MUST reach or compose on the row root. Caller `onPointerMove` MUST run after the row's hover focus, and caller handlers MUST NOT replace the row's own behavior.                                       | `architecture:public-component-api/INV5–INV8`; focused tests               | verify             |
-| FR6 | The marker MUST be the shared radio Indicator, hidden from assistive technology, never the pointer target, sized `sm` in a small menu and `md` otherwise, at the row's inline start on a fine pointer and its inline end on a coarse pointer.                                          | Current source, focused tests, and browser evidence                        | verify             |
-| FR7 | The row MUST carry the `dropdown-menu-item` target with the menu size and the marker MUST carry the `dropdown-menu-radio` target with size, checked, and disabled reflections.                                                                                                         | `architecture:component-theming-surface/INV4–INV6`; current source/docs    | verify             |
-| FR8 | The row MUST add no key handler or tab stop of its own: enabled rows are `tabindex="-1"` for the parent's roving focus, and keyboard selection arrives as the parent's synthesized click.                                                                                              | `architecture:interaction-modality`; parent keyboard tests                 | verify             |
+| ID  | Invariant                                                                                                                                                                                                                                                                                   | Basis                                                                |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| FR1 | The row renders one element with `role="menuitemradio"` whose `aria-checked` is true exactly when the group value equals the row value. It nests no native or ARIA radio.                                                                                                                   | `spec:AST-020`; current source and tests                             |
+| FR2 | Rendering the row outside a DropdownMenuRadioGroup throws.                                                                                                                                                                                                                                  | Current source and focused tests                                     |
+| FR3 | Enabled activation, by pointer or by the parent's synthesized Enter/Space click, calls the group `onChange` with the row value, then asks DropdownMenu to close when the group's close policy is on, then calls the caller `onClick`.                                                       | `architecture:public-component-api` INV7; current behavior and tests |
+| FR4 | A disabled row exposes `aria-disabled="true"`, renders no `tabindex`, takes no hover focus, and on any activation, including an assistive-technology click, calls neither `onChange` nor the caller `onClick` and does not close the menu. It paints at half opacity with a default cursor. | Current source and tests                                             |
+| FR5 | Ref, supported host attributes and handlers, `className`, `style`, and `xstyle` reach or compose on the row root. Caller `onPointerMove` runs after the row's hover focus, and caller handlers do not replace the row's own behavior.                                                       | `architecture:public-component-api` INV5–INV8; current tests         |
+| FR6 | The marker is the shared radio Indicator, hidden from assistive technology, never the pointer target, sized `sm` in a small menu and `md` otherwise, at the row's inline start on a fine pointer and its inline end on a coarse pointer.                                                    | Current source and tests                                             |
+| FR7 | The row carries the `dropdown-menu-item` target with the menu size and the marker carries the `dropdown-menu-radio` target with size, checked, and disabled reflections.                                                                                                                    | `architecture:component-theming-surface`; current source and docs    |
+| FR8 | The row adds no key handler or tab stop of its own: enabled rows are `tabindex="-1"` for the parent's roving focus, and keyboard selection arrives as the parent's synthesized click.                                                                                                       | `architecture:interaction-modality`; parent keyboard tests           |
 
 ### Allowed variation
 
@@ -165,23 +161,21 @@ intentional decision.
 - **AR3 — Keyboard ownership.** DropdownMenu owns focus movement and activation;
   the row adds no key handling. Whether disabled rows stay keyboard-discoverable
   is owned by `component:DropdownMenu` (its OQ1).
-- **AR4 — Focus visibility (objective gap).** Keyboard focus MUST be
-  perceivable (WCAG 2.2 SC 2.4.7 and 1.4.11). The row currently paints focus
-  only as the menu overlay tint with no outline, which measures about 1.1:1
-  against the menu surface and paints nothing under forced colors. The
-  remediation is a shared row-visual decision with `component:DropdownMenuItem`
-  (its OQ2); this draft records the gap and does not settle it.
+- **AR4 — Focus visibility.** Keyboard focus paints only the menu overlay
+  tint, about 1.1:1 against the menu surface in the default themes, with no
+  outline, and nothing under forced colors. The shared row
+  treatment is `component:DropdownMenuItem` OQ2.
 
 ## Design relationships
 
-| Anatomy or state | Design requirement                                               | Representation authority         | Hierarchy role | Component contract |
-| ---------------- | ---------------------------------------------------------------- | -------------------------------- | -------------- | ------------------ |
-| Row              | Menu row paint and radius; focus paint is the AR4 objective gap. | Current source and menu tokens   | structural     | FR7, AR4           |
-| Radio marker     | Shared radio Indicator at the menu's control size.               | Shared radio Indicator           | prominent      | FR1, FR6           |
-| Disabled         | Half-opacity row with a default cursor.                          | Current source                   | supporting     | FR4                |
-| Direction/touch  | Logical marker placement that mirrors and moves on touch.        | Bidirectionality and current CSS | structural     | FR6                |
+| Anatomy or state | Design requirement                                        | Representation authority         | Hierarchy role | Component contract |
+| ---------------- | --------------------------------------------------------- | -------------------------------- | -------------- | ------------------ |
+| Row              | Menu row paint and radius; focus paint is AR4.            | Current source and menu tokens   | structural     | FR7, AR4           |
+| Radio marker     | Shared radio Indicator at the menu's control size.        | Shared radio Indicator           | prominent      | FR1, FR6           |
+| Disabled         | Half-opacity row with a default cursor.                   | Current source                   | supporting     | FR4                |
+| Direction/touch  | Logical marker placement that mirrors and moves on touch. | Bidirectionality and current CSS | structural     | FR6                |
 
-No new component-local visual decision is settled by this draft.
+No component-local visual decision is recorded.
 
 ## Family and system relationships
 
@@ -195,21 +189,29 @@ No new component-local visual decision is settled by this draft.
   reflection.
 - `architecture:component-test-sufficiency` owns proportionate observable evidence.
 - `spec:AST-020` supplies WCAG/APG adoption and evidence-layer boundaries.
-- `spec:AST-029` keeps this observational draft separate from the audit receipt.
 
 ## Verification map
 
-| Contract      | Verification                                                                                        | Representative states                                          | Mutation or failure expectation                                                                                              | Audit section                              |
-| ------------- | --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
-| FR1, FR2, AR1 | `DropdownMenuSelectable.test.tsx`; reusable radio-group and Menu contracts; scoped axe              | checked, unchecked, outside a group                            | A nested radio, wrong checked row, extra announced control, or missing throw fails                                           | `audit:DropdownMenuRadioItem/§1,§4,§6`     |
-| FR3, FR5, FR8 | `DropdownMenuSelectable.test.tsx` handler, keyboard, close, and ref cases; browser fixture counters | pointer and keyboard activation, close on/off, caller handlers | A dropped caller handler, wrong order, or missing close fails                                                                | `audit:DropdownMenuRadioItem/§3,§4,§6`     |
-| FR4, AR2      | Disabled focused test with an assistive-technology click; browser disabled-hover frame              | disabled checked/unchecked                                     | Removing the disabled guard makes the focused test fail                                                                      | `audit:DropdownMenuRadioItem/§1,§4`        |
-| AR4           | Exact-head keyboard-focus and forced-colors frames with rendered contrast                           | Neutral/Butter light/dark focus, forced colors                 | Current frames record the gap; a remediation passes only with a perceivable indicator in every theme and under forced colors | `audit:DropdownMenuRadioItem/§1,§5`        |
-| FR6, FR7      | Marker and target tests; exact-head Neutral/Butter/RTL/narrow/size/coarse/focus frames              | sm/md/lg, fine/coarse, LTR/RTL, light/dark                     | A lost target or reflection, a marker that is announced, wrongly sized, or misplaced fails                                   | `audit:DropdownMenuRadioItem/§2,§5,§9,§10` |
+| Contract | Verification                                                                                                                                                                                                                                                                                                                                                                      | Representative states                            | Mutation or failure expectation                                                                                                                                                                      | Audit section                           |
+| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
+| FR1, AR1 | `DropdownMenuSelectable.test.tsx` "renders the shared radio indicator in the menu marker" and "composes caller root inputs without replacing the row semantics"; `Menu.a11y.test.tsx` menu binding cases                                                                                                                                                                          | Checked and unchecked                            | A row that is not `menuitemradio` or a wrong `aria-checked` fails. Evidence gap: no test asserts the absence of a nested radio.                                                                      | `audit:DropdownMenuRadioItem/semantics` |
+| FR2      | `DropdownMenuSelectable.test.tsx` "throws when a radio item is used outside a group"                                                                                                                                                                                                                                                                                              | Outside a group                                  | A row that renders outside a group fails.                                                                                                                                                            | `audit:DropdownMenuRadioItem/behavior`  |
+| FR3, FR8 | `DropdownMenuSelectable.test.tsx` "calls onChange with the selected value", "composes the caller click handler with the selection", "composes the caller click handler on keyboard activation", "keeps the menu open while controlled selection updates when requested"; `DropdownMenu.test.tsx` "activates a focused menuitemradio with Enter and a menuitemcheckbox with Space" | Pointer and keyboard activation; close off       | A missing `onChange`, a dropped caller `onClick`, or a close despite the opt-out fails. Evidence gap: no test asserts the `onChange`, close, `onClick` order or the `tabindex="-1"` on enabled rows. | `audit:DropdownMenuRadioItem/behavior`  |
+| FR4, AR2 | `DropdownMenuSelectable.test.tsx` "does not select, close, or call the caller click handler when disabled"; `DropdownMenu.test.tsx` "does not move focus on hover for a disabled item"                                                                                                                                                                                            | Disabled                                         | A selection, close, or caller `onClick` while disabled, or hover focus on a disabled row, fails. Evidence gap: no test asserts the absent `tabindex` or the half-opacity paint.                      | `audit:DropdownMenuRadioItem/behavior`  |
+| FR5      | `DropdownMenuSelectable.test.tsx` "composes caller root inputs without replacing the row semantics", "composes the caller pointer-move handler with menu hover focus", and "a ref reaches the menuitemradio element"                                                                                                                                                              | Ref, host attributes, class, style, pointer move | A dropped ref, attribute, class, style, or handler fails. Evidence gap: no test asserts `xstyle` on the row.                                                                                         | `audit:DropdownMenuRadioItem/api`       |
+| FR6, FR7 | `DropdownMenuSelectable.test.tsx` "renders the shared radio indicator in the menu marker"; `DropdownMenuRadioItemAudit.a11y.chromium.spec.ts`                                                                                                                                                                                                                                     | Marker in the row                                | A missing shared radio marker fails. Evidence gap: no test asserts the marker size by menu size, its fine and coarse placement, or the `dropdown-menu-radio` reflections.                            | `audit:DropdownMenuRadioItem/visual`    |
+| AR4, PR1 | Evidence gap: no test asserts the focus paint, forced-colors focus, or the absence of lifecycle resources                                                                                                                                                                                                                                                                         | —                                                | —                                                                                                                                                                                                    | `audit:DropdownMenuRadioItem/visual`    |
+
+## Current-state impact
+
+- **Focus visibility (AR4).** Keyboard focus on a radio row shows only an
+  overlay tint about 1.1:1 against the menu surface, and no indicator in
+  forced-colors mode; the shared row treatment is
+  `component:DropdownMenuItem` OQ2.
 
 ## Decision log
 
-None. This draft records current facts and introduces no product decision.
+No component-local decision.
 
 ## Open questions
 
@@ -222,5 +224,4 @@ None. This draft records current facts and introduces no product decision.
 ## Content boundary
 
 This file does not duplicate consumer prop tables/examples, current audit scores,
-screenshot matrices, implementation steps, or group/parent contracts. The audit
-pull request owns the closed run evidence required by `spec:AST-029/FR5`.
+screenshot matrices, implementation steps, or group/parent contracts. It links to their owners.

package/src/DropdownMenu/DropdownMenuSubMenu.spec.md

@@ -3,20 +3,20 @@ schema_version: 3
 template_version: 7
 kind: component
 id: component:DropdownMenuSubMenu
-authority: draft
+authority: current
 archive_reason: null
 superseded_by: null
-approved_by: null
-approved_at: null
+approved_by: cixzhang
+approved_at: 2026-10-31
 owners: [cixzhang]
 review_triggers: [public-api, behavior, accessibility, theming, layout, testing]
 verified_by:
   [
     packages/core/src/DropdownMenu/DropdownMenuSubMenu.test.tsx,
+    packages/core/src/__tests__/BusyOwnerAnnouncement.test.tsx,
     packages/core/src/DropdownMenu/__tests__/SubMenuHeaderFooter.a11y.chromium.spec.ts,
     packages/core/src/DropdownMenu/__tests__/DropdownMenuDrillIn.a11y.chromium.spec.ts,
     packages/core/src/DropdownMenu/__tests__/DropdownMenuSubMenuAudit.a11y.chromium.spec.ts,
-    apps/storybook/stories/DropdownMenuSubMenu.stories.tsx,
     apps/storybook/rtl-audit/targets.json,
     scripts/check-knowledge.mjs,
   ]
@@ -33,7 +33,7 @@ architecture:
     architecture:react-component-runtime,
   ]
 contributing: []
-system_specs: [spec:AST-020, spec:AST-029, spec:AST-086]
+system_specs: [spec:AST-020, spec:AST-086]
 ---
 
 # DropdownMenuSubMenu component contract
@@ -46,9 +46,9 @@ system_specs: [spec:AST-020, spec:AST-029, spec:AST-086]
 | Behavior                | The row reveals its children as a flyout beside it or as a drilled-in view led by a Back row; with a header or footer that surface is a modal dialog named by the row.                                         |
 | End-user impact         | Pointer, keyboard, and touch users reach nested commands from one row; assistive technology hears the row's popup kind and expanded state, and Escape or the close arrow returns to the row.                   |
 | Builder impact          | Place the row inside a DropdownMenu or ContextMenu and give it a label and rows; data-driven menus get it from a nested `items` array.                                                                         |
-| Compatibility/readiness | Released subcomponent; observational draft of current behavior. Authority stays `draft` until owner approval.                                                                                                  |
+| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change.                                                                                                                                                      |
 | Review checks           | Reject a second keyboard owner, a lost popup state, a flyout that does not flip under RTL, a disabled row that opens, dropped caller inputs, or an open callback that misses a transition.                     |
-| Governing rules         | WAI-ARIA menu pattern; `architecture:public-component-api/INV5–INV8`; `architecture:react-component-runtime/INV2`; `architecture:layer-runtime`; `spec:AST-020/FR1,FR2`; `spec:AST-086/FR8`.                   |
+| Governing rules         | `spec:AST-020` FR15; `architecture:public-component-api/INV5–INV8`; `architecture:react-component-runtime/INV2`; `architecture:layer-runtime`; `spec:AST-020/FR1,FR2`; `spec:AST-086/FR8`.                     |
 
 This table is a review projection; the body below is authoritative.
 
@@ -66,7 +66,8 @@ host that a sub-menu with a header or footer renders into.
 
 - Released default preserved: yes (`isDisabled=false`, `hasSpinner=false`,
   `presentation='adaptive'`).
-- Compatibility class: no public API change.
+- Compatibility class: records shipped behavior; no public prop, default,
+  export, or DOM change.
 - Controlled behavior: the open state is internal; `onOpenChange` reports it.
 - Migration decision: none.
 
@@ -107,20 +108,17 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ## Behavioral and layout contract
 
-Draft requirements identify their basis so observed code is not mistaken for an
-intentional decision.
-
-| ID  | Candidate invariant                                                                                                                                                                                                                                                          | Basis                                                             | Draft review state                                                                                       |
-| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
-| FR1 | The row MUST expose `role="menuitem"`, `aria-haspopup="menu"` (`"dialog"` with a header or footer), `aria-expanded` matching its surface, and `aria-controls` naming the surface while open. The surface MUST be labelled by the row.                                        | WAI-ARIA menu pattern; current source and focused tests           | verify                                                                                                   |
-| FR2 | A click, Enter, Space, or the inline-end arrow (inline-start under RTL) MUST open the surface; a keyboard open MUST focus its first row. Escape or the close arrow MUST close only this level and return focus to the row. A hover MUST open a flyout after an intent delay. | WAI-ARIA menu pattern; `architecture:interaction-modality`; tests | verify                                                                                                   |
-| FR3 | A flyout MUST sit beside the row on the inline-end side, flip with direction, and stay within the viewport; its block size MUST cap at the smaller of its own cap and the viewport.                                                                                          | `architecture:layer-runtime`; current source and browser evidence | verify                                                                                                   |
-| FR4 | A drilled-in view MUST replace the root's rows with a Back row named after the parent menu and then this row's children; Back, Escape, and the close arrow MUST return to the row.                                                                                           | Current source and focused tests                                  | verify                                                                                                   |
-| FR5 | Selecting a leaf row inside the surface MUST close every level and the root menu.                                                                                                                                                                                            | Current source, focused tests, and browser evidence               | verify                                                                                                   |
-| FR6 | `onOpenChange` MUST report `true` once when the surface opens and `false` once when it closes, from the action that caused the change.                                                                                                                                       | Documented promise; `architecture:react-component-runtime/INV2`   | objective gap: a drilled-in view reset by the root menu closing reports no `false` (owner: DropdownMenu) |
-| FR7 | A disabled row MUST expose `aria-disabled="true"`, render no `tabindex`, take no hover focus, open on no input, and run no caller `onClick`.                                                                                                                                 | Current source, focused tests, and browser evidence               | verify                                                                                                   |
-| FR8 | With `hasSpinner` the row MUST show a decorative spinner in place of the caret and announce the busy start once the root menu shows.                                                                                                                                         | `spec:AST-086/FR8`; current source                                | verify                                                                                                   |
-| FR9 | Ref, supported host attributes and handlers, `className`, `style`, and `xstyle` MUST reach or compose on the row root after the row's own behavior; the open keys and a disabled click stop before the caller's handler.                                                     | `architecture:public-component-api/INV5–INV8`; focused tests      | verify                                                                                                   |
+| ID  | Invariant                                                                                                                                                                                                                                                      | Basis                                                              |
+| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| FR1 | The row exposes `role="menuitem"`, `aria-haspopup="menu"` (`"dialog"` with a header or footer), `aria-expanded` matching its surface, and `aria-controls` naming the surface while open. The surface is labelled by the row.                                   | `spec:AST-020`; current source and tests                           |
+| FR2 | A click, Enter, Space, or the inline-end arrow (inline-start under RTL) opens the surface; a keyboard open focuses its first row. Escape or the close arrow closes only this level and returns focus to the row. A hover opens a flyout after an intent delay. | `spec:AST-020`; `architecture:interaction-modality`; current tests |
+| FR3 | A flyout sits beside the row on the inline-end side, flips with direction, and stays within the viewport; its block size caps at the smaller of its own cap and the viewport.                                                                                  | `architecture:layer-runtime`; current source                       |
+| FR4 | A drilled-in view replaces the root's rows with a Back row named after the parent menu and then this row's children; Back, Escape, and the close arrow return to the row.                                                                                      | Current source and focused tests                                   |
+| FR5 | Selecting a leaf row inside the surface closes every level and the root menu.                                                                                                                                                                                  | Current source and tests                                           |
+| FR6 | `onOpenChange` MUST report `true` once when the surface opens and `false` once when it closes, from the action that caused the change. Implementation gap: a drilled-in view reset by the root menu closing reports no `false` (OQ1).                          | Documented promise; `architecture:react-component-runtime` INV2    |
+| FR7 | A disabled row exposes `aria-disabled="true"`, renders no `tabindex`, takes no hover focus, opens on no input, and runs no caller `onClick`.                                                                                                                   | Current source and tests                                           |
+| FR8 | With `hasSpinner` the row shows a decorative spinner in place of the caret and announces the busy start once the root menu shows.                                                                                                                              | `spec:AST-086` FR8; current source and tests                       |
+| FR9 | Ref, supported host attributes and handlers, `className`, `style`, and `xstyle` reach or compose on the row root after the row's own behavior; the open keys and a disabled click stop before the caller's handler.                                            | `architecture:public-component-api` INV5–INV8; current tests       |
 
 ### Allowed variation
 
@@ -164,12 +162,10 @@ intentional decision.
   Escape; a deeper level's keys never act on its parent.
 - **AR3 — Disabled discoverability.** Whether disabled rows stay
   keyboard-discoverable is owned by `component:DropdownMenu` (its OQ1).
-- **AR4 — Focus visibility (objective gap).** Keyboard focus MUST be
-  perceivable (WCAG 2.2 SC 2.4.7 and 1.4.11). The row currently paints focus
-  only as the menu overlay tint with no outline, and paints nothing under
-  forced colors. The remediation is a shared row-visual decision with
-  `component:DropdownMenuItem` (its OQ2); this draft records the gap and does
-  not settle it.
+- **AR4 — Focus visibility.** Keyboard focus paints only the menu overlay
+  tint, about 1.1:1 against the menu surface in the default themes, with no
+  outline, and nothing under forced colors. The shared row
+  treatment is `component:DropdownMenuItem` OQ2.
 
 ## Design relationships
 
@@ -181,7 +177,7 @@ intentional decision.
 | Drilled view     | Rows inside the root's box, led by a mirrored Back row.       | Current source                   | structural     | FR4                |
 | Disabled         | Half-opacity row with a default cursor.                       | Current source                   | supporting     | FR7                |
 
-No new component-local visual decision is settled by this draft.
+No component-local visual decision is recorded.
 
 ## Family and system relationships
 
@@ -193,22 +189,33 @@ No new component-local visual decision is settled by this draft.
 - `architecture:public-component-api` owns root input and handler composition.
 - `architecture:react-component-runtime` owns callback timing.
 - `spec:AST-086` owns the loading announcement.
-- `spec:AST-029` keeps this observational draft separate from the audit receipt.
 
 ## Verification map
 
-| Contract      | Verification                                                                  | Representative states               | Mutation or failure expectation                                                       | Audit section                         |
-| ------------- | ----------------------------------------------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------- |
-| FR1, FR2, AR2 | `DropdownMenuSubMenu.test.tsx` keyboard, hover, typeahead, and nesting suites | open, close, nested, loading        | A lost popup state, wrong focus target, or double-stepped level fails                 | `audit:DropdownMenuSubMenu/§1,§4,§6`  |
-| FR3           | RTL D4 flyout target; exact-head LTR/RTL/narrow open frames                   | LTR, RTL, 320px                     | A flyout on the wrong side or outside the viewport fails                              | `audit:DropdownMenuSubMenu/§5,§9,§10` |
-| FR4, FR5      | Drill-in and selection tests; exact-head drill-in and select frames           | drilled, nested selection           | A missing Back row or a stack that stays open fails                                   | `audit:DropdownMenuSubMenu/§4`        |
-| FR6           | onOpenChange test (mutation-sensitive); browser select-frame counters         | flyout open and close               | Dropping the close report fails; the drill-in reset gap is recorded, not asserted     | `audit:DropdownMenuSubMenu/§3,§4`     |
-| FR7, FR9      | Host-attribute, handler, and disabled tests; disabled-hover frames            | disabled, caller handlers, test ids | A disabled open or dropped caller input fails                                         | `audit:DropdownMenuSubMenu/§1,§3`     |
-| AR4           | Exact-head keyboard-focus and forced-colors frames with rendered contrast     | Neutral/Butter focus, forced colors | Current frames record the gap; a remediation passes only with a perceivable indicator | `audit:DropdownMenuSubMenu/§1,§5`     |
+| Contract | Verification                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Representative states                      | Mutation or failure expectation                                                                                                                                               | Audit section                             |
+| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
+| FR1, AR1 | `DropdownMenuSubMenu.test.tsx` "renders the trigger with aria-haspopup and collapsed aria-expanded", "names the flyout from its trigger via aria-labelledby", "the row keeps its own popup state and tab stop"; header-and-footer case "holds the header, the rows and the footer in a dialog named by the row, outside every menu"                                                                                                                                                                                          | Closed and open; with regions              | A missing `aria-haspopup`, `aria-expanded`, or row label on the surface fails. Evidence gap: no test asserts `aria-controls` while open.                                      | `audit:DropdownMenuSubMenu/semantics`     |
+| FR2, AR2 | `DropdownMenuSubMenu.test.tsx` "opens the flyout on trigger click and exposes its items", "opens on ArrowRight and returns focus to the trigger on ArrowLeft", "mirrors its indicator and keyboard directions under RTL", "closes only the submenu on Escape and restores focus to the trigger", "supports first-character type-ahead within the flyout", "navigates a two-level nested submenu without double-stepping", "moves focus to the submenu trigger on hover, keeping a single highlight"; hover/click-guard cases | Click, arrows, RTL, Escape, hover, nesting | A key that does not open or close, a wrong focus target, a double-stepped level, or a reversed RTL arrow fails. Evidence gap: no test asserts Enter or Space opening the row. | `audit:DropdownMenuSubMenu/accessibility` |
+| FR3      | `DropdownMenuSubMenu.test.tsx` "caps the flyout width and height to the available viewport"; `apps/storybook/rtl-audit/targets.json` DropdownMenuSubMenu entry                                                                                                                                                                                                                                                                                                                                                               | Viewport cap; RTL                          | A flyout that escapes the viewport fails. Evidence gap: no test asserts the inline-end placement or its flip.                                                                 | `audit:DropdownMenuSubMenu/layout`        |
+| FR4      | `DropdownMenuSubMenu.test.tsx` drill-in cases; `DropdownMenuDrillIn.a11y.chromium.spec.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                   | Drilled view; Back                         | A missing Back row or a Back that does not return fails.                                                                                                                      | `audit:DropdownMenuSubMenu/behavior`      |
+| FR5      | `DropdownMenuSubMenu.test.tsx` "closes the whole menu after selecting a nested item" and "activates a nested item with the Enter key and closes the menu"                                                                                                                                                                                                                                                                                                                                                                    | Pointer and Enter                          | A level left open after a leaf pick fails.                                                                                                                                    | `audit:DropdownMenuSubMenu/behavior`      |
+| FR6      | `DropdownMenuSubMenu.test.tsx` "reports each flyout open and close to onOpenChange once"                                                                                                                                                                                                                                                                                                                                                                                                                                     | Flyout open and close                      | A missing or repeated report fails. Evidence gap: the drill-in reset gap is not asserted.                                                                                     | `audit:DropdownMenuSubMenu/behavior`      |
+| FR7, FR9 | `DropdownMenuSubMenu.test.tsx` "does not open a disabled submenu", "a disabled row does not pass a click on to the caller's onClick", host-attribute and ref cases ("aria-\*, data-\* and id reach the trigger row, and the flyout stays labelled by it", "a ref reaches the trigger row", "a caller's handlers run after the row's own, and the row still opens and takes the hover focus")                                                                                                                                 | Disabled; caller handlers and attributes   | A disabled open or caller click, or a dropped attribute, ref, or handler, fails. Evidence gap: no test asserts `className`, `style`, or `xstyle` on the row.                  | `audit:DropdownMenuSubMenu/api`           |
+| FR8      | `BusyOwnerAnnouncement.test.tsx` "DropdownMenuSubMenu loading state" cases; `DropdownMenuSubMenu.test.tsx` loading-flyout cases                                                                                                                                                                                                                                                                                                                                                                                              | Loading closed and open                    | A busy start announced while closed, twice, or not at all, or an announced Spinner, fails.                                                                                    | `audit:DropdownMenuSubMenu/accessibility` |
+| AR4, PR1 | Evidence gap: no test asserts the focus paint, forced-colors focus, or the timer bounds                                                                                                                                                                                                                                                                                                                                                                                                                                      | —                                          | —                                                                                                                                                                             | `audit:DropdownMenuSubMenu/visual`        |
+
+## Current-state impact
+
+- **Drill-in close report (FR6).** When the root menu closes a drilled-in view,
+  `onOpenChange(false)` does not run (OQ1).
+- **Focus visibility (AR4).** Keyboard focus on the row shows only an
+  overlay tint about 1.1:1 against the menu surface, and no indicator in
+  forced-colors mode; the shared row treatment is
+  `component:DropdownMenuItem` OQ2.
 
 ## Decision log
 
-None. This draft records current facts and introduces no product decision.
+No component-local decision.
 
 ## Open questions
 
@@ -221,5 +228,4 @@ None. This draft records current facts and introduces no product decision.
 ## Content boundary
 
 This file does not duplicate consumer prop tables/examples, current audit scores,
-screenshot matrices, implementation steps, or root/leaf contracts. The audit
-pull request owns the closed run evidence required by `spec:AST-029/FR5`.
+screenshot matrices, implementation steps, or root/leaf contracts. It links to their owners.

package/src/DropdownMenu/DropdownMenuSubMenu.tsx

@@ -1183,7 +1183,9 @@ export function DropdownMenuSubMenu(
   // on the menu element shows the ring the base style otherwise removes.
   const handleMenuFocus = (event: React.FocusEvent<HTMLDivElement>) => {
     if (hasRegions && event.target === event.currentTarget) {
-      setIsMenuKeyboardFocused(getInteractionModality() === 'keyboard');
+      setIsMenuKeyboardFocused(
+        getInteractionModality(event.currentTarget) === 'keyboard',
+      );
     }
   };
   const handleMenuBlur = (event: React.FocusEvent<HTMLDivElement>) => {

package/src/DropdownMenu/MenuBottomSheetActionList.tsx

@@ -11,14 +11,16 @@
 
 import React, {useRef, type ReactElement} from 'react';
 import * as stylex from '@stylexjs/stylex';
-import {Divider} from '../Divider';
-import {Heading} from '../Heading';
-import {Icon, renderIconSlot} from '../Icon';
-import {List, ListItem} from '../List';
+import {Divider} from '../Divider/Divider';
+import {Heading} from '../Heading/Heading';
+import {Icon, renderIconSlot} from '../Icon/Icon';
+import {List} from '../List/List';
+import {ListItem} from '../List/ListItem';
 import {useMenuPress} from '../hooks/useMenuPress';
+import {useMergedRefs} from '../hooks/useMergedRefs';
 import {colorVars, spacingVars} from '../theme/tokens.stylex';
-import {rtlStyles} from '../utils';
-import {getInteractionModality} from '../utils/interactionModality';
+import {rtlStyles} from '../utils/rtlStyles';
+import {useInteractionModalityTracking} from '../utils/interactionModality';
 import type {DropdownMenuItemData, DropdownMenuOption} from './DropdownMenu';
 import {isModifiedClick} from './menuItemRoles';
 
@@ -67,6 +69,8 @@ export function MenuBottomSheetActionList({
   onOpenSubmenu: (item: DropdownMenuItemData) => void;
 }) {
   const listRef = useRef<HTMLUListElement>(null);
+  const {ref: modalityRef, readModality} = useInteractionModalityTracking();
+  const listComposedRef = useMergedRefs(listRef, modalityRef);
   // The press model: the row under a finger's RELEASE acts, and the
   // highlight (focus) follows the finger across the rows. The sheet is modal,
   // so a release outside it is the scrim's, not a dismissal of ours.
@@ -89,7 +93,7 @@ export function MenuBottomSheetActionList({
         event.preventDefault();
         return;
       }
-      if (getInteractionModality() === 'pointer') {
+      if (readModality() === 'pointer') {
         (event.currentTarget as HTMLElement).blur();
       }
       if (isSubmenu) {
@@ -145,7 +149,7 @@ export function MenuBottomSheetActionList({
 
   return (
     <List
-      ref={listRef}
+      ref={listComposedRef}
       density="spacious"
       xstyle={styles.list}
       {...menuPress.menuProps}>

package/src/DropdownMenu/lazyMenuBottomSheet.ts

@@ -15,6 +15,11 @@
  * of pages whose dropdowns only open as anchored popovers. Each wrapper keeps
  * the wrapped component's props and renders nothing until its module loads.
  *
+ * The action list preloads at rest, and the preload's result says whether it
+ * loaded. A failed load is not kept, so the next preload or open asks the
+ * module loader again (a loader that retries then loads it; a browser does not
+ * fetch a native module again once its import failed).
+ *
  * Neither wrapper renders on the server or in the render that hydrates server
  * HTML (spec:AST-013 FR9): a lazy component that has not loaded yet would
  * leave server markup incomplete and abort hydration. The closed sheet has no
@@ -47,16 +52,40 @@ const LazyMenuBottomSheet = lazy(async () =>
 let actionListModule: typeof ActionListModule | null = null;
 let actionListLoad: Promise<typeof ActionListModule> | null = null;
 async function loadActionList(): Promise<typeof ActionListModule> {
-  actionListLoad ??= import('./MenuBottomSheetActionList').then(module => {
-    actionListModule = module;
-    return module;
-  });
+  actionListLoad ??= import('./MenuBottomSheetActionList').then(
+    module => {
+      actionListModule = module;
+      return module;
+    },
+    (error: unknown) => {
+      // A failed load (a dropped connection) is not kept: the next caller
+      // asks the module loader again.
+      actionListLoad = null;
+      throw error;
+    },
+  );
   return actionListLoad;
 }
 
-/** Starts loading the action list; a sheet menu calls it at rest. */
-export function preloadMenuBottomSheetActionList(): void {
-  void loadActionList();
+/** What a preload of the action list came to: loaded, or failed with the loader's error. */
+export type ActionListPreload =
+  | {readonly isLoaded: true}
+  | {readonly isLoaded: false; readonly error: unknown};
+
+/**
+ * Starts loading the action list; a sheet menu calls it at rest. Its result
+ * says whether the list loaded: a failure (a dropped connection) is that
+ * result, with the loader's error, and never a rejection. The failed load is
+ * not kept, so the first open asks the module loader again, and a load that
+ * fails there reaches the menu through lazy().
+ */
+export async function preloadMenuBottomSheetActionList(): Promise<ActionListPreload> {
+  try {
+    await loadActionList();
+    return {isLoaded: true};
+  } catch (error) {
+    return {isLoaded: false, error};
+  }
 }
 
 const LazyMenuBottomSheetActionList = lazy(async () =>

package/src/DropdownMenu/renderDropdownItems.tsx

@@ -68,6 +68,28 @@ function renderLeafItem(
   return <DropdownMenuItem key={getItemKey(item, index)} {...itemProps} />;
 }
 
+/**
+ * A data item that declares nested `items` becomes a submenu (data-mode
+ * parity with the compound DropdownMenuSubMenu API), at the top level and
+ * inside a section alike; otherwise it's a leaf. renderDropdownItems owns the
+ * recursion and hands the rendered children to DropdownMenuSubMenu, so
+ * DropdownMenuSubMenu never imports this module back (no import cycle).
+ */
+function renderItem(item: DropdownMenuItemData, index: number): ReactElement {
+  if (item.items && item.items.length > 0) {
+    return (
+      <DropdownMenuSubMenu
+        key={getItemKey(item, index)}
+        icon={item.icon}
+        label={item.label}
+        isDisabled={item.isDisabled}>
+        {renderDropdownItems(item.items)}
+      </DropdownMenuSubMenu>
+    );
+  }
+  return renderLeafItem(item, index);
+}
+
 /**
  * Converts data-driven items into DropdownMenuItem components,
  * so both modes share the same rendering and keyboard navigation path.
@@ -96,28 +118,11 @@ export function renderDropdownItems(items: DropdownMenuOption[]): ReactNode {
               {option.title}
             </div>
           )}
-          {option.items.map(renderLeafItem)}
+          {option.items.map(renderItem)}
         </div>,
       );
     } else if (!('type' in option)) {
-      // A plain item that declares nested `items` becomes a submenu (data-mode
-      // parity with the compound DropdownMenuSubMenu API); otherwise it's a
-      // leaf. renderDropdownItems owns the recursion and hands the rendered
-      // children to DropdownMenuSubMenu — so DropdownMenuSubMenu never imports
-      // this module back (no import cycle).
-      if (option.items && option.items.length > 0) {
-        elements.push(
-          <DropdownMenuSubMenu
-            key={getItemKey(option, i)}
-            icon={option.icon}
-            label={option.label}
-            isDisabled={option.isDisabled}>
-            {renderDropdownItems(option.items)}
-          </DropdownMenuSubMenu>,
-        );
-      } else {
-        elements.push(renderLeafItem(option, i));
-      }
+      elements.push(renderItem(option, i));
     }
   }