@astryxdesign/core 0.7.3-canary.02f5fe4 → 0.7.3-canary.05bfcc5

package/dist/DropdownMenu/DropdownMenuRadioGroup.d.ts

@@ -9,7 +9,7 @@
  * comes from the parent DropdownMenu's useListFocus, which matches
  * menuitemradio rows.
  */
-import { type ReactNode } from 'react';
+import { type ReactNode, type Ref } from 'react';
 import type { BaseProps } from '../BaseProps';
 export interface DropdownMenuRadioGroupProps extends Omit<BaseProps, 'onChange'> {
     /**
@@ -24,9 +24,9 @@ export interface DropdownMenuRadioGroupProps extends Omit<BaseProps, 'onChange'>
     /**
      * Accessible name for the group, announced by screen readers so the radios
      * read as a named set (e.g. "Sort by"). Applied as the group's `aria-label`.
-     * Required -- an unnamed radio group is an accessibility defect. Pass
-     * `aria-labelledby` (via base props) instead if the name already exists as a
-     * visible element on the page.
+     * Required even when `aria-labelledby` (via base props) points to visible
+     * text; that visible reference becomes the computed name while `label`
+     * remains the fallback.
      */
     label: string;
     /**
@@ -36,6 +36,10 @@ export interface DropdownMenuRadioGroupProps extends Omit<BaseProps, 'onChange'>
      * @default true
      */
     hasCloseOnSelect?: boolean;
+    /**
+     * Ref forwarded to the role="group" root.
+     */
+    ref?: Ref<HTMLDivElement>;
     /**
      * The `DropdownMenuRadioItem`s that make up the group.
      */
@@ -58,7 +62,7 @@ export interface DropdownMenuRadioGroupProps extends Omit<BaseProps, 'onChange'>
  * </DropdownMenu>
  * ```
  */
-export declare function DropdownMenuRadioGroup({ value, onChange, label, hasCloseOnSelect, children, xstyle, className, style, ...rest }: DropdownMenuRadioGroupProps): import("react").JSX.Element;
+export declare function DropdownMenuRadioGroup({ value, onChange, label, hasCloseOnSelect, children, ref, xstyle, className, style, ...rest }: DropdownMenuRadioGroupProps): import("react").JSX.Element;
 export declare namespace DropdownMenuRadioGroup {
     var displayName: string;
 }

package/dist/DropdownMenu/DropdownMenuRadioGroup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DropdownMenuRadioGroup.d.ts","sourceRoot":"","sources":["../../src/DropdownMenu/DropdownMenuRadioGroup.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;GAUG;AAEH,OAAO,EAAU,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAI9C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAiB5C,MAAM,WAAW,2BAA4B,SAAQ,IAAI,CACvD,SAAS,EACT,UAAU,CACX;IACC;;;OAGG;IACH,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B;;OAEG;IACH,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,sBAAsB,CAAC,EACrC,KAAK,EACL,QAAQ,EACR,KAAK,EACL,gBAAuB,EACvB,QAAQ,EACR,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,IAAI,EACR,EAAE,2BAA2B,+BAiB7B;yBA3Be,sBAAsB"}
+{"version":3,"file":"DropdownMenuRadioGroup.d.ts","sourceRoot":"","sources":["../../src/DropdownMenu/DropdownMenuRadioGroup.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;GAUG;AAEH,OAAO,EAAU,KAAK,SAAS,EAAE,KAAK,GAAG,EAAC,MAAM,OAAO,CAAC;AAIxD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAiB5C,MAAM,WAAW,2BAA4B,SAAQ,IAAI,CACvD,SAAS,EACT,UAAU,CACX;IACC;;;OAGG;IACH,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B;;OAEG;IACH,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;OAEG;IACH,GAAG,CAAC,EAAE,GAAG,CAAC,cAAc,CAAC,CAAC;IAC1B;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,sBAAsB,CAAC,EACrC,KAAK,EACL,QAAQ,EACR,KAAK,EACL,gBAAuB,EACvB,QAAQ,EACR,GAAG,EACH,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,IAAI,EACR,EAAE,2BAA2B,+BAkB7B;yBA7Be,sBAAsB"}

package/dist/DropdownMenu/DropdownMenuRadioGroup.js

@@ -51,6 +51,7 @@ export function DropdownMenuRadioGroup({
   label,
   hasCloseOnSelect = true,
   children,
+  ref,
   xstyle,
   className,
   style,
@@ -63,6 +64,7 @@ export function DropdownMenuRadioGroup({
   }), [value, onChange, hasCloseOnSelect]);
   return /*#__PURE__*/_jsx("div", {
     ...rest,
+    ref: ref,
     role: "group",
     "aria-label": label,
     ...mergeProps(stylex.props(styles.group, xstyle), {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.7.3-canary.02f5fe4",
+  "version": "0.7.3-canary.05bfcc5",
   "displayName": "Astryx Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",
@@ -792,8 +792,8 @@
     "react-dom": ">=19.0.0"
   },
   "devDependencies": {
-    "@astryxdesign/a11y-spec": "0.7.3-canary.02f5fe4",
-    "@astryxdesign/cli": "0.7.3-canary.02f5fe4",
+    "@astryxdesign/a11y-spec": "0.7.3-canary.05bfcc5",
+    "@astryxdesign/cli": "0.7.3-canary.05bfcc5",
     "@babel/cli": "^7.29.7",
     "@babel/core": "^7.29.7",
     "@babel/preset-react": "^7.29.7",

package/src/Carousel/Carousel.spec.md

@@ -0,0 +1,146 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:Carousel
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-10-22
+owners: [cixzhang]
+review_triggers: [behavior, accessibility]
+verified_by:
+  [
+    packages/core/src/Carousel/Carousel.test.tsx,
+    packages/core/src/Carousel/__tests__/Carousel.a11y.chromium.spec.ts,
+  ]
+modules: []
+families: [family:buttons]
+design_specs: []
+architecture: [architecture:interaction-modality]
+contributing: []
+system_specs: [spec:AST-085, spec:AST-025]
+---
+
+# Carousel component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                                                                                                           |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | None changes.                                                                                                                                                                                                                                                                      |
+| Behavior                | An edge scroll button whose direction has run out is hidden and takes no tab stop. When the focused edge button runs out, focus moves to the scroll area.                                                                                                                          |
+| End-user impact         | A keyboard user who scrolls to the first or last item stays inside the carousel instead of landing on the page body or on an invisible control. The scroll area has no role or name yet, so screen-reader users hear little at the destination until it meets `spec:AST-025` FR12. |
+| Builder impact          | None.                                                                                                                                                                                                                                                                              |
+| Compatibility/readiness | No API change. Shipped Carousel and its current tests still use native `disabled` and hand focus to the opposite button; they change with conformance work.                                                                                                                        |
+| Review checks           | Reject focus left on a hidden edge button, focus dropped to the page body, or an edge handoff that moves focus to anything but the scroll area.                                                                                                                                    |
+| Governing rules         | `spec:AST-085` FR1, FR4; `spec:AST-025` FR12; `architecture:interaction-modality` INV1.                                                                                                                                                                                            |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+Carousel shows a horizontally scrolling row of items inside a labelled region,
+with optional scroll buttons at each edge. This record covers only what the edge
+scroll buttons do when their direction runs out. Other Carousel behavior is
+uncontracted until this record grows.
+
+## Compatibility and migration
+
+- Released default preserved: yes, except where focus lands at an edge.
+- Compatibility class: behavior correction; no API change.
+- Controlled/uncontrolled behavior: unchanged.
+- Migration decision: DEC-1.
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- Edge scroll button visibility, tab order, and the focus destination when one
+  runs out.
+
+**Does not own / non-goals**
+
+- Scroll area keyboard access and naming — `spec:AST-025`.
+- Disabled control semantics in general — `spec:AST-085`.
+- Button naming, sizing, and activation — `family:buttons`.
+- Looping, snapping, edge fades, and slide semantics — uncontracted.
+
+## Public concepts
+
+| Concept            | Closed values or states | Meaning                                            | Availability by variant/orientation/state | Default | Owner                | Stability | Invalid-value behavior |
+| ------------------ | ----------------------- | -------------------------------------------------- | ----------------------------------------- | ------- | -------------------- | --------- | ---------------------- |
+| Edge scroll button | available, run out      | Whether content remains in that button's direction | Both edges when the carousel overflows    | —       | `component:Carousel` | stable    | not applicable         |
+
+## Behavioral and layout contract
+
+| ID  | Candidate invariant                                                                                                                                                                                                                                                                                                    | Basis                                    | Draft review state |
+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | ------------------ |
+| FR1 | An edge scroll button whose direction has run out is hidden. While hidden it takes no tab stop and is not exposed to assistive technology. It stays mounted so layout does not shift. This is removal under `spec:AST-085` FR4, not a disabled control.                                                                | DEC-1                                    | settled            |
+| FR2 | When the focused edge scroll button runs out, focus moves to the scroll area without scrolling it. This holds when the content no longer overflows and the scroll area is out of the tab order (`spec:AST-025` FR12): it still takes focus programmatically. Focus never lands on the page body or on a hidden button. | DEC-1; `spec:AST-085` FR4                | settled            |
+| FR3 | The handoff happens once per edge transition, and only while the edge button held focus. An edge reached by swipe, resize, or wheel while focus is elsewhere moves nothing.                                                                                                                                            | `architecture:interaction-modality` INV8 | settled            |
+| FR4 | An edge scroll button that is available behaves as an ordinary Button.                                                                                                                                                                                                                                                 | `family:buttons`                         | settled            |
+
+### Representative states
+
+| State                                  | Required invariant                                              | Allowed variation       |
+| -------------------------------------- | --------------------------------------------------------------- | ----------------------- |
+| Mid-scroll                             | Both edge buttons available                                     | Loop keeps both enabled |
+| Focused "Scroll right" reaches the end | Button hides; focus is on the scroll area; no extra scroll      | Reduced motion          |
+| Edge reached by swipe, focus elsewhere | Button hides; focus does not move                               | —                       |
+| Content shrinks to fit                 | Both buttons hidden; a focused one hands off to the scroll area | —                       |
+
+## Accessibility contract
+
+- **AR1 — No invisible tab stops.** A hidden edge button is not focusable and is
+  not exposed to assistive technology (FR1).
+- **AR2 — Focus stays in the region.** The edge handoff keeps focus inside the
+  labelled carousel region (FR2), and the keyboard focus indicator follows
+  `architecture:interaction-modality` INV1.
+
+## Design relationships
+
+No design record governs Carousel yet. Edge button visuals stay in code and
+visual evidence.
+
+## Family and system relationships
+
+- `spec:AST-085` FR4 lets a component name a focus destination for a control it
+  removes; FR2 names the scroll area.
+- `spec:AST-025` FR12 owns the scroll area's tab stop and naming.
+- `family:buttons` owns the edge buttons' behavior while available.
+
+## Verification map
+
+| Contract | Verification                            | Representative states                                    | Mutation or failure expectation                                                | Audit section                  |
+| -------- | --------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------ |
+| FR1, AR1 | Unit and accessibility-tree tests       | at rest at each edge; no overflow                        | A hidden button that is focusable or exposed fails                             | `audit:Carousel/accessibility` |
+| FR2, AR2 | Real-browser keyboard test              | Enter on "Scroll right" until the end; same on the start | Focus on the page body, a hidden button, or the opposite button fails          | `audit:Carousel/accessibility` |
+| FR3      | Real-browser test with swipe and resize | edge reached with focus outside the carousel             | Focus moving without an edge-button press, or moving twice for one edge, fails | `audit:Carousel/accessibility` |
+
+## Decision log
+
+### DEC-1 — The scroll area receives focus when an edge button runs out
+
+**Reference:** `component:Carousel/DEC-1`
+**Decider:** cixzhang, 2026-10-22
+
+Carousel hides an edge button whose direction has run out, so keeping focus on
+it would leave a keyboard user on an invisible control. The scroll area is always
+mounted inside the labelled region and can take focus whether or not it is in the
+tab order, so focus moving there keeps the user in place inside the carousel.
+
+Rejected: the opposite edge button — it may be hidden too, and focus would jump
+across the carousel.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables/examples, current audit
+results, implementation steps, or family/system rules. It links to their owners.

package/src/DropdownMenu/DropdownMenuRadioGroup.doc.mjs

@@ -8,7 +8,52 @@ export const docs = {
   displayName: 'Dropdown Menu Radio Group',
   isHiddenFromOverview: true,
   description:
-    'A single-select group of radio menu items (role="group" of menuitemradio). Owns the selected value and lays its items out with the menu\'s inter-item gap.',
+    'A controlled, named single-select group of DropdownMenuRadioItem children (role="group" of menuitemradio). Owns value propagation, close policy, root composition, and the menu inter-item gap; the parent DropdownMenu owns keyboard navigation.',
+  usage: {
+    description:
+      'Use DropdownMenuRadioGroup inside compound-mode DropdownMenu when several commands represent one mutually exclusive choice. Keep value in caller state, provide a concise accessible label, and render each choice as DropdownMenuRadioItem.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Keep value controlled and update it from onChange so checked state follows caller data.',
+      },
+      {
+        guidance: true,
+        description:
+          'Provide a concise label even when aria-labelledby points to visible text; label remains required and supplies the aria-label fallback.',
+      },
+      {
+        guidance: true,
+        description:
+          'Set hasCloseOnSelect=false only when the menu must stay open to show another selection or an in-place result.',
+      },
+      {
+        guidance: false,
+        description:
+          'Place buttons, links, checkboxes, or arbitrary menu rows inside the radio group.',
+      },
+      {
+        guidance: false,
+        description:
+          'Add a second key handler or roving-focus model; DropdownMenu owns keyboard navigation.',
+      },
+    ],
+    anatomy: [
+      {
+        name: 'Group',
+        required: true,
+        description:
+          'The role="group" root that owns the accessible name, controlled-selection context, close policy, root inputs, and inter-item gap.',
+      },
+      {
+        name: 'Radio items',
+        required: true,
+        description:
+          'DropdownMenuRadioItem children; each child owns its menuitemradio role, checked state, content, and indicator paint.',
+      },
+    ],
+  },
   playground: {
     wrapper: {
       component: 'DropdownMenu',
@@ -42,17 +87,20 @@ export const docs = {
       type: 'string | undefined',
       description:
         'The currently selected value in the group. Pass undefined when nothing is selected yet.',
+      required: true,
     },
     {
       name: 'onChange',
       type: '(value: string) => void',
       description: 'Callback fired when the selected value changes.',
+      required: true,
     },
     {
       name: 'label',
       type: 'string',
       description:
-        'Accessible name for the group, applied as aria-label so screen readers announce the radios as a named set, e.g. "Sort by". Required. Pass aria-labelledby (via base props) instead when the name already exists as a visible element.',
+        'Accessible name for the group, applied as aria-label so screen readers announce the radios as a named set, e.g. "Sort by". Required even when aria-labelledby (via base props) points to visible text; that visible reference becomes the computed name while label remains the fallback.',
+      required: true,
     },
     {
       name: 'hasCloseOnSelect',
@@ -61,40 +109,47 @@ export const docs = {
       description:
         'Whether selecting a value closes the menu. Radio items default to closing on selection (a single-choice commit).',
     },
+    {
+      name: 'ref',
+      type: 'React.Ref<HTMLDivElement>',
+      description: 'Ref forwarded to the role="group" root.',
+    },
     {
       name: 'children',
       type: 'ReactNode',
       description: 'The DropdownMenuRadioItems that make up the group.',
+      required: true,
     },
   ],
 };
 
 export const docsZh = {
   name: 'DropdownMenuRadioGroup',
-  isHiddenFromOverview: true,
   displayName: 'Dropdown Menu Radio Group',
   description:
-    '单选的单选菜单项组（menuitemradio 的 role="group"）。持有所选值，并以菜单的项间距布局其子项。',
+    'DropdownMenu 中由调用方控制且有名称的单选组（menuitemradio 的 role="group"）。该组负责值传递、关闭策略、根元素组合和菜单项间距；父 DropdownMenu 负责键盘导航。',
   propDescriptions: {
     value: '组中当前选中的值。尚无选中项时传 undefined。',
     onChange: '所选值变化时触发的回调。',
     label:
-      '组的无障碍名称，作为 aria-label 应用，以便屏幕阅读器将单选项作为命名集合朗读，例如“Sort by”。必需。当名称已作为可见元素存在时，可改用 aria-labelledby（通过基础属性）。',
+      '组的无障碍名称，作为 aria-label 应用。即使 aria-labelledby（通过基础属性）指向可见文本，label 仍然必需并作为后备名称。',
     hasCloseOnSelect: '选择某值是否关闭菜单。默认关闭。',
+    ref: '转发到 role="group" 根元素的 ref。',
     children: '组成该组的 DropdownMenuRadioItem。',
   },
 };
 
 export const docsDense = {
   name: 'DropdownMenuRadioGroup',
-  isHiddenFromOverview: true,
   displayName: 'Dropdown Menu Radio Group',
-  description: 'single-select group of menuitemradio; owns selected value',
+  description:
+    'controlled named menuitemradio group; owns value propagation, close policy, root inputs, and item gap',
   propDescriptions: {
     value: 'selected value (undefined = none)',
     onChange: 'fired when selected value changes',
     label: 'accessible group name (applied as aria-label); required',
     hasCloseOnSelect: 'close menu on select (default true)',
+    ref: 'forwarded to the role="group" root',
     children: 'the DropdownMenuRadioItems',
   },
 };

package/src/DropdownMenu/DropdownMenuRadioGroup.spec.md

@@ -0,0 +1,190 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:DropdownMenuRadioGroup
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [public-api, behavior, accessibility, theming, testing]
+verified_by:
+  [
+    packages/core/src/DropdownMenu/DropdownMenuSelectable.test.tsx,
+    packages/core/src/DropdownMenu/DropdownMenu.test.tsx,
+    packages/core/src/DropdownMenu/__tests__/Menu.a11y.test.tsx,
+    apps/storybook/stories/DropdownMenuRadioGroup.stories.tsx,
+    apps/storybook/rtl-audit/verified-not-applicable.json,
+    scripts/check-knowledge.mjs,
+  ]
+modules: []
+families: []
+design_specs: []
+architecture:
+  [
+    architecture:public-component-api,
+    architecture:component-test-sufficiency,
+    architecture:interaction-modality,
+  ]
+contributing: []
+system_specs: [spec:AST-020, spec:AST-029]
+---
+
+# DropdownMenuRadioGroup component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                          |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | One controlled, named single-selection group of `DropdownMenuRadioItem` children with value, change callback, close policy, root inputs, and an explicit React 19 ref.                            |
+| Behavior                | The group supplies selection and close-policy context; radio items emit values; the parent DropdownMenu owns keyboard navigation and menu lifecycle.                                              |
+| End-user impact         | Assistive technology encounters one named group with exactly one current choice when a value matches, while pointer and keyboard selection stay aligned.                                          |
+| Builder impact          | Keep the value controlled, provide a stable accessible label, and place only DropdownMenuRadioItem options inside the group.                                                                      |
+| Compatibility/readiness | Patch-compatible additive `ref` prop on the existing group root. Existing runtime behavior, exports, defaults, and theme surfaces remain unchanged; authority stays `draft` until owner approval. |
+| Review checks           | Reject unnamed groups, local selection state, dropped root inputs, a second keyboard owner, or a close policy that bypasses the controlled callback.                                              |
+| Governing rules         | WAI-ARIA menu pattern; `architecture:public-component-api/INV5–INV9`; `architecture:component-test-sufficiency/INV1–INV7`; `spec:AST-020/FR1,FR2,FR6`.                                            |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+DropdownMenuRadioGroup renders one named `role="group"` wrapper inside the
+pointer presentation of DropdownMenu. It owns controlled selection context,
+close policy, root composition, and the tokenized gap between children.
+DropdownMenuRadioItem owns each `menuitemradio` row and its checked state;
+DropdownMenu owns focus movement, typeahead, keyboard activation, presentation,
+and menu open/close lifecycle.
+
+## Compatibility and migration
+
+- Released default preserved: yes (`hasCloseOnSelect=true`).
+- Compatibility class: additive patch; declares and forwards the React 19 `ref`
+  prop to the existing group root without changing existing behavior.
+- Controlled behavior: `value` is caller-owned and `onChange` is the only commit path.
+- Migration decision: none.
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- One `role="group"` root with an `aria-label` from the required `label` prop.
+- Controlled `value`, `onChange`, and `hasCloseOnSelect` context for radio items.
+- Composition of `children`, supported host inputs, ref, `className`, `style`, and
+  `xstyle` on the group root.
+- Column layout and the semantic menu inter-item gap.
+
+**Does not own / non-goals**
+
+- The `menuitemradio` role, `aria-checked`, disabled behavior, indicator paint,
+  label, description, icon, or end content — owned by DropdownMenuRadioItem.
+- Focus entry, arrow-key navigation, typeahead, Enter/Space synthesis, and menu
+  close implementation — owned by DropdownMenu and shared menu hooks.
+- Touch and bottom-sheet selectable-row rendering — owned by the parent presentation.
+- Uncontrolled selection state or child-value registration.
+
+## Public concepts
+
+| Concept         | Closed values or states                       | Meaning                                                              | Default  | Owner                    | Stability | Invalid-value behavior                                |
+| --------------- | --------------------------------------------- | -------------------------------------------------------------------- | -------- | ------------------------ | --------- | ----------------------------------------------------- |
+| Selection       | matching value; no matching value             | Controls which child reports checked.                                | none     | caller and radio item    | stable    | No match leaves every child unchecked.                |
+| Commit          | child value                                   | Emits the selected child value through `onChange`.                   | required | group context            | stable    | Children outside the group throw from the item owner. |
+| Close policy    | close; remain open                            | Controls whether an item asks DropdownMenu to close after selection. | close    | group context and parent | stable    | Omission closes.                                      |
+| Accessible name | required label; optional labelledby           | Names the group; `aria-labelledby` may point at visible text.        | label    | group root               | stable    | `label` remains required by the public type.          |
+| Root surface    | ref; DOM/data/ARIA; class/style/xstyle/events | Extends the group root while preserving its role and name.           | omitted  | public component API     | stable    | Accepted inputs compose; owned role and label win.    |
+
+## 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 root MUST expose `role="group"` and a non-empty accessible name. The required `label` supplies `aria-label`; caller `aria-labelledby` MAY reference visible text.        | WAI-ARIA menu pattern; released source/docs                 | verify             |
+| FR2 | The group MUST remain controlled. It MUST compare each radio item's value with caller `value` and MUST emit a selected child value only through caller `onChange`.           | Released public API and focused tests                       | verify             |
+| FR3 | `hasCloseOnSelect` MUST default to true. When false, successful selection MUST update through `onChange` while the parent menu remains open.                                 | Released behavior and focused tests                         | verify             |
+| FR4 | DropdownMenu MUST remain the only keyboard owner. The group adds no tab stop, key handler, typeahead, or click synthesis; it only provides context to child rows.            | `architecture:interaction-modality`; parent tests           | verify             |
+| FR5 | Ref, supported host attributes and handlers, `className`, `style`, and `xstyle` MUST reach or compose on the group root without replacing the owned role or `aria-label`.    | `architecture:public-component-api/INV5–INV9`; source/tests | verify             |
+| FR6 | The wrapper MUST remain a logical column whose tokenized gap matches the surrounding menu's item rhythm; it MUST NOT add component-specific directional paint or navigation. | Current source; token and bidirectionality rules            | verify             |
+
+### Allowed variation
+
+- **AV1 — Children.** The number, labels, descriptions, icons, and supporting
+  content of DropdownMenuRadioItem children may vary.
+- **AV2 — Selection.** Any string value, including no matching value, may be
+  caller-controlled without adding local group state.
+- **AV3 — Root styling.** Caller style inputs may extend the wrapper while the
+  role, accessible label, column flow, and child semantics remain intact.
+
+### Representative states
+
+| State             | Required invariant                                                         | Allowed variation                    |
+| ----------------- | -------------------------------------------------------------------------- | ------------------------------------ |
+| Matching value    | Exactly the matching child reports `aria-checked=true`.                    | Child content and menu size.         |
+| No matching value | Every child reports `aria-checked=false`.                                  | Empty or unmatched caller value.     |
+| Default close     | Selection emits the value and closes through the parent.                   | Pointer or synthesized keyboard act. |
+| Retained open     | Selection emits the value, updates controlled state, and leaves menu open. | Result copy and selected child.      |
+| RTL / narrow      | Column order and tokenized gap hold with no horizontal overflow.           | Parent menu placement.               |
+
+### Transformation and precedence order
+
+- **ORD1 — Selection.** Child activation → disabled guard in the item owner →
+  group `onChange(value)` → optional parent close.
+- **ORD2 — Root composition.** Base column/gap → caller `xstyle`; supported host
+  inputs and class/style compose while owned role and label remain fixed.
+
+### Performance and resources
+
+- **PR1 — Context only.** The group memoizes a small context value and owns no
+  Effect, listener, observer, timer, request, DOM read, or resource lifecycle.
+
+## Accessibility contract
+
+- **AR1 — Named group.** The wrapper is one named `group` inside the parent menu.
+- **AR2 — Radio rows.** Child items own `menuitemradio` and `aria-checked`; the
+  group does not add nested native inputs or duplicate row semantics.
+- **AR3 — Keyboard ownership.** DropdownMenu owns focus collection and activation;
+  the group itself never enters the tab or arrow-key sequence.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                               | Representation authority           | Hierarchy role | Component contract |
+| ---------------- | ---------------------------------------------------------------- | ---------------------------------- | -------------- | ------------------ |
+| Group wrapper    | Logical column with the menu's semantic inter-item gap.          | Current source and spacing tokens  | structural     | FR1, FR5, FR6      |
+| Selected child   | One child reflects caller value through `aria-checked`.          | DropdownMenuRadioItem              | prominent      | FR2, AR2           |
+| Direction/narrow | Child order and gap hold without physical-direction assumptions. | Bidirectionality and parent layout | structural     | FR6                |
+
+No new component-local visual decision is settled by this draft.
+
+## Family and system relationships
+
+- `architecture:public-component-api` owns root input composition and released compatibility.
+- `architecture:component-test-sufficiency` owns proportionate observable evidence.
+- `architecture:interaction-modality` and DropdownMenu own keyboard behavior.
+- `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–FR4, AR1–3 | `DropdownMenuSelectable.test.tsx`; reusable Menu contracts; scoped axe         | matching, none, close, retained-open | An unnamed group, wrong checked row, skipped callback, unwanted close, or key owner fails | `audit:DropdownMenuRadioGroup/§1,§4,§6`     |
+| FR5            | root/ref/handler tests; lint and typecheck                                     | ref, host attributes, class/style    | An accepted input is dropped or overrides the owned role/name                             | `audit:DropdownMenuRadioGroup/§3`           |
+| FR6            | source-hashed RTL N/A receipt plus exact-head Neutral/Butter/RTL/narrow frames | LTR, RTL, 320px, light/dark          | Physical direction, lost tokenized gap, collapsed geometry, or horizontal overflow fails  | `audit:DropdownMenuRadioGroup/§2,§5,§9,§10` |
+
+## Decision log
+
+None. This draft records current facts and introduces no product decision.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables/examples, current audit scores,
+screenshot matrices, implementation steps, or parent/item contracts. The audit
+pull request owns the closed run evidence required by `spec:AST-029/FR5`.

package/src/DropdownMenu/DropdownMenuRadioGroup.tsx

@@ -14,7 +14,7 @@
  * menuitemradio rows.
  */
 
-import {useMemo, type ReactNode} from 'react';
+import {useMemo, type ReactNode, type Ref} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {spacingVars} from '../theme/tokens.stylex';
 import {mergeProps} from '../utils';
@@ -51,9 +51,9 @@ export interface DropdownMenuRadioGroupProps extends Omit<
   /**
    * Accessible name for the group, announced by screen readers so the radios
    * read as a named set (e.g. "Sort by"). Applied as the group's `aria-label`.
-   * Required -- an unnamed radio group is an accessibility defect. Pass
-   * `aria-labelledby` (via base props) instead if the name already exists as a
-   * visible element on the page.
+   * Required even when `aria-labelledby` (via base props) points to visible
+   * text; that visible reference becomes the computed name while `label`
+   * remains the fallback.
    */
   label: string;
   /**
@@ -63,6 +63,10 @@ export interface DropdownMenuRadioGroupProps extends Omit<
    * @default true
    */
   hasCloseOnSelect?: boolean;
+  /**
+   * Ref forwarded to the role="group" root.
+   */
+  ref?: Ref<HTMLDivElement>;
   /**
    * The `DropdownMenuRadioItem`s that make up the group.
    */
@@ -92,6 +96,7 @@ export function DropdownMenuRadioGroup({
   label,
   hasCloseOnSelect = true,
   children,
+  ref,
   xstyle,
   className,
   style,
@@ -105,6 +110,7 @@ export function DropdownMenuRadioGroup({
   return (
     <div
       {...rest}
+      ref={ref}
       role="group"
       aria-label={label}
       {...mergeProps(stylex.props(styles.group, xstyle), {className, style})}>

package/src/DropdownMenu/DropdownMenuSelectable.test.tsx

@@ -9,6 +9,7 @@
  *   outcomes live in their reusable contracts; Menu retains navigation.
  */
 
+import {useState} from 'react';
 import {describe, it, expect, vi, beforeEach} from 'vitest';
 import {render, screen, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
@@ -328,6 +329,98 @@ describe('DropdownMenuRadioGroup / RadioItem', () => {
       screen.getByRole('menuitemradio', {name: 'Oldest', hidden: true}),
     );
     expect(onChange).toHaveBeenCalledWith('oldest');
+    expect(
+      screen.getByRole('menuitemradio', {name: 'Newest', hidden: true}),
+    ).toHaveAttribute('aria-checked', 'true');
+    expect(
+      screen.getByRole('menuitemradio', {name: 'Oldest', hidden: true}),
+    ).toHaveAttribute('aria-checked', 'false');
+    expect(HTMLElement.prototype.hidePopover).toHaveBeenCalledTimes(1);
+  });
+
+  it('keeps the menu open while controlled selection updates when requested', async () => {
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+
+    function ControlledGroup() {
+      const [value, setValue] = useState('newest');
+      return (
+        <DropdownMenu button={{label: 'Sort'}}>
+          <DropdownMenuRadioGroup
+            value={value}
+            onChange={nextValue => {
+              onChange(nextValue);
+              setValue(nextValue);
+            }}
+            label="Sort by"
+            hasCloseOnSelect={false}>
+            <DropdownMenuRadioItem value="newest" label="Newest" />
+            <DropdownMenuRadioItem value="oldest" label="Oldest" />
+          </DropdownMenuRadioGroup>
+        </DropdownMenu>
+      );
+    }
+
+    render(<ControlledGroup />);
+    await user.click(screen.getByRole('button', {name: /Sort/}));
+    const oldest = screen.getByRole('menuitemradio', {
+      name: 'Oldest',
+      hidden: true,
+    });
+    await user.click(oldest);
+
+    expect(onChange).toHaveBeenCalledWith('oldest');
+    expect(oldest).toHaveAttribute('aria-checked', 'true');
+    expect(HTMLElement.prototype.hidePopover).not.toHaveBeenCalled();
+  });
+
+  it('names and composes the group root when no value matches', async () => {
+    const user = userEvent.setup();
+    const ref = vi.fn();
+    const onClick = vi.fn();
+    render(
+      <>
+        <span id="sort-label">Visible sort label</span>
+        <DropdownMenu button={{label: 'Sort'}}>
+          <DropdownMenuRadioGroup
+            ref={ref}
+            role="tree"
+            aria-label="Consumer label"
+            aria-labelledby="sort-label"
+            data-owner="consumer"
+            className="consumer-group"
+            style={{inlineSize: 240}}
+            onClick={onClick}
+            value={undefined}
+            onChange={() => {}}
+            label="Sort fallback">
+            <DropdownMenuRadioItem value="newest" label="Newest" />
+            <DropdownMenuRadioItem value="oldest" label="Oldest" />
+          </DropdownMenuRadioGroup>
+        </DropdownMenu>
+      </>,
+    );
+    await user.click(screen.getByRole('button', {name: /Sort/}));
+
+    const group = screen.getByRole('group', {
+      name: 'Visible sort label',
+      hidden: true,
+    });
+    expect(group).toHaveAttribute('role', 'group');
+    expect(group).toHaveAttribute('aria-label', 'Sort fallback');
+    expect(group).toHaveAttribute('aria-labelledby', 'sort-label');
+    expect(group).toHaveAttribute('data-owner', 'consumer');
+    expect(group).toHaveClass('consumer-group');
+    expect(group).toHaveStyle({inlineSize: '240px'});
+    expect(ref).toHaveBeenCalledWith(group);
+    expect(
+      screen
+        .getAllByRole('menuitemradio', {hidden: true})
+        .every(item => item.getAttribute('aria-checked') === 'false'),
+    ).toBe(true);
+
+    fireEvent.click(group);
+    expect(onClick).toHaveBeenCalledTimes(1);
   });
 
   it('throws when a radio item is used outside a group', () => {

package/src/DropdownMenu/__tests__/DropdownMenuRadioGroupAudit.a11y.chromium.spec.ts

@@ -0,0 +1,327 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file DropdownMenuRadioGroupAudit.a11y.chromium.spec.ts
+ * @input Exact-head DropdownMenuRadioGroup story across themes, modes, direction, and viewport widths
+ * @output Screenshots and fail-closed sensor receipts for the DropdownMenuRadioGroup component audit
+ * @position Component-owned Night Watch browser evidence; CI runs it only for a DropdownMenuRadioGroup audit pull request
+ */
+
+import {createHash} from 'node:crypto';
+import {execFileSync} from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {expect, test, type Page} from '@playwright/test';
+import {holdMotionStill} from '@astryxdesign/a11y-spec/chromium';
+import {
+  DEFAULT_STORYBOOK_DIR,
+  serveStorybook,
+  type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+
+const OUTPUT = path.resolve('dropdown-menu-radio-group-audit-evidence');
+const STORY_ID = 'core-dropdownmenuradiogroup--controlled-selection';
+const WIDE = {width: 1024, height: 768};
+const NARROW = {width: 320, height: 720};
+
+type Mode = 'light' | 'dark';
+type Direction = 'ltr' | 'rtl';
+type Theme = 'neutral' | 'butter';
+type AuditCase = {
+  key: string;
+  mode: Mode;
+  direction: Direction;
+  theme: Theme;
+  viewport: {width: number; height: number};
+};
+
+const cases: AuditCase[] = [
+  {
+    key: 'neutral-light',
+    mode: 'light',
+    direction: 'ltr',
+    theme: 'neutral',
+    viewport: WIDE,
+  },
+  {
+    key: 'neutral-dark',
+    mode: 'dark',
+    direction: 'ltr',
+    theme: 'neutral',
+    viewport: WIDE,
+  },
+  {
+    key: 'butter-light',
+    mode: 'light',
+    direction: 'ltr',
+    theme: 'butter',
+    viewport: WIDE,
+  },
+  {
+    key: 'butter-dark',
+    mode: 'dark',
+    direction: 'ltr',
+    theme: 'butter',
+    viewport: WIDE,
+  },
+  {
+    key: 'rtl-light',
+    mode: 'light',
+    direction: 'rtl',
+    theme: 'neutral',
+    viewport: WIDE,
+  },
+  {
+    key: 'rtl-dark',
+    mode: 'dark',
+    direction: 'rtl',
+    theme: 'neutral',
+    viewport: WIDE,
+  },
+  {
+    key: 'narrow-light',
+    mode: 'light',
+    direction: 'ltr',
+    theme: 'neutral',
+    viewport: NARROW,
+  },
+  {
+    key: 'narrow-dark',
+    mode: 'dark',
+    direction: 'ltr',
+    theme: 'neutral',
+    viewport: NARROW,
+  },
+];
+
+test.describe.configure({mode: 'serial', retries: 0});
+let server: StaticServer;
+let checkoutSha: string;
+let storybookSha: string;
+
+function storyUrl(item: AuditCase) {
+  return `${server.origin}/iframe.html?id=${STORY_ID}&viewMode=story&globals=colorMode:${item.mode};astryxTheme:${item.theme};direction:${item.direction}`;
+}
+
+async function settle(page: Page) {
+  await holdMotionStill(page);
+  await page.evaluate(async () => document.fonts.ready);
+  await page.waitForTimeout(40);
+}
+
+test.beforeAll(async () => {
+  fs.rmSync(OUTPUT, {recursive: true, force: true});
+  fs.mkdirSync(OUTPUT, {recursive: true});
+  checkoutSha = execFileSync('git', ['rev-parse', 'HEAD'], {
+    encoding: 'utf8',
+  }).trim();
+  const expected = process.env.ASTRYX_HEAD_SHA;
+  if (expected && expected !== checkoutSha) {
+    throw new Error(
+      `checkout ${checkoutSha} does not match expected head ${expected}`,
+    );
+  }
+  server = await serveStorybook(
+    process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+  );
+  const response = await fetch(`${server.origin}/astryx-build-sha.txt`);
+  if (!response.ok) {
+    throw new Error(`Storybook build has no SHA stamp (${response.status})`);
+  }
+  storybookSha = (await response.text()).trim();
+  if (storybookSha !== checkoutSha) {
+    throw new Error(
+      `Storybook ${storybookSha} does not match checkout ${checkoutSha}`,
+    );
+  }
+});
+
+test.afterAll(async () => {
+  await server?.close();
+});
+
+for (const item of cases) {
+  test(item.key, async ({browser}) => {
+    const context = await browser.newContext({
+      viewport: item.viewport,
+      colorScheme: item.mode,
+      reducedMotion: 'reduce',
+    });
+    const page = await context.newPage();
+    const pageErrors: string[] = [];
+    page.on('pageerror', error => pageErrors.push(String(error)));
+    await page.goto(storyUrl(item), {waitUntil: 'load'});
+    await page.locator('#storybook-root').waitFor();
+
+    const fixture = page.getByTestId('dropdown-menu-radio-group-audit');
+    const menu = page.getByRole('menu').last();
+    const group = menu.getByRole('group', {name: 'Sort options'});
+    await expect(group).toBeVisible();
+    const radios = group.getByRole('menuitemradio');
+    await expect(radios).toHaveCount(3);
+    await expect(fixture).toHaveAttribute('data-close-request-count', '0');
+    await expect(radios.first()).toHaveAttribute('aria-checked', 'true');
+    await radios.nth(1).click();
+    await expect(radios.nth(1)).toHaveAttribute('aria-checked', 'true');
+    await expect(fixture).toHaveAttribute('data-close-request-count', '0');
+    await expect(menu).toBeVisible();
+    await settle(page);
+
+    const observed = await group.evaluate(element => {
+      const currentRadios = Array.from(
+        element.querySelectorAll<HTMLElement>('[role="menuitemradio"]'),
+      );
+      const groupStyle = getComputedStyle(element);
+      const groupBox = element.getBoundingClientRect();
+      const currentMenu = element.closest<HTMLElement>('[role="menu"]');
+      const rows = currentRadios.map(row => {
+        const box = row.getBoundingClientRect();
+        const style = getComputedStyle(row);
+        const indicator = row.querySelector<HTMLElement>(
+          '.astryx-dropdown-menu-radio',
+        );
+        const indicatorBox = indicator?.getBoundingClientRect() ?? null;
+        return {
+          role: row.getAttribute('role'),
+          checked: row.getAttribute('aria-checked'),
+          text: row.textContent?.replace(/\s+/g, ' ').trim() ?? null,
+          color: style.color,
+          geometry: {x: box.x, y: box.y, width: box.width, height: box.height},
+          indicator:
+            indicatorBox === null
+              ? null
+              : {width: indicatorBox.width, height: indicatorBox.height},
+        };
+      });
+      return {
+        theme: document
+          .querySelector('[data-astryx-theme]')
+          ?.getAttribute('data-astryx-theme'),
+        mode: document.documentElement.getAttribute('data-theme'),
+        direction: groupStyle.direction,
+        viewport: {width: innerWidth, height: innerHeight},
+        reducedMotion: matchMedia('(prefers-reduced-motion: reduce)').matches,
+        closeRequestCount:
+          element
+            .closest('[data-close-request-count]')
+            ?.getAttribute('data-close-request-count') ?? null,
+        horizontalOverflow:
+          document.documentElement.scrollWidth > innerWidth + 1,
+        fonts: document.fonts.status,
+        group: {
+          role: element.getAttribute('role'),
+          ariaLabel: element.getAttribute('aria-label'),
+          display: groupStyle.display,
+          flexDirection: groupStyle.flexDirection,
+          rowGap: groupStyle.rowGap,
+          menuRowGap:
+            currentMenu === null ? null : getComputedStyle(currentMenu).rowGap,
+          geometry: {
+            x: groupBox.x,
+            y: groupBox.y,
+            width: groupBox.width,
+            height: groupBox.height,
+          },
+        },
+        rows,
+      };
+    });
+
+    const semanticsPass =
+      observed.group.role === 'group' &&
+      observed.group.ariaLabel === 'Sort options' &&
+      observed.rows.length === 3 &&
+      observed.rows.every(row => row.role === 'menuitemradio') &&
+      observed.rows.filter(row => row.checked === 'true').length === 1 &&
+      observed.rows[1]?.checked === 'true' &&
+      observed.rows[1]?.text?.includes('Oldest first') === true &&
+      observed.closeRequestCount === '0';
+    const layoutPass =
+      observed.group.display === 'flex' &&
+      observed.group.flexDirection === 'column' &&
+      observed.group.menuRowGap !== null &&
+      observed.group.rowGap === observed.group.menuRowGap &&
+      Number.parseFloat(observed.group.rowGap) > 0 &&
+      observed.group.geometry.width > 0 &&
+      observed.group.geometry.height > 0 &&
+      observed.rows.every(
+        row => row.geometry.width > 0 && row.geometry.height > 0,
+      ) &&
+      (observed.rows[1]?.geometry.y ?? 0) >
+        (observed.rows[0]?.geometry.y ?? Number.POSITIVE_INFINITY);
+    const paintPass = observed.rows.every(
+      row =>
+        row.color !== 'rgba(0, 0, 0, 0)' &&
+        row.indicator !== null &&
+        row.indicator.width > 0 &&
+        row.indicator.height > 0,
+    );
+
+    const png = await page.screenshot({animations: 'disabled', fullPage: true});
+    const image = `${item.key}.png`;
+    const receipt = {
+      schemaVersion: 1,
+      expected: {
+        build: checkoutSha,
+        storyId: STORY_ID,
+        mode: item.mode,
+        direction: item.direction,
+        theme: item.theme,
+        viewport: item.viewport,
+      },
+      observed: {build: storybookSha, ...observed, pageErrors},
+      image: {
+        file: image,
+        sha256: createHash('sha256').update(png).digest('hex'),
+        width: png.readUInt32BE(16),
+        height: png.readUInt32BE(20),
+      },
+      checks: {semanticsPass, layoutPass, paintPass},
+      passed:
+        storybookSha === checkoutSha &&
+        pageErrors.length === 0 &&
+        observed.theme === item.theme &&
+        observed.mode === item.mode &&
+        observed.direction === item.direction &&
+        observed.viewport.width === item.viewport.width &&
+        observed.viewport.height === item.viewport.height &&
+        observed.reducedMotion &&
+        !observed.horizontalOverflow &&
+        observed.fonts === 'loaded' &&
+        semanticsPass &&
+        layoutPass &&
+        paintPass,
+    };
+    fs.writeFileSync(path.join(OUTPUT, image), png);
+    fs.writeFileSync(
+      path.join(OUTPUT, `${item.key}.sensors.json`),
+      `${JSON.stringify(receipt, null, 2)}\n`,
+    );
+    expect(receipt.passed).toBe(true);
+    await context.close();
+  });
+}
+
+test('manifest is complete', () => {
+  const receipts = fs
+    .readdirSync(OUTPUT)
+    .filter(file => file.endsWith('.sensors.json'));
+  fs.writeFileSync(
+    path.join(OUTPUT, 'manifest.json'),
+    `${JSON.stringify(
+      {
+        schemaVersion: 1,
+        component: 'core/DropdownMenuRadioGroup',
+        build: checkoutSha,
+        frames: cases.map(item => ({
+          key: item.key,
+          image: `${item.key}.png`,
+          receipt: `${item.key}.sensors.json`,
+        })),
+      },
+      null,
+      2,
+    )}\n`,
+  );
+  expect(receipts).toHaveLength(cases.length);
+});

package/src/FieldStatus/FieldStatus.spec.md

@@ -130,9 +130,9 @@ intentional decision.
   region, including on first mount and when message or type changes, without
   moving focus. Inside a mounted live container, `spec:AST-086` FR4 applies.
 - **AR5 — Assistive-technology output.** Claims about whether, when, or how the
-  message is spoken or presented in braille MUST be verified through the real-AT
-  evidence process in `spec:AST-009`; DOM and accessibility-tree checks prove
-  only programmatic exposure and routing.
+  message is spoken or presented in braille are recommended real-AT follow-up
+  under `spec:AST-009`, not a merge or release requirement; DOM and
+  accessibility-tree checks prove programmatic exposure and routing.
 - **AR2 — Visible description.** The rendered message box MUST remain available
   to assistive technology for `aria-describedby` association and MUST NOT become
   its own newly mounted live region.
@@ -182,7 +182,7 @@ change either presentation.
 | FR5, FR6            | `FieldStatus.test.tsx` forwarding and update suites                     | Initial render and rerender                                   | Breaking the released root or update behavior fails compatibility assertions.                                                         | `audit:FieldStatus/behavior`      |
 | AR1                 | `StatusMessage.a11y.test.tsx` and `StatusMessage.a11y.chromium.spec.ts` | Error, warning, and success; post-mount message replacement   | Removing the persistent channel, changing its role/urgency, or dropping a post-mount update fails the shared status-message contract. | `audit:FieldStatus/accessibility` |
 | AR1                 | `FieldStatus.test.tsx` channel-routing suite                            | First non-empty mount; same-instance message and type changes | Breaking FieldStatus's first-use hook call or severity rerouting fails component-specific assertions.                                 | `audit:FieldStatus/accessibility` |
-| AR5                 | Pending/unverified real-AT evidence governed by `spec:AST-009`          | First mount; message replacement; type/urgency change         | Spoken and braille output remain unverified until a durable named AT/browser receipt exists.                                          | `audit:FieldStatus/accessibility` |
+| AR5                 | Recommended real-AT follow-up under `spec:AST-009`                      | First mount; message replacement; type/urgency change         | Spoken and braille output stay unverified until a real-AT receipt exists; this does not block merge or release.                       | `audit:FieldStatus/accessibility` |
 | AR2                 | `FieldStatus.test.tsx`                                                  | Attached/detached visible message and empty message           | The visible description becomes a second live region or is hidden from assistive technology.                                          | `audit:FieldStatus/accessibility` |
 | Theming anatomy map | `scripts/check-knowledge.mjs`                                           | Consumer anatomy and current targets                          | Missing, extra, duplicated, prefixed, or stale mappings fail repository validation.                                                   | `audit:FieldStatus/theming`       |
 

package/src/Markdown/Markdown.helpers.perf.test.ts

@@ -357,17 +357,17 @@ describe('Markdown helper performance', () => {
         }),
       ];
 
-      // Timed on the transform stage alone and compared at the FASTEST
-      // sample of each side: this is a few hundred microseconds against a
-      // parse of milliseconds, so measuring the whole parse buries it, and
-      // a minimum is the least-disturbed sample each side achieved.
+      // Timed on the transform stage alone: this is a few hundred
+      // microseconds against a parse of milliseconds, so measuring the whole
+      // parse buries it. Each side is compared at its FASTEST sample, the
+      // least-disturbed run it achieved, and the two sides alternate sample by
+      // sample so a slow stretch of the machine reaches both instead of one.
       const root = parseMarkdownAst(source);
-      const fastestTransform = (
+      const transformOnly = (
         plugins: ReadonlyArray<ReturnType<typeof createMarkdownPlugin>>,
-      ): number => {
+      ) => {
         const prepared = prepareMarkdownPlugins(plugins);
-        let fastest = Number.POSITIVE_INFINITY;
-        for (let sample = 0; sample < 60; sample++) {
+        return () => {
           const start = performance.now();
           benchmarkSink ^= applyMarkdownTransforms(
             root,
@@ -376,18 +376,24 @@ describe('Markdown helper performance', () => {
             true,
             'block',
           ).children.length;
-          fastest = Math.min(fastest, performance.now() - start);
-        }
-        void benchmarkSink;
-        return fastest;
+          return performance.now() - start;
+        };
       };
-
-      const single = plugin('scale-single', gaps);
-      const double = plugin('scale-double', doubled);
-      // Warm both before either is recorded.
-      fastestTransform(single);
-      fastestTransform(double);
-      const ratio = fastestTransform(double) / fastestTransform(single);
+      const single = transformOnly(plugin('scale-single', gaps));
+      const double = transformOnly(plugin('scale-double', doubled));
+      let fastestSingle = Number.POSITIVE_INFINITY;
+      let fastestDouble = Number.POSITIVE_INFINITY;
+      for (let sample = 0; sample < 80; sample++) {
+        // The first rounds only warm both sides.
+        const singleTime = single();
+        const doubleTime = double();
+        if (sample >= 20) {
+          fastestSingle = Math.min(fastestSingle, singleTime);
+          fastestDouble = Math.min(fastestDouble, doubleTime);
+        }
+      }
+      void benchmarkSink;
+      const ratio = fastestDouble / fastestSingle;
       console.log(
         `  ${sections} sections, ${doubled.length} ranges over ${gaps.length}: ${ratio.toFixed(3)}`,
       );

package/src/Table/plugins/columnResize/useTableColumnResize.spec.md

@@ -227,17 +227,17 @@ without a target of its own.
 
 ## Verification map
 
-| Contract           | Verification                                                                                                   | Representative states                                                                                            | Mutation or failure expectation                                                                                                                                                           |
-| ------------------ | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| FR1, FR6           | `useTableColumnResize.test.tsx` boundary-presence cases plus hover-capability and coarse-primary cases         | Resizable, opted-out, and generated columns; hover-capable, coarse-primary with keyboard, and coarse-only inputs | A boundary appears on a non-resizable column, disappears from a resizable one, the hover reveal fires where no pointer can hover, or the control is absent where an input can operate it. |
-| FR2                | Browser measurement of scroll-region vertical overflow with the plugin enabled                                 | Short and tall tables, wrapped and single-line headers, dense and default                                        | The indicator ends below the last row or the scroll region gains vertical scroll that the same table lacks without resize.                                                                |
-| FR3-FR5, FR9, ORD1 | New focused tests for resting, header-hovered, pointer-on-boundary, focused, and dragging states               | Rest, header hover, hover plus pointer on one boundary, keyboard focus with no pointer in the row, drag          | A resting header draws boundaries, header hover misses a boundary, the pointed/focused boundary fails to outrank the hint, or focus alone draws a neighbor.                               |
-| FR10, ORD0         | Scroll-gate test driving the scroll region with a stationary pointer over the header                           | Pointer resting over a header while the region scrolls and after it settles                                      | Boundaries reveal mid-scroll, an existing hint survives the scroll, or disclosure fails to resume once scrolling stops.                                                                   |
-| FR7                | Snapshot or assertion that header hover changes no other header or row treatment                               | Header hover over a sortable and a selectable header                                                             | Header hover changes background, label, cursor, width, or another control's state.                                                                                                        |
-| FR8, AR1-AR3, AR6  | Existing keyboard and ARIA suites, a coarse-primary keyboard case, plus assistive-technology spot check        | Tab to boundary, arrow resize, screen-reader navigation of the header, coarse-primary device with a keyboard     | The boundary leaves tab order on any input that can operate it, loses its name or values, or the hint reaches the accessibility tree.                                                     |
-| PR1, PR2           | Render-count assertion around header pointer enter/leave and during a scroll; listener and observer inspection | Pointer enters and leaves the header repeatedly; the region scrolls under a resting pointer                      | Disclosure rerenders the Table, the scroll gate sets React state, more than one scroll listener or any timer is added, or the extent measurement observes what it resizes.                |
-| Plugin composition | Test mounting the resize and sticky-columns plugins together in both insertion orders                          | Pinned start column with resize enabled, before and after a drag                                                 | A pinned column loses `position: sticky` in either order, or the composition depends on caller insertion order.                                                                           |
-| Record shape       | `scripts/check-knowledge.mjs`                                                                                  | Colocated module record, canonical id and filename, parent backlink                                              | A missing, misnamed, mis-parented, or unlinked record passes validation.                                                                                                                  |
+| Contract           | Verification                                                                                                                      | Representative states                                                                                            | Mutation or failure expectation                                                                                                                                                           |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| FR1, FR6           | `useTableColumnResize.test.tsx` boundary-presence cases plus hover-capability and coarse-primary cases                            | Resizable, opted-out, and generated columns; hover-capable, coarse-primary with keyboard, and coarse-only inputs | A boundary appears on a non-resizable column, disappears from a resizable one, the hover reveal fires where no pointer can hover, or the control is absent where an input can operate it. |
+| FR2                | Browser measurement of scroll-region vertical overflow with the plugin enabled                                                    | Short and tall tables, wrapped and single-line headers, dense and default                                        | The indicator ends below the last row or the scroll region gains vertical scroll that the same table lacks without resize.                                                                |
+| FR3-FR5, FR9, ORD1 | New focused tests for resting, header-hovered, pointer-on-boundary, focused, and dragging states                                  | Rest, header hover, hover plus pointer on one boundary, keyboard focus with no pointer in the row, drag          | A resting header draws boundaries, header hover misses a boundary, the pointed/focused boundary fails to outrank the hint, or focus alone draws a neighbor.                               |
+| FR10, ORD0         | Scroll-gate test driving the scroll region with a stationary pointer over the header                                              | Pointer resting over a header while the region scrolls and after it settles                                      | Boundaries reveal mid-scroll, an existing hint survives the scroll, or disclosure fails to resume once scrolling stops.                                                                   |
+| FR7                | Snapshot or assertion that header hover changes no other header or row treatment                                                  | Header hover over a sortable and a selectable header                                                             | Header hover changes background, label, cursor, width, or another control's state.                                                                                                        |
+| FR8, AR1-AR3, AR6  | Existing keyboard and ARIA suites and a coarse-primary keyboard case; an assistive-technology spot check is recommended follow-up | Tab to boundary, arrow resize, screen-reader navigation of the header, coarse-primary device with a keyboard     | The boundary leaves tab order on any input that can operate it, loses its name or values, or the hint reaches the accessibility tree.                                                     |
+| PR1, PR2           | Render-count assertion around header pointer enter/leave and during a scroll; listener and observer inspection                    | Pointer enters and leaves the header repeatedly; the region scrolls under a resting pointer                      | Disclosure rerenders the Table, the scroll gate sets React state, more than one scroll listener or any timer is added, or the extent measurement observes what it resizes.                |
+| Plugin composition | Test mounting the resize and sticky-columns plugins together in both insertion orders                                             | Pinned start column with resize enabled, before and after a drag                                                 | A pinned column loses `position: sticky` in either order, or the composition depends on caller insertion order.                                                                           |
+| Record shape       | `scripts/check-knowledge.mjs`                                                                                                     | Colocated module record, canonical id and filename, parent backlink                                              | A missing, misnamed, mis-parented, or unlinked record passes validation.                                                                                                                  |
 
 Browser, render-count, and assistive-technology evidence are pending. Passing this
 specification pull request proves record integrity only.

package/src/Table/plugins/rowStatus/useTableRowStatus.spec.md

@@ -214,8 +214,9 @@ add semantic/custom cases to representative Table render and no-op update budget
 - **AR5 — Supplemental tooltip.** Tooltip may repeat `label` as pointer help, but
   the indicator's accessible name MUST remain sufficient without opening it. The
   current indicator is not focusable, so tooltip presence is not keyboard evidence.
-- **AR6 — Row context.** Assistive-technology verification MUST confirm the named
-  status is encountered in its row context without duplicate announcements.
+- **AR6 — Row context.** The named status is exposed in its row context without a
+  duplicate name, proved at the accessibility tree. Assistive-technology
+  observation of the announcement is recommended follow-up under `spec:AST-009`.
 
 ## Design relationships
 
@@ -259,7 +260,7 @@ own AST-002 review and synchronized consumer anatomy.
 | FR3, FR4, FR6            | Add public-subpath compile fixtures for the unchanged interface, declaration merging and extension, semantic interface, callback union, missing labels, unknown statuses, and forbidden mixtures. | Stable custom annotations/extensions; all semantic statuses.                           | `TableRowStatus` changes or stops merging, semantic usage is inaccessible, or supported status mixes with custom fields.                                           |
 | FR3-FR5                  | Extend row-status runtime tests with semantic-looking custom colors, raw/palette dots, explicit custom icons, all semantic statuses, and active-theme substitution.                               | Custom dot, custom icon, and three semantic outcomes.                                  | Custom color selects an implicit glyph, semantic status bypasses shared resolution, or variant becomes caller/theme input.                                         |
 | FR7, ORD2-ORD4, PR4      | Runtime tests under development and production modes with repeated mixed objects, rows, and renders.                                                                                              | `status + color`, `status + icon`, and all three fields.                               | Custom input overrides supported status, forbidden fields affect output, production warns, or development warns more than once per loaded module instance.         |
-| AR1-AR6                  | Existing role/name tests plus browser axe, forced-colors, tooltip modality, and VoiceOver table-navigation evidence.                                                                              | Semantic glyphs, custom icon, custom dot, `null`, light/dark, and every shipped theme. | Header or indicator loses its name, nested glyph is announced twice, glyph distinctions disappear, tooltip becomes sole meaning, or row context duplicates status. |
+| AR1-AR6                  | Existing role/name tests plus browser axe, forced-colors, tooltip modality, and accessibility-tree row-context evidence; VoiceOver table navigation is recommended follow-up.                     | Semantic glyphs, custom icon, custom dot, `null`, light/dark, and every shipped theme. | Header or indicator loses its name, nested glyph is announced twice, glyph distinctions disappear, tooltip becomes sole meaning, or row context duplicates status. |
 | PR1-PR3                  | Extend `Table.perf.test.tsx` with semantic/custom initial render and no-op update cases.                                                                                                          | Stable rerender, mixed rows, and theme substitution.                                   | Resolution adds measurement/resources, creates a parallel registry, or exceeds existing representative Table budgets.                                              |
 | Structural ownership     | `scripts/check-knowledge.mjs`.                                                                                                                                                                    | Colocated module, canonical filename/id, and parent backlink.                          | A missing, duplicate, orphaned, mis-parented, misnamed, or undiscovered record passes validation.                                                                  |
 | Public hygiene and scope | Prettier, `check:knowledge`, checker tests, `check:repo`, changed-file scan, and public-content scan.                                                                                             | Parent backlink plus one module specification; no Changeset.                           | Runtime/docs files, private context, invalid record shape, or unrelated changes enter this contract proposal.                                                      |