@astryxdesign/core 0.7.4 → 0.7.5-canary.0418c47

package/src/Divider/Divider.spec.md

@@ -3,15 +3,16 @@ schema_version: 3
 template_version: 7
 kind: component
 id: component:Divider
-authority: draft
+authority: current
 archive_reason: null
 superseded_by: null
-approved_by: null
-approved_at: null
+approved_by: cixzhang
+approved_at: 2026-10-27
 owners: [cixzhang]
 review_triggers: [public-api, behavior, layout, theming, accessibility, testing]
 verified_by:
   [
+    .github/visual-baseline/manifest.json,
     packages/core/src/Divider/Divider.test.tsx,
     packages/core/src/theme/themingTargets.test.ts,
     apps/storybook/stories/Divider.stories.tsx,
@@ -27,22 +28,22 @@ architecture:
     architecture:component-test-sufficiency,
   ]
 contributing: []
-system_specs: [spec:AST-020, spec:AST-029]
+system_specs: [spec:AST-009, spec:AST-020]
 ---
 
 # Divider component contract
 
 ## Contract at a glance
 
-| Area                    | Contract                                                                                                                                                                                                                      |
-| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | `orientation`, `label`, theme-extensible `variant`, `isFullBleed`, `BaseProps<HTMLDivElement>`, and a root `ref`.                                                                                                             |
-| Behavior                | The separator renders one rule without a label and two rules around a renderable label; full bleed consumes inherited logical container inset. The theme-extensible variant axis has no settled no-match line-paint fallback. |
-| End-user impact         | People can perceive a named separator across horizontal, vertical, labelled, full-bleed, narrow, and RTL compositions. A custom theme variant can still lose its line paint; OQ2 records that retained gap.                   |
-| Builder impact          | No new caller choice. Numeric zero remains a valid label; booleans and empty strings leave one continuous unnamed rule.                                                                                                       |
-| Compatibility/readiness | Patch-compatible observational contract. Public props, defaults, target names, and built-in appearances remain unchanged; authority stays `draft` until exact-head owner approval.                                            |
-| Review checks           | Reject missing numeric labels, physical-edge bleed, dropped root inputs, or a target/axis that disagrees with the rendered separator. Keep the custom-variant paint gap unresolved until OQ2 is settled.                      |
-| Governing rules         | `architecture:public-component-api/INV1,INV5–INV9`; `architecture:component-theming-surface/INV3–INV7,INV14`; `architecture:container-padding/INV1,INV3,INV7–INV10`; WCAG 2.2 SC 1.3.1 and 4.1.2 through `spec:AST-020/FR1`.  |
+| Area                    | Contract                                                                                                                                                                                                                     |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | `orientation`, `label`, theme-extensible `variant`, `isFullBleed`, `BaseProps<HTMLDivElement>`, and a root `ref`.                                                                                                            |
+| Behavior                | The separator renders one rule without a label and two rules around a renderable label; full bleed consumes inherited logical container inset.                                                                               |
+| End-user impact         | People perceive a named separator across horizontal, vertical, labelled, full-bleed, narrow, and RTL compositions.                                                                                                           |
+| Builder impact          | None; the record describes shipped behavior. Numeric zero is a valid label; booleans and empty strings leave one continuous unnamed rule.                                                                                    |
+| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. Two implementation gaps are listed under Current-state impact.                                                                                    |
+| Review checks           | Reject missing numeric labels, physical-edge bleed, dropped root inputs, or a target or axis that disagrees with the rendered separator.                                                                                     |
+| Governing rules         | `architecture:public-component-api/INV1,INV5–INV9`; `architecture:component-theming-surface/INV3–INV7,INV14`; `architecture:container-padding/INV1,INV3,INV7–INV10`; WCAG 2.2 SC 1.3.1 and 4.1.2 through `spec:AST-020/FR1`. |
 
 This table is a review projection; the body below is authoritative.
 
@@ -59,7 +60,8 @@ Consumer syntax and examples belong in `Divider.doc.mjs`.
 
 - Released default preserved: yes — horizontal, subtle, unlabelled, and not full
   bleed.
-- Compatibility class: patch fix. ReactNode values that React renders, including
+- Compatibility class: records shipped behavior; no public prop, default, DOM,
+  or styling output changes. ReactNode values that React renders, including
   numeric zero, stay inside the label wrapper; skipped scalar labels leave one
   continuous unnamed rule.
 - Controlled/uncontrolled behavior: not applicable.
@@ -67,6 +69,19 @@ Consumer syntax and examples belong in `Divider.doc.mjs`.
 
 Consumer migration instructions belong in consumer docs and release notes.
 
+## Current-state impact
+
+- **Theme-added variant without line paint (FR3).** `DividerVariantMap` admits
+  theme-added values, but an unmatched value leaves the inner rule unpainted, so
+  the line can disappear. `architecture:component-theming-surface` INV14
+  requires an extensible visual axis to have a safe theme-independent baseline;
+  OQ2 holds the remediation direction.
+- **Caller `role` and `aria-orientation` replaced (FR6).** Divider sets
+  `role="separator"` and `aria-orientation` after caller props, so a caller's
+  explicit values never reach the root, where
+  `architecture:public-component-api` INV5 lets a caller's explicit input reach
+  the element.
+
 ## Ownership boundary
 
 **Owns**
@@ -76,8 +91,8 @@ Consumer migration instructions belong in consumer docs and release notes.
 - Horizontal and vertical rule geometry.
 - Optional label placement and the separator naming relationship.
 - Built-in subtle and strong line weights.
-- The current reflected custom-variant state, including the missing deterministic
-  line-paint fallback recorded by OQ2.
+- The reflected custom-variant state, including the missing line-paint fallback
+  recorded under Current-state impact.
 - Logical full-bleed consumption of inherited container inset.
 - The aggregate `divider` target with reflected orientation and variant axes.
 
@@ -86,33 +101,30 @@ Consumer migration instructions belong in consumer docs and release notes.
 - The meaning or heading structure of surrounding content regions — owned by the
   product callsite.
 - Container inset publication — owned by `architecture:container-padding`.
-- A separate public target for Rule or Label — unresolved under OQ1.
+- A separate public target for Rule or Label — none exists; OQ1 holds the question.
 - Theme-authored custom variant paint and the public part that should own it —
-  unresolved under OQ2.
+  OQ2 holds the question.
 
 ## Public concepts
 
-| Concept      | Closed values or states                       | Meaning                                                                                       | Availability by variant/orientation/state | Default      | Owner                        | Stability                               | Invalid-value behavior                                                             |
-| ------------ | --------------------------------------------- | --------------------------------------------------------------------------------------------- | ----------------------------------------- | ------------ | ---------------------------- | --------------------------------------- | ---------------------------------------------------------------------------------- |
-| Orientation  | `horizontal`; `vertical`                      | Selects the separator axis, rule geometry, and `aria-orientation`.                            | Every divider                             | `horizontal` | component                    | stable                                  | Closed union; rejected by types                                                    |
-| Label        | renderable ReactNode; omitted/skipped scalar  | Inserts one label between two rules and names the separator unless explicit ARIA naming wins. | Every orientation and variant             | omitted      | caller/component             | stable                                  | `null`, booleans, and empty strings render no label; numeric zero remains visible  |
-| Variant      | `subtle`; `strong`; theme-added visual values | Selects line paint and reflects the requested value on the target.                            | Every orientation and label state         | `subtle`     | component/theme              | stable built-ins; theme-extensible axis | An unmatched custom value has no deterministic line-paint baseline; see OQ2        |
-| Full bleed   | false; true                                   | Consumes inherited logical container inset on the divider axis.                               | Every orientation                         | false        | component/container protocol | stable                                  | Missing variables resolve to zero                                                  |
-| Root surface | ref; DOM/data/ARIA; class/style/xstyle/events | Extends the semantic separator root.                                                          | Every divider                             | omitted      | public component API         | stable                                  | Accepted inputs compose; component-owned role and orientation remain authoritative |
+| Concept      | Closed values or states                       | Meaning                                                                                       | Availability by variant/orientation/state | Default      | Owner                        | Stability                               | Invalid-value behavior                                                                     |
+| ------------ | --------------------------------------------- | --------------------------------------------------------------------------------------------- | ----------------------------------------- | ------------ | ---------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------ |
+| Orientation  | `horizontal`; `vertical`                      | Selects the separator axis, rule geometry, and `aria-orientation`.                            | Every divider                             | `horizontal` | component                    | stable                                  | Closed union; rejected by types                                                            |
+| Label        | renderable ReactNode; omitted/skipped scalar  | Inserts one label between two rules and names the separator unless explicit ARIA naming wins. | Every orientation and variant             | omitted      | caller/component             | stable                                  | `null`, booleans, and empty strings render no label; numeric zero remains visible          |
+| Variant      | `subtle`; `strong`; theme-added visual values | Selects line paint and reflects the requested value on the target.                            | Every orientation and label state         | `subtle`     | component/theme              | stable built-ins; theme-extensible axis | An unmatched custom value leaves the rule unpainted (FR3)                                  |
+| Full bleed   | false; true                                   | Consumes inherited logical container inset on the divider axis.                               | Every orientation                         | false        | component/container protocol | stable                                  | Missing variables resolve to zero                                                          |
+| Root surface | ref; DOM/data/ARIA; class/style/xstyle/events | Extends the semantic separator root.                                                          | Every divider                             | omitted      | public component API         | stable                                  | Accepted inputs compose; a caller `role` or `aria-orientation` is replaced today (FR6 gap) |
 
 ## 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 divider MUST render one rule without a renderable label and two rules with the label between them. Numeric zero MUST remain a renderable label.                                                                              | Released ReactNode API; current source/docs; `architecture:public-component-api/INV9`  | verify                          |
-| FR2 | The root MUST expose `role="separator"` and the selected `aria-orientation`. A renderable label MUST name it through `aria-labelledby` unless an explicit caller `aria-label` or `aria-labelledby` wins.                         | WCAG 2.2 SC 1.3.1 and 4.1.2; current source/tests                                      | verify                          |
-| FR3 | Built-in variants MUST paint subtle or strong lines. The exported map accepts theme-added values, but an unmatched value currently leaves the inner rule without line paint; the correct fallback/target ownership requires OQ2. | `architecture:component-theming-surface/INV4,INV6,INV14`; exported `DividerVariantMap` | human decision; open BLOCK      |
-| FR4 | Full bleed MUST consume inherited logical inline inset for horizontal dividers and logical block inset for vertical dividers; absent inset MUST resolve to zero.                                                                 | `architecture:container-padding/INV1,INV3,INV7–INV10`                                  | verify                          |
-| FR5 | The root MUST carry the `divider` target and reflect orientation and requested variant. Rule and Label currently carry no public target.                                                                                         | `architecture:component-theming-surface/INV3–INV6`; current metadata                   | verify; part exposure unsettled |
-| FR6 | Accepted ref, DOM/data/ARIA, class, style, events, and `xstyle` MUST reach or compose on the separator root without replacing component-owned role or orientation.                                                               | `architecture:public-component-api/INV5–INV8`                                          | verify                          |
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                     | Basis                                                                       |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| FR1 | The divider renders one rule without a renderable label and two rules with the label between them. Numeric zero is a renderable label; `null`, booleans, and empty strings render no label. A horizontal divider is a full-width flex row and a vertical divider a full-height inline flex column; the label uses supporting type in secondary text with `--spacing-3` padding on the divider's axis.         | Released ReactNode API; current source, docs, and tests                     |
+| FR2 | By default the root exposes `role="separator"` and the selected `aria-orientation`; a caller's explicit `role` or `aria-orientation` wins and is used as given, even where it contradicts `orientation` (FR6). A renderable label names it through `aria-labelledby` unless a caller `aria-label` or `aria-labelledby` is supplied.                                                                           | WCAG 2.2 SC 1.3.1 and 4.1.2; current source and tests                       |
+| FR3 | `subtle` paints the rule `--color-border` and `strong` paints it `--color-border-emphasized`, at `--border-width`. The exported map accepts theme-added values, which the root reflects, and an extensible visual axis has a safe theme-independent baseline (`architecture:component-theming-surface` INV14). Implementation gap: an unmatched value leaves the inner rule unpainted (Current-state impact). | `architecture:component-theming-surface/INV4,INV6,INV14`; current source    |
+| FR4 | Full bleed consumes the inherited logical inline inset for horizontal dividers and the logical block inset for vertical dividers, extending the box by the same amounts; absent inset resolves to zero.                                                                                                                                                                                                       | `architecture:container-padding/INV1,INV3,INV7–INV10`; current source       |
+| FR5 | The root carries the `divider` target and reflects `orientation` and the requested `variant`. Rule and Label carry no public target. The reflected `data-orientation` and `data-variant` are component-owned theming state and replace a caller's values.                                                                                                                                                     | `architecture:component-theming-surface/INV3–INV6`; current source and docs |
+| FR6 | `ref`, DOM, data, ARIA, class, style, event, and `xstyle` inputs reach or compose on the separator root, and a caller's explicit `role` or `aria-orientation` reaches it (`architecture:public-component-api` INV5). Implementation gap: the component sets `role` and `aria-orientation` after caller props, so a caller's values are replaced (Current-state impact).                                       | `architecture:public-component-api/INV5–INV8`; current source and tests     |
 
 ### Allowed variation
 
@@ -131,7 +143,7 @@ intentional decision.
 | Labelled horizontal                 | Two rules around one visible, naming label                                              | Any renderable label content               |
 | Numeric zero label                  | One visible `0` inside the label wrapper; separator name `0`                            | Any orientation or variant                 |
 | Vertical labelled/unlabelled        | Block-axis rules and vertical separator semantics                                       | Container height and label content         |
-| Theme-added variant without a match | Requested variant reflected; inner rule has no component-owned paint (open BLOCK)       | Custom variant name                        |
+| Theme-added variant without a match | Requested variant reflected; inner rule has no component-owned paint (FR3 gap)          | Custom variant name                        |
 | Full bleed                          | Logical-axis inset consumed without physical-direction assumptions                      | Uniform, asymmetric, zero, or absent inset |
 | RTL                                 | Horizontal geometry remains logical; full bleed consumes inline start/end independently | Surrounding content and label language     |
 
@@ -144,7 +156,7 @@ intentional decision.
   unnamed.
 - **ORD3 — Variant paint.** Reflect the requested value on the root target. Built-in
   values select subtle or strong inner-rule paint; unmatched custom values select no
-  inner-rule paint pending OQ2.
+  inner-rule paint (FR3).
 
 ### Performance and resources
 
@@ -153,8 +165,10 @@ intentional decision.
 
 ## Accessibility contract
 
-- **AR1 — Programmatic separator.** The root exposes separator role and the exact
-  visual orientation.
+- **AR1 — Programmatic separator.** By default the root exposes separator role
+  and the exact visual orientation; a caller's explicit `role` or
+  `aria-orientation` wins (FR6), and today the component's values replace it
+  (FR6 gap).
 - **AR2 — Label relationship.** A rendered label names the separator unless the
   caller supplies an explicit accessible name relationship.
 - **AR3 — Decorative rule segments.** Internal rule elements add no separate role,
@@ -164,11 +178,11 @@ intentional decision.
 
 | Anatomy or state | Design requirement                                                                            | Representation authority                                     | Hierarchy role | Component contract |
 | ---------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | -------------- | ------------------ |
-| Divider group    | Arrange rule segments and the optional label on one logical axis.                             | observed; container geometry settled by current architecture | supporting     | FR1, FR4           |
-| Rule             | Paint a visible subtle or strong separation line; theme-added values lack a settled fallback. | built-ins observed; custom fallback unsettled                | supporting     | FR3                |
-| Label            | Present optional content between two rules using supporting text tokens.                      | observed; separate target exposure unsettled                 | prominent      | FR1–FR2            |
+| Divider group    | Arrange rule segments and the optional label on one logical axis.                             | Current source; container geometry from current architecture | supporting     | FR1, FR4           |
+| Rule             | Paint a visible subtle or strong separation line; theme-added values lack a settled fallback. | Current source; custom fallback is the FR3 gap               | supporting     | FR3                |
+| Label            | Present optional content between two rules using supporting text tokens.                      | Current source; no separate target (OQ1)                     | prominent      | FR1–FR2            |
 
-No component-local visual decision is settled by this draft.
+No component-local design decision is recorded.
 
 ### Theming anatomy
 
@@ -190,54 +204,49 @@ No component-local visual decision is settled by this draft.
 }
 ```
 
-The two `none` dispositions record current reachability while target exposure
-remains unsettled. They do not decide that Rule or Label should remain without
-public targets.
+The two `none` dispositions record that no public target reaches Rule or Label;
+OQ1 holds whether they should gain one.
 
 ## Family and system relationships
 
 - `architecture:container-padding` owns the inherited internal inset protocol;
   Divider consumes it only through `isFullBleed`.
-- `architecture:component-theming-surface` owns the aggregate target, reflected
-  axes, anatomy qualification, and the requirement that an open visual axis have
-  a deterministic fallback. Divider's current custom-value path does not satisfy
-  that requirement; OQ2 keeps remediation out of this objective audit patch.
+- `architecture:component-theming-surface` sets the rules for the target,
+  reflected axes, and anatomy qualification, and the requirement that an open visual axis have
+  a deterministic fallback. Divider's custom-value path does not satisfy that
+  requirement (FR3); OQ2 holds the remediation direction.
 - `architecture:public-component-api` owns root composition, ref behavior, and
   compatibility of the released ReactNode label surface.
 - There is no current Divider family or design record.
-- `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–AR3 | `Divider.test.tsx`; component-owned Storybook states; scoped axe | labelled/unlabelled, numeric zero, explicit names, both orientations | Truthiness renders zero outside wrappers or leaves the separator unnamed; role/orientation/name drift fails | `audit:Divider/§1,§4`     |
-| FR3              | Source review; global extensible-axis structural guard           | subtle, strong, unmatched theme-added value                          | The current unmatched path leaves the rule unpainted; no Divider-specific browser fallback proof exists     | `audit:Divider/§2`        |
-| FR4              | Source review; horizontal and vertical full-bleed stories        | inline/block, LTR/RTL logical properties, absent inset               | A physical property or wrong axis consumes unrelated container geometry                                     | `audit:Divider/§5,§9,§10` |
-| FR5              | `themingTargets.test.ts`; component metadata; spec anatomy map   | both orientations and variants                                       | Target/axis/anatomy metadata disagrees with runtime reflection                                              | `audit:Divider/§2`        |
-| FR6              | `Divider.test.tsx`; lint, typecheck, and source review           | ref, DOM/data/ARIA, class/style/xstyle/events                        | An accepted input is dropped or component-owned semantics are overwritten                                   | `audit:Divider/§3`        |
-| PR1              | Source review                                                    | every state                                                          | A lifecycle mechanism appears without a resource contract                                                   | `audit:Divider/§7`        |
+| Contract           | Verification                                                                                                          | Representative states                                                    | Mutation or failure expectation                                                                                                                                                                                                                                                                                    | Audit section            |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------ |
+| FR1, FR2, AR1, AR2 | `Divider.test.tsx` orientation, label, naming, and numeric-zero tests                                                 | Labelled and unlabelled, numeric zero, explicit names, both orientations | Rendering zero outside the wrapper, an unnamed labelled separator, or role, orientation, or name drift fails. Gap: only the unlabelled horizontal default is in the stable visual baseline (`core-divider--default`); the vertical layout and the label's type and padding have no automated check.                | `audit:Divider/a11y`     |
+| AR3                | Source review                                                                                                         | Labelled and unlabelled                                                  | Gap: no automated check fails if a rule segment gains a role, name, or tab stop.                                                                                                                                                                                                                                   | `audit:Divider/a11y`     |
+| FR3, FR5           | `Divider.test.tsx` variant and target tests; `themingTargets.test.ts`; stable visual baseline `core-divider--default` | Subtle, strong, both orientations; default                               | A lost class or `orientation`/`variant` reflection fails; a changed default rule paint comes back changed for review. Gap: the strong paint and the unmatched theme-added path have no automated check.                                                                                                            | `audit:Divider/theming`  |
+| FR4                | `@astryx/no-physical-properties` lint rule; `Divider.stories.tsx` full-bleed fixtures                                 | Horizontal and vertical, LTR and RTL, absent inset                       | A physical left/right property in Divider's styles fails lint. Gap: the `Divider.test.tsx` full-bleed test only checks that the element renders, so no automated check fails when full bleed is not applied, on the wrong axis, or with a non-zero fallback, and no browser right-to-left check covers full bleed. | `audit:Divider/layout`   |
+| FR6                | `Divider.test.tsx` ref and passthrough tests                                                                          | Ref, extra props                                                         | A dropped ref or caller prop fails. Gap: the ref test accepts any element, so a ref on a wrapper passes; no test covers the styling-input merge or a caller `role` or `aria-orientation`.                                                                                                                          | `audit:Divider/behavior` |
+| PR1                | Source review                                                                                                         | Every state                                                              | Gap: no automated check fails if Divider adds a listener, observer, timer, or effect.                                                                                                                                                                                                                              | `audit:Divider/behavior` |
+| AR1, AR2           | Accessibility-tree evidence (`spec:AST-009` FR3)                                                                      | Labelled and unlabelled separators                                       | Gap: no accessibility-tree check proves the separator role, orientation, or name; the unit tests query the DOM.                                                                                                                                                                                                    | `audit:Divider/a11y`     |
 
 ## Decision log
 
-None. This draft records current facts and introduces no component-local design
-or theming decision.
+None recorded. The record describes shipped behavior.
 
 ## Open questions
 
 - **OQ1 — Should Rule or Label gain stable public theming targets?** (`human-api`)
-  Their target exposure is unsettled; the current lack of reachability does not
-  decide the answer.
+  No public target reaches them today; that absence does not decide the answer.
 - **OQ2 — Should the open `variant` axis close, or which painting part owns its
   deterministic custom-value fallback?** (`human-api`) The root target can carry
   theme paint while the inner rule carries built-in paint. Applying a subtle inner
   fallback can cover an existing root background; keeping the current path can make
-  the rule disappear. Current authority requires a safe fallback but does not choose
-  between closing the axis, moving target ownership, or routing paint through a
-  reviewed public property.
+  the rule disappear. Options: close the axis, move target ownership, or route
+  paint through a reviewed public property.
 
 ## Content boundary
 
-This file does not duplicate consumer prop tables/examples, current audit scores,
-screenshot matrices, implementation steps, or system rules. The audit pull request
-owns the closed run evidence required by `spec:AST-029/FR5`.
+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/Drawer/Drawer.tsx

@@ -74,6 +74,7 @@ import {LayerDepthProvider, useLayerDismissal} from '../Layer';
 import {layerTextReset} from '../Layer/layerTextReset.stylex';
 import {layerStructureReset} from '../Layer/layerStructureReset.stylex';
 import {LayerContentBoundary} from '../Layer/layerScopedContext';
+import {ModalAnnounceProvider} from '../hooks/ModalAnnounceProvider';
 import {composeEventHandlers, mergeProps, themeProps} from '../utils';
 import {container, overlayPaddingReset} from '../Layout';
 import {
@@ -570,42 +571,44 @@ export function Drawer({
       onClick={composeEventHandlers(onClickProp, handleClick)}
       onKeyDown={onKeyDownProp}
       onCancel={handleCancel}>
-      <LayerDepthProvider>
-        <LayerContentBoundary>
-          {/* Scrollable content area — tabIndex so the dialog's focusing steps
+      <ModalAnnounceProvider dialogRef={dialogRef} isOpen={isOpen && hasScrim}>
+        <LayerDepthProvider>
+          <LayerContentBoundary>
+            {/* Scrollable content area — tabIndex so the dialog's focusing steps
               land on the panel body rather than the first button inside. */}
-          <div
-            tabIndex={-1}
-            {...stylex.props(
-              styles.content,
-              ...container(
-                usesThemePadding
-                  ? {useThemeDefault: 'drawer'}
-                  : {
-                      paddingInnerX: paddingToken,
-                      paddingInnerY: paddingToken,
-                      paddingOuterX: paddingToken,
-                      paddingOuterY: paddingToken,
-                    },
-              ),
-              !usesThemePadding &&
-                effectivePadding !== 4 &&
-                paddingStyles[effectivePadding],
-              !usesThemePadding &&
-                effectivePadding !== 4 &&
-                containerPaddingInlineVarStyles[effectivePadding],
-              !usesThemePadding &&
-                effectivePadding !== 4 &&
-                containerPaddingBlockStartVarStyles[effectivePadding],
-              !usesThemePadding &&
-                effectivePadding !== 4 &&
-                containerPaddingBlockEndVarStyles[effectivePadding],
-              styles.contentSafeArea,
-            )}>
-            {children}
-          </div>
-        </LayerContentBoundary>
-      </LayerDepthProvider>
+            <div
+              tabIndex={-1}
+              {...stylex.props(
+                styles.content,
+                ...container(
+                  usesThemePadding
+                    ? {useThemeDefault: 'drawer'}
+                    : {
+                        paddingInnerX: paddingToken,
+                        paddingInnerY: paddingToken,
+                        paddingOuterX: paddingToken,
+                        paddingOuterY: paddingToken,
+                      },
+                ),
+                !usesThemePadding &&
+                  effectivePadding !== 4 &&
+                  paddingStyles[effectivePadding],
+                !usesThemePadding &&
+                  effectivePadding !== 4 &&
+                  containerPaddingInlineVarStyles[effectivePadding],
+                !usesThemePadding &&
+                  effectivePadding !== 4 &&
+                  containerPaddingBlockStartVarStyles[effectivePadding],
+                !usesThemePadding &&
+                  effectivePadding !== 4 &&
+                  containerPaddingBlockEndVarStyles[effectivePadding],
+                styles.contentSafeArea,
+              )}>
+              {children}
+            </div>
+          </LayerContentBoundary>
+        </LayerDepthProvider>
+      </ModalAnnounceProvider>
     </dialog>
   );
 }

package/src/Drawer/__tests__/DrawerAudit.a11y.chromium.spec.ts

@@ -1,4 +1,5 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
+// @pr-a11y audit Drawer
 
 /**
  * @file DrawerAudit.a11y.chromium.spec.ts

package/src/Drawer/__tests__/DrawerHeaderAudit.a11y.chromium.spec.ts

@@ -1,4 +1,5 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
+// @pr-a11y audit DrawerHeader
 
 /**
  * @file DrawerHeaderAudit.a11y.chromium.spec.ts

package/src/DropdownMenu/DropdownMenu.spec.md

@@ -50,12 +50,18 @@ highlight follows the pointer — is contracted by
 
 ## Compatibility and migration
 
-- Released default preserved: `yes`
-- Compatibility class: additive documentation; the press-model behavior
-  delta is recorded in `module:DropdownMenu/useMenuPress`
+- Released default preserved: `no` under a finger. The omitted
+  `presentation`, released as `'popover'`, follows `spec:AST-094` FR29 (open
+  on press) and this record's FR21 (the grow) under a finger; `presentation="popover"` keeps the released
+  behavior (`spec:AST-094` FR25). Mouse and keyboard are unchanged.
+- Compatibility class: compatible behavior correction; public API, DOM
+  shape, styling, and targets are preserved; the default under a finger
+  changes as above, and the press-model behavior delta is recorded in
+  `module:DropdownMenu/useMenuPress`
 - Controlled/uncontrolled behavior: unchanged
 - Migration decision: `module:DropdownMenu/useMenuPress/DEC-3`; proposed
-  `module:DropdownMenu/useMenuPress/DEC-4`
+  `module:DropdownMenu/useMenuPress/DEC-4`; `spec:AST-094/DEC-4` (a caller
+  that needs the released tap-open passes `presentation="popover"`)
 
 Consumer migration instructions belong in consumer docs and release notes.
 
@@ -104,10 +110,10 @@ keeps its released default.
 | FR2                   | The six current local targets are `dropdown-menu`, `dropdown-menu-item`, `dropdown-menu-radio`, `dropdown-menu-section-heading`, `dropdown-menu-divider`, and `dropdown-menu-indicator-icon`; every target remains on its current painted element.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Current source, docs, and tests                                                                                                                                               | Verified current inventory; no target change                                      |
 | FR3                   | Button owns the Trigger button, BottomSheet owns the Touch sheet frame, List owns the Touch action list and Touch action rows, Indicator owns checkbox chrome, and Icon owns ordinary rendered icons.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Current source and owner docs                                                                                                                                                 | Verified current delegation; no ownership change                                  |
 | FR4                   | The same `dropdown-menu` target reaches the alternative Pointer menu surface and Touch menu surface. Pointer action rows retain `dropdown-menu-item`; touch action rows instead use List's `list-item` target.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Current source and tests                                                                                                                                                      | Verified modality split; no target change                                         |
-| FR5                   | Both menu surfaces carry `data-astryx-menu-press` and follow `module:DropdownMenu/useMenuPress` FR1–FR7: the row under the release acts, the highlight follows a held pointer, a mouse released outside closes and a finger leaves the menu open, the browser's stray click never acts, and the Pointer menu surface declares `touch-action` by overflow. Trigger opening and keyboard navigation are unchanged.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `module:DropdownMenu/useMenuPress`; `DropdownMenu.test.tsx` press model suite                                                                                                 | Proposed; verified in jsdom and real Chromium                                     |
+| FR5                   | Both menu surfaces carry `data-astryx-menu-press` and follow `module:DropdownMenu/useMenuPress` FR1–FR7: the row under the release acts, the highlight follows a held pointer, a mouse released outside closes and a finger leaves the menu open, the browser's stray click never acts, and the Pointer menu surface declares `touch-action` by overflow. Under a finger the press, the menu's grow and collapse, and its dismissal follow `spec:AST-094` FR26–FR35 (pending implementation). Trigger opening and keyboard navigation are unchanged.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `module:DropdownMenu/useMenuPress`; `DropdownMenu.test.tsx` press model suite                                                                                                 | Proposed; verified in jsdom and real Chromium                                     |
 | FR6                   | When the pointer menu closes, focus returns to the Trigger button with a visible ring only when the menu was driven by keyboard; a press outside that landed on a focusable control keeps focus there.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `architecture:interaction-modality` INV1; proposed in this change; `DropdownMenu.test.tsx` closing suite                                                                      | Proposed; verified in jsdom, pending owner review                                 |
 | FR7                   | `menuMaxHeight` MUST replace the 300px term of the menu's and its popover viewport's block-size cap while the viewport gutters still bound both; the touch sheet ignores it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `component:DropdownMenu/DEC-3`                                                                                                                                                | Proposed; verified in jsdom; owner to confirm DEC-3                               |
-| FR8                   | The Trigger button opens the pointer menu on a mouse press-down and on a finger held for the long-press delay, with the module's settle rule on the opening release; pressing the trigger of an open menu closes it without reopening in the same gesture; a tap and the keyboard open as before (`module:DropdownMenu/useMenuPress` proposed FR8, FR9).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Proposed `module:DropdownMenu/useMenuPress/DEC-4`; `DropdownMenu.test.tsx` press model suite                                                                                  | Proposed; verified in jsdom, pending owner review                                 |
+| FR8                   | The Trigger button opens the pointer menu on a mouse press-down, with the module's settle rule on the opening release, and under a finger as `spec:AST-094` FR29 states; pressing the trigger of an open menu closes it without reopening in the same gesture; a mouse click and the keyboard open as before (`module:DropdownMenu/useMenuPress` proposed FR8, FR9).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Proposed `module:DropdownMenu/useMenuPress/DEC-4`; `DropdownMenu.test.tsx` press model suite                                                                                  | Proposed; verified in jsdom, pending owner review                                 |
 | Trigger source        | `button` (Button props) or `renderTrigger` (render prop)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Which control the menu hangs off. `trigger` receives `DropdownMenuTriggerProps` — the press model, keyboard opens, toggle click and ARIA wiring — and names the menu.         | Both presentations                                                                | `button`             | `component:DropdownMenu` | stable | Both given: `trigger` wins and a dev warning fires.              |
 | FR9                   | With `renderTrigger`, the rendered control MUST carry `aria-haspopup`, `aria-expanded`, `aria-controls` and the `id` the menu's `aria-labelledby` points at, and MUST receive the same press-model, keyboard-open and toggle-click handlers as the Button path; the menu is named by that control. `button` and `trigger` are mutually exclusive: both given, `trigger` wins and a dev warning fires, in both presentations. A drilled-in Back row (FR11) returns to the menu by that same name: the caller's `aria-label` when given, else the control's accessible name, read as the menu opens.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `component:DropdownMenu/DEC-2`                                                                                                                                                | Proposed; verified in jsdom; owner to confirm DEC-2                               |
 | Row destination       | `href` (+ `target`, `rel`) on an action item                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | The row's act is navigation: the row itself is the link (`family:navigation-destinations`).                                                                                   | Pointer action row and Touch action row, compound and data mode                   | none (an action row) | `component:DropdownMenu` | stable | Blocked schemes follow the family rule; a disabled row has none. |
@@ -121,6 +127,7 @@ keeps its released default.
 | FR16                  | `DropdownMenuCheckboxItem` MUST expose one `menuitemcheckbox` row whose `aria-checked` equals its controlled value; enabled activation reports `!value`, stays open by default, and composes consumer click and pointer-move handlers with owned activation and hover focus. Disabled activation calls no consumer activation handler.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Released subcomponent API; `architecture:public-component-api/INV5–INV8`; `DropdownMenuSelectable.test.tsx`                                                                   | Verified current behavior; consumer handlers are preserved                        |
 | FR17                  | Disabled menu rows SHOULD remain keyboard-discoverable while activation stays blocked. Current shared `useListFocus` deliberately skips every `aria-disabled` row, including checkbox items.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | WAI-ARIA Menu pattern; current shared navigation source/tests                                                                                                                 | Objective mismatch; shared mechanism remains undecided in OQ1                     |
 | FR20                  | With `header` or `footer` on a sub-menu (`DropdownMenuSubMenu`), its surface is a modal dialog named by its row (AR7), holding the header, the sub-menu's `role="menu"` (rows only), then the footer. It sits in a host `DropdownMenu` renders beside its menu, never inside a menu; under a root with no such host (`ContextMenu`) the sub-menu shows its rows alone. On a fine pointer the dialog is the flyout; on a compact touch display, the drilled-in view, which replaces the root's menu and regions until popped. A region keeps its own keys and presses. The rows are one Tab stop: Tab and Shift+Tab walk the header's controls, the rows, then the footer's, and wrap; from a deeper flyout, that flyout closes and the walk goes on from the rows. An open lands as for any sub-menu (FR11, FR12), not on a region. Escape in the dialog, outside an IME composition and unless a control there handled it, returns focus to the row and leaves the root open. A pointer leaving the flyout keeps it open until focus leaves, and it closes with the flyout holding its row. Without either prop nothing changes.                                                                                                    | Proposed DEC-13; FR15; AR5                                                                                                                                                    | Proposed; verified in jsdom and Chromium, pending owner review                    |
+| FR21                  | Under a finger, in the touch modes (`presentation` not pinned to `'popover'`), the pointer menu grows out of the Trigger button and collapses back into it (`spec:AST-094` FR31), and closes on a pan that starts outside it (FR32); a pinned `'popover'` keeps the layer's own entrance. A pan dismissal is the menu's own close: focus that was in the menu returns to the Trigger button, whose `aria-expanded` turns false. A mouse keeps the layer's own entrance and exit.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Owner decision, 2026-10-26; `spec:AST-094` FR31, FR32; `family:overlay-dismissal` AV6                                                                                         | Decided; pending implementation                                                   |
 
 ### Allowed variation
 
@@ -332,6 +339,7 @@ than adding a DropdownMenu-owned heading target.
 | FR10                | `DropdownMenuSubMenu.test.tsx` safe-triangle suite; `useMenuHover.test.tsx` `isPointInSafeTriangle` and click-guard suites                                                                                                                                                                                                                                                                                                                                                                                                                                             | diagonal path toward the flyout, a pause inside it, path away, click-opened and hover-opened guard windows                                                                                                                                                                                                                               | A flyout that closes while the pointer is inside the triangle or paused in it, one that never closes after leaving it, or a changed guard-window rule, fails.                                                                                                                                                                      | `audit:DropdownMenu/behavior`                  |
 | FR15                | `DropdownMenu.test.tsx` header and footer suite; `__tests__/MenuHeaderFooter.a11y.chromium.spec.ts` in real Chromium                                                                                                                                                                                                                                                                                                                                                                                                                                                   | dialog role, modality, name and trigger wiring; regions outside the menu element; typing in a header field; Tab walk header → menu → footer with wrap at both ends; Tab and Shift+Tab from an open sub-menu; hidden and hidden-wrapper controls; Escape from the header; a finger tap on a footer button; bottom sheet order; no regions | A region rendered inside the menu element, a popover with regions that is not a named modal dialog, a trigger still saying `aria-haspopup="menu"` with regions, a header key taken by typeahead, a Tab that leaves the dialog or closes it, focus stranded outside the dialog, or a footer tap swallowed by the press model fails. |
 | FR16                | `DropdownMenuSelectable.test.tsx`, source inspection, scoped `pr-a11y` over the `a11y/Checkbox pattern` stories, and owned Storybook states                                                                                                                                                                                                                                                                                                                                                                                                                            | checked, unchecked, disabled, caller click/pointer handlers, marker size and ownership                                                                                                                                                                                                                                                   | A dropped consumer handler, wrong checked state, nested semantic checkbox, disabled activation, or menu that closes by default fails.                                                                                                                                                                                              | `audit:DropdownMenuCheckboxItem/behavior`      |
+| FR21                | `DropdownMenu.test.tsx` touch motion and pan-outside cases; `menuSurfaceMotion.test.ts`; `__tests__/DropdownMenuTouchMotion.interaction.browser.spec.ts`                                                                                                                                                                                                                                                                                                                                                                                                               | open, close, an interrupted open and close, Reduce Motion, a mouse; a tap, a hold and a pan outside; focus in the menu at a pan dismissal                                                                                                                                                                                                | A pinned `'popover'` or a mouse open that grows from the trigger, a pan outside that leaves the menu open, or focus left in a hidden menu fails                                                                                                                                                                                    |
 | FR17, AR6           | Shared navigation source and DropdownMenu keyboard tests                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | disabled checkbox row first, middle, and last                                                                                                                                                                                                                                                                                            | Current tests prove the shared hook skips the row; no keyboard-discoverability proof exists until OQ1 is settled.                                                                                                                                                                                                                  | `audit:DropdownMenuCheckboxItem/accessibility` |
 | FR20, AR7           | `DropdownMenuSubMenu.test.tsx` "header and footer" suite; `ContextMenu.test.tsx` rows-alone case; `__tests__/SubMenuHeaderFooter.a11y.chromium.spec.ts` in real Chromium (fine pointer, coarse pointer)                                                                                                                                                                                                                                                                                                                                                                | flyout and phone view; dialog role, name, row wiring; regions outside menus; Tab walk and wrap from a field, row, deeper flyout; field keys, presses; Escape, IME and handled Escapes; keyboard open; pointer leaving, focus in then out; parent closing a nested flyout; view tracking its regions; ContextMenu rows alone              | A region inside a menu element, a surface with regions that is not a named modal dialog, a row still saying `aria-haspopup="menu"`, a field key taken by the menu, a Tab that leaves or closes the dialog, a flyout closed under focus by a pointer leaving, a flyout outliving its parent, or the root menu beside a view, fails. | `audit:DropdownMenu/behavior`                  |