@astryxdesign/core 0.7.3-canary.f94e962 → 0.7.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.7.3-canary.f94e962",
+  "version": "0.7.3",
   "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,6 @@
     "react-dom": ">=19.0.0"
   },
   "devDependencies": {
-    "@astryxdesign/a11y-spec": "0.7.3-canary.f94e962",
-    "@astryxdesign/cli": "0.7.3-canary.f94e962",
     "@babel/cli": "^7.29.7",
     "@babel/core": "^7.29.7",
     "@babel/preset-react": "^7.29.7",
@@ -804,7 +802,9 @@
     "@testing-library/jest-dom": "^6.6.0",
     "@testing-library/react": "^16.3.2",
     "@types/babel__core": "^7.20.5",
-    "tailwindcss": "^4.3.2"
+    "tailwindcss": "^4.3.2",
+    "@astryxdesign/a11y-spec": "0.0.0",
+    "@astryxdesign/cli": "0.7.3"
   },
   "dependencies": {
     "intl-messageformat": "^11.2.9"

package/scripts/agent-doc-state.mjs

@@ -44,6 +44,26 @@ export const CURSOR_RULES = '.cursorrules';
 export const HERMES_DOT_MD = '.hermes.md';
 export const HERMES_MD = 'HERMES.md';
 
+/**
+ * The page workflow every Astryx agent text gives, written with the command
+ * name `astryx`: the project agent docs and the computer-level skill both
+ * render these lines, so the two never drift.
+ */
+export const WORKFLOW_TITLE =
+  'WORKFLOW — start every page from a template, never from scratch:';
+export const WORKFLOW_STEPS = Object.freeze([
+  '1. `astryx build "<idea>"` — names the template to scaffold from and the parts it lacks.',
+  '2. `astryx template <name> <path>` — scaffold it; keep its frame, gap and padding; replace the content.',
+  '3. `astryx template <Block>` for parts it lacks; `astryx component <Name>` to read props before using one.',
+]);
+
+/**
+ * The self-check's fix for a project with no StyleX or Tailwind compiler,
+ * and for an agent outside a project.
+ */
+export const SELF_CHECK_CSS =
+  'replace any raw <div>/<span>, imported .css/@apply, or hardcoded #hex/px with the component or a token';
+
 export const MARKER_START = '<!-- ASTRYX:START -->';
 export const MARKER_END = '<!-- ASTRYX:END -->';
 // Legacy markers — read during migration so the script finds existing XDS blocks
@@ -101,7 +121,9 @@ export function holdsAstryxBlock(content) {
     while (at !== -1) {
       const from = at + marker.length;
       const end = content.indexOf('<!--', from);
-      const inner = (end === -1 ? content.slice(from) : content.slice(from, end)).trim();
+      const inner = (
+        end === -1 ? content.slice(from) : content.slice(from, end)
+      ).trim();
       if (!/^@\S+$/.test(inner)) return true;
       at = content.indexOf(marker, from);
     }
@@ -163,7 +185,7 @@ export function isAstryxPromptInReach(startDir = process.cwd()) {
  * @returns {string | null}
  */
 function findRepositoryRoot(start) {
-  for (let dir = start; ; ) {
+  for (let dir = start; ;) {
     if (fs.existsSync(path.join(dir, '.git'))) return dir;
     const parent = path.dirname(dir);
     if (parent === dir) return null;

package/src/BottomSheet/BottomSheet.spec.md

@@ -3,11 +3,11 @@ schema_version: 3
 template_version: 3
 kind: component
 id: component:BottomSheet
-authority: draft
+authority: current
 archive_reason: null
 superseded_by: null
-approved_by: null
-approved_at: null
+approved_by: imdreamrunner
+approved_at: 2026-10-21
 owners: [cixzhang]
 review_triggers: [theming, layout, public-api]
 verified_by:
@@ -15,7 +15,6 @@ verified_by:
     packages/core/src/BottomSheet/BottomSheet.test.tsx,
     packages/core/src/BottomSheet/BottomSheetPanel.test.tsx,
     packages/core/src/BottomSheet/BottomSheetKeyboard.test.tsx,
-    packages/core/src/BottomSheet/__tests__/BottomSheetNativeModal.a11y.browser.spec.ts,
     packages/core/src/BottomSheet/__tests__/BottomSheetKeyboard.a11y.browser.spec.ts,
     apps/storybook/stories/BottomSheet.stories.tsx,
     scripts/check-knowledge.mjs,
@@ -38,52 +37,24 @@ system_specs: [spec:AST-025]
 ## Intent
 
 BottomSheet presents caller-provided content in a panel that rises from the
-bottom edge. This draft records current consumer anatomy, keyboard-reachable
-scrolling, theming reachability, and the Content area's container padding.
+bottom edge. This record covers consumer anatomy, the native dialog every sheet
+renders, keyboard-reachable scrolling, theming reachability, and the Content
+area's container padding. Where the shipped sheet does not yet meet a
+requirement, the row carries a present-tense implementation gap note.
 
 ## Compatibility and migration
 
-- Released default preserved: `no` — with no `padding` prop and no theme
-  padding, the Content area insets by `--spacing-4` on every logical edge
-- Compatibility class: breaking default, scheduled for a minor release. Content
-  whose only child is a padded Section keeps its geometry because that Section
-  escapes the inset; content that supplies its own inset is padded twice until
-  it drops that inset or sets `padding={0}`
+- Released default preserved: `yes`; with no `padding` prop and no theme
+  padding, the Content area insets by `--spacing-4` on every logical edge, and
+  `padding={0}` keeps an unpadded Content area
+- Compatibility class: records the shipped anatomy, padded Content area, and
+  native dialog; no public prop, default, or export changes
 - Controlled/uncontrolled behavior: unchanged
-- Migration decision: `padding={0}` restores the released unpadded Content area
+- Migration decision: none; the precedence rule under Transformation and
+  precedence order is the whole contract
 
 Consumer migration instructions belong in consumer docs and release notes.
 
-### DEP-0009 — Deprecate the unpadded default Content area of `BottomSheet`
-
-| Field            | Value                                                                                                                                                               |
-| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| id               | `DEP-0009`                                                                                                                                                          |
-| cleanup          | `CLN-0018`                                                                                                                                                          |
-| package          | `@astryxdesign/core`                                                                                                                                                |
-| surface          | Default inset of the `BottomSheet` Content area when no `padding` prop and no theme padding are set                                                                 |
-| old contract     | The Content area has no padding                                                                                                                                     |
-| replacement      | `padding={0}` keeps the unpadded Content area; `padding` and theme padding already resolve before the default                                                       |
-| direct authority | `component:BottomSheet` Compatibility and migration. Owners: `cixzhang`                                                                                             |
-| warning          | Consumer docs and the release notes name `DEP-0009` and `padding={0}`. No runtime warning (`spec:AST-017` FR29)                                                     |
-| migration        | Mechanical: add `padding={0}` to a BottomSheet that sets no padding, unless its only child is a padded Section or a Layout                                          |
-| codemod          | `astryx upgrade` adds `padding={0}` before any spread, skips sheets whose only child is a core Section or Layout, and marks a nested padding-less Layout for review |
-| downstream       | In-repo sheets that supply their own inset pass `padding={0}`; consumer examples rely on the default inset                                                          |
-| transition       | no prior transition                                                                                                                                                 |
-| state            | `proposed`                                                                                                                                                          |
-| open decision    | This record is draft and needs approval                                                                                                                             |
-| target plan      | `CLN-0018` in the next minor release                                                                                                                                |
-
-### CLN-0018 — BottomSheet pads its Content area by default
-
-| Field     | Value                                                                                                                                |
-| --------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| id        | `CLN-0018`                                                                                                                           |
-| lifecycle | `DEP-0009`                                                                                                                           |
-| delta     | With no `padding` prop and no theme padding, the Content area insets by `--spacing-4` on every logical edge and publishes that inset |
-| rollback  | Restore the unpadded default from the final-patch baseline                                                                           |
-| state     | `pending` — lands in a declared minor with its `[breaking]` Changeset                                                                |
-
 ## Ownership boundary
 
 **Owns**
@@ -95,7 +66,9 @@ Consumer migration instructions belong in consumer docs and release notes.
   `architecture:container-padding`.
 - Standalone sheet presentation, including its optional native-dialog Scrim.
 - The native dialog every sheet renders, standalone or switcher-managed
-  (`component:BottomSheetSwitcher` DEC-1's decided structure).
+  (`component:BottomSheetSwitcher` DEC-1). Implementation gap: a
+  switcher-managed sheet renders a panel inside the switcher's one shared
+  dialog and owns no dialog of its own.
 
 **Does not own / non-goals**
 
@@ -104,7 +77,7 @@ Consumer migration instructions belong in consumer docs and release notes.
   `main`.
 - The presentation lifecycle of its dialog and the flow's scrim ownership when
   the sheet participates in a BottomSheetSwitcher — owned by BottomSheetSwitcher
-  (`component:BottomSheetSwitcher` DEC-1's decided structure).
+  (`component:BottomSheetSwitcher` DEC-1).
 - Shared layer hosting or dismissal policy.
 
 ## Public concepts
@@ -114,12 +87,12 @@ in `BottomSheet.doc.mjs`.
 
 ## Behavioral and layout contract
 
-| ID  | Candidate invariant                                                                                                                                                                                                                         | Basis                              | Draft review state                                 |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | -------------------------------------------------- |
-| FR1 | The current presented sheet contains one Sheet panel, one scrolling Content area, and one decorative Handle; a Scrim is present only in scrim-backed presentation.                                                                          | Current source, docs, and tests    | Verified current behavior; no new behavior decided |
-| FR2 | The Sheet panel carries `bottom-sheet`; Content area, Handle, and Scrim carry no BottomSheet public target.                                                                                                                                 | Current source, docs, and tests    | Verified current behavior; no target change        |
-| FR3 | Content renders in one real observed content box. Effective overflow, containment, and keyboard access come from `useScrollableArea`; the named overflowing body delegates forward Tab entry to a safe first sequential native link/button. | `spec:AST-025`; issue #5207; tests | Focus-time prototype for owner review              |
-| FR4 | The Content area pads caller content by the sheet's container inset and publishes the applied inset to descendants as a container publisher.                                                                                                | `architecture:container-padding`   | Admitted; implementation pending                   |
+| ID  | Invariant                                                                                                                                                                                                                                   | Basis                            |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
+| FR1 | The current presented sheet contains one Sheet panel, one scrolling Content area, and one decorative Handle; a Scrim is present only in scrim-backed presentation.                                                                          | Current source, docs, and tests  |
+| FR2 | The Sheet panel carries `bottom-sheet`; Content area, Handle, and Scrim carry no BottomSheet public target.                                                                                                                                 | Current source, docs, and tests  |
+| FR3 | Content renders in one real observed content box. Effective overflow, containment, and keyboard access come from `useScrollableArea`; the named overflowing body delegates forward Tab entry to a safe first sequential native link/button. | `spec:AST-025`; tests            |
+| FR4 | The Content area pads caller content by the sheet's container inset and publishes the applied inset to descendants as a container publisher.                                                                                                | `architecture:container-padding` |
 
 ### Allowed variation
 
@@ -134,8 +107,8 @@ in `BottomSheet.doc.mjs`.
   without a Scrim.
 - A switcher-managed sheet renders the same panel anatomy in its own dialog while
   BottomSheetSwitcher coordinates that dialog's lifecycle and the flow's one Scrim
-  (`component:BottomSheetSwitcher` DEC-1's decided structure, not shipped
-  anatomy).
+  (`component:BottomSheetSwitcher` DEC-1). Implementation gap: the panel
+  renders inside the switcher's one shared dialog.
 
 ### Transformation and precedence order
 

package/src/BottomSheet/BottomSheet.test.tsx

@@ -498,6 +498,35 @@ describe('BottomSheet', () => {
     expect(dialog).toHaveStyle({'--_sheet-scrim-opacity': '1'});
   });
 
+  it('stays open when a file picker inside it is dismissed, and still closes on its own close request', () => {
+    // A file input fires a bubbling `cancel` at itself when its picker is
+    // dismissed. It reaches the <dialog> like a close request but is not one.
+    const onOpenChange = vi.fn();
+    render(
+      <BottomSheet
+        isOpen
+        purpose="form"
+        onOpenChange={onOpenChange}
+        label="Upload">
+        <input type="file" aria-label="Picture" />
+      </BottomSheet>,
+    );
+
+    const fromPicker = new Event('cancel', {bubbles: true, cancelable: true});
+    fireEvent(screen.getByLabelText('Picture'), fromPicker);
+
+    expect(onOpenChange).not.toHaveBeenCalled();
+    expect(fromPicker.defaultPrevented).toBe(false);
+
+    fireEvent(
+      screen.getByRole('dialog'),
+      new Event('cancel', {cancelable: true}),
+    );
+
+    expect(onOpenChange).toHaveBeenCalledTimes(1);
+    expect(onOpenChange).toHaveBeenCalledWith(false);
+  });
+
   it('keeps a standalone modal sheet presented through its exit animation', () => {
     render(<ExitHarness />);
     const dialog = screen.getByRole('dialog', {name: 'Filters'});

package/src/BottomSheet/BottomSheet.tsx

@@ -361,12 +361,16 @@ function StandaloneBottomSheet({
   });
 
   // The native `cancel` event is a close request the stack never saw a press
-  // for (Android back, the platform close watcher). Always preventDefault so
-  // the browser cannot close the controlled <dialog>, then answer with the
-  // stack's rules: only the top-most layer dismisses, and nothing dismisses
-  // during an IME composition.
+  // for (Android back, the platform close watcher). One that bubbles up from
+  // inside is not: a file input fires it when its picker is dismissed, so it is
+  // left alone. Otherwise always preventDefault so the browser cannot close the
+  // controlled <dialog>, then answer with the stack's rules: only the top-most
+  // layer dismisses, and nothing dismisses during an IME composition.
   const handleCancel = useCallback(
     (event: React.SyntheticEvent<HTMLDialogElement>) => {
+      if (event.target !== event.currentTarget) {
+        return;
+      }
       event.preventDefault();
       if (shouldDismissOnCloseRequest()) {
         dismissOnEscape();

package/src/BottomSheet/BottomSheetSwitcher.spec.md

@@ -3,17 +3,16 @@ schema_version: 3
 template_version: 4
 kind: component
 id: component:BottomSheetSwitcher
-authority: draft
+authority: current
 archive_reason: null
 superseded_by: null
-approved_by: null
-approved_at: null
+approved_by: imdreamrunner
+approved_at: 2026-10-21
 owners: [cixzhang]
 review_triggers: [public-api, behavior, layout, theming, accessibility]
 verified_by:
   [
     packages/core/src/BottomSheet/BottomSheetSwitcher.test.tsx,
-    packages/core/src/BottomSheet/__tests__/BottomSheetNativeModal.a11y.browser.spec.ts,
     apps/storybook/stories/BottomSheetSwitcher.stories.tsx,
     scripts/check-knowledge.mjs,
   ]
@@ -35,13 +34,10 @@ system_specs: [spec:AST-002, spec:AST-027]
 ## Intent
 
 BottomSheetSwitcher coordinates a mutually exclusive sequence of BottomSheet
-children. This draft records verified shipped and remediated behavior, and the
-hosting requirements its decision log decides — each child presented in its own
-native dialog — without adding a prop, changing a default, or settling the
-open modality, identifier, or theming decisions below. A row whose review state
-is "Owner decision" is the decided requirement, not shipped behavior; the
-representative states that name a sheet's own dialog, the retained dialog, or
-the flow wrapper describe DEC-1's decided structure in the same way.
+children, each presented in its own native dialog (DEC-1), without adding a
+prop or changing a default. Where the shipped switcher does not yet meet a
+requirement, the row carries a present-tense implementation gap note. The
+modality, identifier, and theming questions below stay open.
 
 ## Compatibility and migration
 
@@ -61,6 +57,8 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 - The presentation lifecycle of every directly nested BottomSheet child's native
   dialog: which is presented, retained during a handoff, or closed.
+  Implementation gap: the switcher renders one dialog of its own and hosts
+  every child as a panel inside it; no child owns a dialog yet.
 - Which child sheet is active, retained during a handoff, or hidden.
 - Which sheet dialog hosts the flow (its ref, `id`, and dismissal
   registration) and which paints the flow's one scrim, plus
@@ -81,30 +79,27 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ## Public concepts
 
-| Concept             | Closed values or states                              | Meaning                                                                                                                                                                                                                     | Availability by variant/orientation/state                                      | Default                                | Owner                                                                     | Stability | Invalid-value behavior                                                                     |
-| ------------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | -------------------------------------- | ------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------ |
-| Active sheet        | `null` or one nested BottomSheet `sheetId`           | Selects the only interactive child, or closes the flow                                                                                                                                                                      | All presentations                                                              | `null` is closed; the prop is required | `component:BottomSheetSwitcher`                                           | released  | A non-matching or duplicate id is not given a safe public fallback by the current contract |
-| Shared presentation | `true` / `false` through `hasScrim`                  | Selects the current modal scrim-backed host or non-modal no-scrim host                                                                                                                                                      | Entire flow                                                                    | `true`                                 | `component:BottomSheetSwitcher`                                           | released  | Boolean only                                                                               |
-| Child identity      | Non-empty `sheetId` on each direct BottomSheet child | Associates controlled selection, labeling, purpose, and transition state with a child                                                                                                                                       | Direct nested BottomSheet children                                             | none                                   | `component:BottomSheet`                                                   | released  | Empty ids warn and stay hidden; duplicate-id behavior is not specified                     |
-| Dismissal request   | `onActiveSheetChange(null)`                          | Reports an allowed implicit close without taking control from the caller                                                                                                                                                    | Escape/platform close, scrim click, or swipe according to active child purpose | none                                   | `component:BottomSheetSwitcher`; `family:overlay-dismissal` owns ordering | released  | The caller may retain its controlled value                                                 |
-| Dialog surface      | inherited dialog props plus `ref` and `onCancel`     | Dialog props and handlers, `onCancel` included, reach every sheet dialog; `ref`, `id`, and `data-testid` resolve to the host dialog, which is never null for an object ref while a sheet is mounted (owner decision, DEC-2) | Entire flow                                                                    | none                                   | `component:BottomSheetSwitcher`                                           | released  | Component-owned semantics and handlers retain precedence                                   |
+| Concept             | Closed values or states                              | Meaning                                                                                                                                                                                                                                                                                                                     | Availability by variant/orientation/state                                      | Default                                | Owner                                                                     | Stability | Invalid-value behavior                                                                     |
+| ------------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | -------------------------------------- | ------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------ |
+| Active sheet        | `null` or one nested BottomSheet `sheetId`           | Selects the only interactive child, or closes the flow                                                                                                                                                                                                                                                                      | All presentations                                                              | `null` is closed; the prop is required | `component:BottomSheetSwitcher`                                           | released  | A non-matching or duplicate id is not given a safe public fallback by the current contract |
+| Shared presentation | `true` / `false` through `hasScrim`                  | Selects the current modal scrim-backed host or non-modal no-scrim host                                                                                                                                                                                                                                                      | Entire flow                                                                    | `true`                                 | `component:BottomSheetSwitcher`                                           | released  | Boolean only                                                                               |
+| Child identity      | Non-empty `sheetId` on each direct BottomSheet child | Associates controlled selection, labeling, purpose, and transition state with a child                                                                                                                                                                                                                                       | Direct nested BottomSheet children                                             | none                                   | `component:BottomSheet`                                                   | released  | Empty ids warn and stay hidden; duplicate-id behavior is not specified                     |
+| Dismissal request   | `onActiveSheetChange(null)`                          | Reports an allowed implicit close without taking control from the caller                                                                                                                                                                                                                                                    | Escape/platform close, scrim click, or swipe according to active child purpose | none                                   | `component:BottomSheetSwitcher`; `family:overlay-dismissal` owns ordering | released  | The caller may retain its controlled value                                                 |
+| Dialog surface      | inherited dialog props plus `ref` and `onCancel`     | Dialog props and handlers, `onCancel` included, reach every sheet dialog; `ref`, `id`, and `data-testid` resolve to the host dialog, which is never null for an object ref while a sheet is mounted (DEC-2). Implementation gap: every dialog prop, `ref`, `id`, and `data-testid` reaches the switcher's one shared dialog | Entire flow                                                                    | none                                   | `component:BottomSheetSwitcher`                                           | released  | Component-owned semantics and handlers retain precedence                                   |
 
 ## Behavioral and layout contract
 
-Draft requirements identify their basis so observed code is not mistaken for an
-intentional decision. This draft cannot clear the gaps it records.
-
-| ID  | Candidate invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Basis                                                    | Draft review state                                                                                                                                                                       |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| FR1 | Zero or one child sheet is interactive for each controlled `activeSheet` value; all other children are hidden or retained inert and `aria-hidden` during a transition.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Current source, docs, and tests                          | Verified shipped behavior                                                                                                                                                                |
-| FR2 | Each child sheet owns one native dialog. Opening a sheet presents its dialog once; a handoff presents the entering sheet's dialog above the retained one and closes the retained dialog only after its panel has faded. Returning to a sheet whose dialog is still open beneath a newer one re-presents it so the interactive sheet is the topmost layer.                                                                                                                                                                                                                                                                                                                                                                                               | DEC-1                                                    | Owner decision                                                                                                                                                                           |
-| FR3 | During a handoff, the entering sheet is above the retained sheet. A taller retained sheet aligns down to a shorter entering sheet, and the retained sheet fades only after required transform motion completes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Current source and transition tests                      | Verified shipped behavior; exact visual treatment remains human-reviewed                                                                                                                 |
-| FR4 | Closing retains the outgoing sheet through its exit, then closes the dialog. A modal flow restores focus to the element captured when that modal flow opened.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Current source and focus tests                           | Verified shipped behavior                                                                                                                                                                |
-| FR5 | `hasScrim=true` uses `showModal()`, a native backdrop, and native focus containment, and locks page scroll: the page does not scroll while a modal flow is presented; the lock is held continuously across a handoff, never released and re-acquired between steps; it still holds beneath a `Dialog` opened from a step; it is released after the flow's exit (owner decision, DEC-1). `hasScrim=false` uses `show()` without a backdrop or scroll lock and leaves the page interactive (verified current behavior). In a non-modal flow the sheet dialogs order themselves with local values inside the switcher's isolated flow wrapper (owner decision, DEC-1); the page-level value that wrapper carries remains a `spec:AST-027` conformance gap. | DEC-1; `spec:AST-027` FR2, FR4, FR8                      | Modal host and the wrapper's local ordering: owner decision. Non-modal `show()` host: verified current behavior. The wrapper's page-level value remains a `spec:AST-027` conformance gap |
-| FR6 | The active child purpose governs implicit dismissal: `info` allows Escape, scrim click, and swipe; `form` allows Escape; `required` blocks all three and exposes `alertdialog`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Current BottomSheet docs and switcher tests              | Verified shipped behavior                                                                                                                                                                |
-| FR7 | While visible, the switcher participates in `family:overlay-dismissal`; one Escape or platform close request reaches only the topmost present layer, and descendants receive a deeper logical layer scope.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `family:overlay-dismissal` and the audit regression test | Settled remediation in this audit                                                                                                                                                        |
-| FR8 | One backdrop paints the flow's scrim at a time: the retained sheet's dialog keeps it through a handoff and the entering dialog takes it over without a fade when the retained dialog closes. A stale gesture from an outgoing sheet cannot change the flow's scrim, and unmounting a retained sheet cannot keep its dialog open or the flow's modal layer held.                                                                                                                                                                                                                                                                                                                                                                                         | DEC-1; current tests                                     | Owner decision                                                                                                                                                                           |
-| FR9 | The switcher forwards neutral dialog attributes, styling inputs, and composed handlers, `onCancel` included, to every sheet dialog, so a handler fires for whichever sheet dialog raises the event; renders `id` and `data-testid` on the host dialog only, so each appears once in the document; attaches its ref to the host dialog; and preserves its owned ARIA and dismissal behavior. An object ref's `current` is never `null` while a sheet is mounted. A callback ref follows React's semantics on a handoff: a cleanup it returned runs when it detaches from the old host; a callback ref without a cleanup is called with `null` on detach, then with the new host.                                                                         | DEC-1, DEC-2; `architecture:public-component-api` INV8   | Owner decision                                                                                                                                                                           |
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Basis                                                    |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
+| FR1 | Zero or one child sheet is interactive for each controlled `activeSheet` value; all other children are hidden or retained inert and `aria-hidden` during a transition.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Current source, docs, and tests                          |
+| FR2 | Each child sheet owns one native dialog. Opening a sheet presents its dialog once; a handoff presents the entering sheet's dialog above the retained one and closes the retained dialog only after its panel has faded. Returning to a sheet whose dialog is still open beneath a newer one re-presents it so the interactive sheet is the topmost layer. Implementation gap: the switcher presents one shared dialog once per flow and hosts every child as a panel inside it; a handoff swaps panels in that dialog, and no dialog is re-presented.                                                                                                                                                                                                                                                                                                                                       | DEC-1                                                    |
+| FR3 | During a handoff, the entering sheet is above the retained sheet. A taller retained sheet aligns down to a shorter entering sheet, and the retained sheet fades only after required transform motion completes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Current source and transition tests                      |
+| FR4 | Closing retains the outgoing sheet through its exit, then closes the dialog. A modal flow restores focus to the element captured when that modal flow opened.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Current source and focus tests                           |
+| FR5 | `hasScrim=true` uses `showModal()`, a native backdrop, and native focus containment, and locks page scroll: the page does not scroll while a modal flow is presented; the lock is held continuously across a handoff, never released and re-acquired between steps; it still holds beneath a `Dialog` opened from a step; it is released after the flow's exit (DEC-1). `hasScrim=false` uses `show()` without a backdrop or scroll lock and leaves the page interactive. In a non-modal flow the sheet dialogs order themselves with local values inside the switcher's isolated flow wrapper (DEC-1); the page-level value that wrapper carries remains a `spec:AST-027` conformance gap. Implementation gap: a script focus trap runs on top of the modal dialog's native containment; a non-modal flow is one shared dialog carrying the page-level value itself, with no flow wrapper. | DEC-1; `spec:AST-027` FR2, FR4, FR8                      |
+| FR6 | The active child purpose governs implicit dismissal: `info` allows Escape, scrim click, and swipe; `form` allows Escape; `required` blocks all three and exposes `alertdialog`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Current BottomSheet docs and switcher tests              |
+| FR7 | While visible, the switcher participates in `family:overlay-dismissal`; one Escape or platform close request reaches only the topmost present layer, and descendants receive a deeper logical layer scope.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `family:overlay-dismissal` and the audit regression test |
+| FR8 | One backdrop paints the flow's scrim at a time: the retained sheet's dialog keeps it through a handoff and the entering dialog takes it over without a fade when the retained dialog closes. A stale gesture from an outgoing sheet cannot change the flow's scrim, and unmounting a retained sheet cannot keep its dialog open or the flow's modal layer held. Implementation gap: the one backdrop is the shared dialog's, so no takeover between dialogs happens.                                                                                                                                                                                                                                                                                                                                                                                                                        | DEC-1; current tests                                     |
+| FR9 | The switcher forwards neutral dialog attributes, styling inputs, and composed handlers, `onCancel` included, to every sheet dialog, so a handler fires for whichever sheet dialog raises the event; renders `id` and `data-testid` on the host dialog only, so each appears once in the document; attaches its ref to the host dialog; and preserves its owned ARIA and dismissal behavior. An object ref's `current` is never `null` while a sheet is mounted. A callback ref follows React's semantics on a handoff: a cleanup it returned runs when it detaches from the old host; a callback ref without a cleanup is called with `null` on detach, then with the new host. Implementation gap: every forwarded input, `ref`, `id`, and `data-testid` reaches the one shared dialog, which never changes on a handoff.                                                                  | DEC-1, DEC-2; `architecture:public-component-api` INV8   |
 
 ### Allowed variation
 
@@ -116,8 +111,9 @@ intentional decision. This draft cannot clear the gaps it records.
 
 ### Representative states
 
-The states below describe DEC-1's decided structure where they name a sheet's
-own dialog, the retained dialog, or the flow wrapper.
+Where a state names a sheet's own dialog, the retained dialog, or the flow
+wrapper, the shipped switcher meets it with its one shared dialog instead; FR2
+and FR5 record that implementation gap.
 
 | State      | Required invariant                                                                                                                                                               | Allowed variation                                                                        |
 | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
@@ -125,7 +121,7 @@ own dialog, the retained dialog, or the flow wrapper.
 | First open | Matching child is visible and interactive in its own dialog.                                                                                                                     | Child-owned height and content.                                                          |
 | Handoff    | Entering child is interactive in its own dialog; retained child's dialog stays open, inert, and hidden from accessibility APIs until it fades, and keeps painting the one scrim. | Alignment offset depends on measured panel geometry.                                     |
 | Closing    | Outgoing child is retained inert while exit motion completes; modal focus and scroll ownership remain until close.                                                               | Theme-controlled duration.                                                               |
-| Modal      | Native modal host, backdrop, native focus containment, and the page scroll lock are active.                                                                                      | Active child's `purpose` controls implicit dismissal.                                    |
+| Modal      | Native modal host, backdrop, native focus containment, and the page scroll lock are active. Implementation gap: a script focus trap runs on top of the native containment.       | Active child's `purpose` controls implicit dismissal.                                    |
 | Non-modal  | Native non-modal host has no backdrop or scroll lock and background content remains interactive.                                                                                 | The current clipping/stacking limitation is a conformance gap, not an allowed exception. |
 
 ### Transformation and precedence order
@@ -144,7 +140,8 @@ own dialog, the retained dialog, or the flow wrapper.
   Native modality holds across a modal flow's child handoffs because a sheet
   dialog is modal throughout, and the one page scroll lock is held for the
   whole flow rather than per step. A non-modal flow paints no backdrop and
-  holds no lock.
+  holds no lock. Implementation gap: one shared dialog is presented
+  throughout, so a handoff has one dialog open, not two.
 - **PR2 — Stable child registration.** Parent rerenders and changing consumer ref
   identities do not unregister a mounted child or cancel an active handoff.
 
@@ -160,11 +157,11 @@ own dialog, the retained dialog, or the flow wrapper.
 
 ## Design relationships
 
-| Anatomy or state | Design requirement                                                                                                                    | Representation authority                                         | Hierarchy role | Component contract |
-| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | -------------- | ------------------ |
-| Shared dialog    | Transparent host for the flow's interaction and accessibility boundary; DEC-1 decides one such host per child sheet                   | Current source and public docs; DEC-1 for the per-sheet clause   | Structural     | FR2, FR5, AR1      |
-| Sheet panels     | Delegate visible panel, content, handle, and gesture presentation to BottomSheet                                                      | `component:BottomSheet` draft as observational context           | Prominent      | FR1, FR3           |
-| Scrim            | Optional native backdrop that dims and blocks the page in modal presentation; DEC-1 decides that one sheet dialog paints it at a time | Current source and public docs; DEC-1 for the one-painter clause | Supporting     | FR5, FR8           |
+| Anatomy or state | Design requirement                                                                                                                                           | Representation authority                                         | Hierarchy role | Component contract |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------- | -------------- | ------------------ |
+| Shared dialog    | Transparent host for the flow's interaction and accessibility boundary, one per child sheet (DEC-1). Implementation gap: one such host serves the whole flow | Current source and public docs; DEC-1 for the per-sheet clause   | Structural     | FR2, FR5, AR1      |
+| Sheet panels     | Delegate visible panel, content, handle, and gesture presentation to BottomSheet                                                                             | `component:BottomSheet` as observational context                 | Prominent      | FR1, FR3           |
+| Scrim            | Optional native backdrop that dims and blocks the page in modal presentation; one sheet dialog paints it at a time (DEC-1)                                   | Current source and public docs; DEC-1 for the one-painter clause | Supporting     | FR5, FR8           |
 
 ### Theming anatomy
 
@@ -198,16 +195,16 @@ own dialog, the retained dialog, or the flow wrapper.
 - `architecture:public-component-api` and `spec:AST-002` own the released prop,
   DOM, ref, and compatibility surface.
 - `spec:AST-027` identifies the non-modal `show()` plus page-level `z-index` path
-  as a migration gap; this draft does not treat it as an exception.
+  as a migration gap, not an exception.
 
 ## Verification map
 
-| Contract         | Verification                                                                  | Representative states                                                                                                  | Mutation or failure expectation                                                                                                                                              | Audit section                             |
-| ---------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
-| FR1–FR4, FR8     | `BottomSheetSwitcher.test.tsx`                                                | closed, first open, handoffs in either completion order, rapid replacement, unmount, close                             | A child becomes interactive at the wrong time, a retained child disappears early, a second backdrop paints, or a sheet dialog's lifecycle breaks.                            | `audit:BottomSheetSwitcher/behavior`      |
-| FR5–FR7, AR1–AR3 | `BottomSheetSwitcher.test.tsx`; `BottomSheetNativeModal.a11y.browser.spec.ts` | modal/non-modal, info/form/required, nested layer, IME, focus return, scroll lock in engines, non-modal local ordering | Modality, dismissal order, naming, inertness, scroll lock, or focus behavior diverges, or a sheet dialog takes a page-level z-index.                                         | `audit:BottomSheetSwitcher/accessibility` |
-| FR9              | `BottomSheetSwitcher.test.tsx`; export checks                                 | ref across open/handoff/close/unmount, callback-ref cleanup, `id` once, DOM/ARIA/data/events, class, style, xstyle     | A supported input is dropped or duplicated, an object ref is null while a sheet is mounted or skips a cleanup, or an input overrides component-owned semantics accidentally. | `audit:BottomSheetSwitcher/api`           |
-| Theming anatomy  | `scripts/check-knowledge.mjs`; theming tests                                  | dialog, delegated sheet panel, scrim                                                                                   | A non-painting host gains a target, a delegated panel loses its owner, or the scrim gap disappears without review.                                                           | `audit:BottomSheetSwitcher/theming`       |
+| Contract         | Verification                                                                                                            | Representative states                                                                                                  | Mutation or failure expectation                                                                                                                                              | Audit section                             |
+| ---------------- | ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
+| FR1–FR4, FR8     | `BottomSheetSwitcher.test.tsx`                                                                                          | closed, first open, handoffs in either completion order, rapid replacement, unmount, close                             | A child becomes interactive at the wrong time, a retained child disappears early, a second backdrop paints, or a sheet dialog's lifecycle breaks.                            | `audit:BottomSheetSwitcher/behavior`      |
+| FR5–FR7, AR1–AR3 | `BottomSheetSwitcher.test.tsx`; `BottomSheetNativeModal.a11y.browser.spec.ts` (implementation gap: not yet in the tree) | modal/non-modal, info/form/required, nested layer, IME, focus return, scroll lock in engines, non-modal local ordering | Modality, dismissal order, naming, inertness, scroll lock, or focus behavior diverges, or a sheet dialog takes a page-level z-index.                                         | `audit:BottomSheetSwitcher/accessibility` |
+| FR9              | `BottomSheetSwitcher.test.tsx`; export checks                                                                           | ref across open/handoff/close/unmount, callback-ref cleanup, `id` once, DOM/ARIA/data/events, class, style, xstyle     | A supported input is dropped or duplicated, an object ref is null while a sheet is mounted or skips a cleanup, or an input overrides component-owned semantics accidentally. | `audit:BottomSheetSwitcher/api`           |
+| Theming anatomy  | `scripts/check-knowledge.mjs`; theming tests                                                                            | dialog, delegated sheet panel, scrim                                                                                   | A non-painting host gains a target, a delegated panel loses its owner, or the scrim gap disappears without review.                                                           | `audit:BottomSheetSwitcher/theming`       |
 
 ## Decision log
 

package/src/BottomSheet/BottomSheetSwitcher.test.tsx

@@ -708,6 +708,32 @@ describe('BottomSheetSwitcher', () => {
     expect(onActiveSheetChange).toHaveBeenNthCalledWith(2, null);
   });
 
+  it('keeps the flow open when a file picker inside a step is dismissed, and still closes on its own close request', () => {
+    // A file input fires a bubbling `cancel` at itself when its picker is
+    // dismissed. A step renders no dialog, so it reaches the switcher's.
+    const onActiveSheetChange = vi.fn();
+    render(
+      <BottomSheetSwitcher
+        activeSheet="upload"
+        onActiveSheetChange={onActiveSheetChange}>
+        <BottomSheet sheetId="upload" label="Upload" purpose="form">
+          <input type="file" aria-label="Picture" />
+        </BottomSheet>
+      </BottomSheetSwitcher>,
+    );
+
+    const fromPicker = new Event('cancel', {bubbles: true, cancelable: true});
+    fireEvent(screen.getByLabelText('Picture'), fromPicker);
+
+    expect(onActiveSheetChange).not.toHaveBeenCalled();
+    expect(fromPicker.defaultPrevented).toBe(false);
+
+    fireEvent(getSharedDialog(), new Event('cancel', {cancelable: true}));
+
+    expect(onActiveSheetChange).toHaveBeenCalledTimes(1);
+    expect(onActiveSheetChange).toHaveBeenCalledWith(null);
+  });
+
   it('honors purpose=required for a switcher-managed sheet', () => {
     const onActiveSheetChange = vi.fn();
     render(

package/src/BottomSheet/BottomSheetSwitcher.tsx

@@ -591,8 +591,14 @@ export function BottomSheetSwitcher({
       ? undefined
       : sheetLabels.get(visibleTransition.retainedSheet));
 
+  // A `cancel` that bubbles up from a step is not a close request for the
+  // flow: a file input fires one when its picker is dismissed, and a step
+  // renders no dialog of its own, so it lands here. It is left alone.
   const handleCancel = useCallback(
     (event: SyntheticEvent<HTMLDialogElement>) => {
+      if (event.target !== event.currentTarget) {
+        return;
+      }
       event.preventDefault();
       if (shouldDismissOnCloseRequest()) {
         dismissOnEscape();

package/src/Button/Button.test.tsx

@@ -17,6 +17,7 @@ import {
   fireEvent,
   createEvent,
   act,
+  waitFor,
 } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {Button} from './Button';
@@ -643,7 +644,17 @@ describe('Button', () => {
     expect(liveRegion).toHaveTextContent('Loading');
   });
 
-  it('localizes the loading announcement through the i18n catalog', () => {
+  it('mounts the loading live region empty when first rendered loading, then fills it (spec:AST-086 FR3)', async () => {
+    render(<Button label="Submit" isLoading />);
+    const button = screen.getByRole('button');
+    // The Spinner also has role="status", so grab the live region explicitly.
+    const regions = button.querySelectorAll('[role="status"]');
+    const liveRegion = regions[regions.length - 1];
+    expect(liveRegion).toHaveTextContent('');
+    await waitFor(() => expect(liveRegion).toHaveTextContent('Loading'));
+  });
+
+  it('localizes the loading announcement through the i18n catalog', async () => {
     render(
       <InternationalizationProvider
         locale="fr"
@@ -655,7 +666,7 @@ describe('Button', () => {
     // The Spinner also has role="status", so grab the live region explicitly.
     const regions = button.querySelectorAll('[role="status"]');
     const liveRegion = regions[regions.length - 1];
-    expect(liveRegion).toHaveTextContent('Chargement');
+    await waitFor(() => expect(liveRegion).toHaveTextContent('Chargement'));
   });
 
   describe('in a narrow row', () => {