@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/BottomSheet/BottomSheet.spec.md

@@ -6,15 +6,18 @@ id: component:BottomSheet
 authority: current
 archive_reason: null
 superseded_by: null
-approved_by: imdreamrunner
-approved_at: 2026-10-21
+approved_by: cixzhang
+approved_at: 2026-10-24
 owners: [cixzhang]
-review_triggers: [theming, layout, public-api]
+review_triggers: [theming, layout, public-api, behavior, accessibility]
 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/BottomSheetStacking.test.tsx,
+    packages/core/src/BottomSheet/BottomSheetReplace.test.tsx,
+    packages/core/src/Toast/ToastViewport.modalHost.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,
@@ -30,7 +33,15 @@ architecture:
     architecture:layer-runtime,
   ]
 contributing: []
-system_specs: [spec:AST-025]
+system_specs:
+  [
+    spec:AST-025,
+    spec:AST-099,
+    spec:AST-027/FR8,
+    spec:AST-017/FR7,
+    spec:AST-017/FR25,
+    spec:AST-020,
+  ]
 ---
 
 # BottomSheet component contract
@@ -39,20 +50,52 @@ system_specs: [spec:AST-025]
 
 BottomSheet presents caller-provided content in a panel that rises from the
 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.
+renders, keyboard-reachable scrolling, theming reachability, the Content area's
+container padding, and how standalone sheets relate to one another: modal
+sheets form one stack per document ordered by when they opened, a sheet that
+closes in the same update another opens is replaced by it with one handoff
+motion, and non-modal sheets are hosted in the browser's top layer (DEC-2).
+Multi-step flows are written as one standalone sheet per step driven by one
+state value; `BottomSheetSwitcher` is the deprecated predecessor of that
+pattern (`component:BottomSheetSwitcher` DEP-0015). 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: `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: none; the precedence rule under Transformation and
-  precedence order is the whole contract
+- Compatibility class: no public prop, type, default, or export changes.
+  Stacking, the replace handoff, and non-modal top-layer hosting are behavior
+  of the existing component, tagged `[feat]` (`spec:AST-017/FR7`: a compatible
+  capability) and admissible in a patch under `spec:AST-017/FR25` as
+  additive — no released contract described two presented sheets, so the stack
+  gives behavior to a state no contract covered — and as
+  implementation-equivalent for a sheet on its own: a modal sheet presented on
+  its own behaves as released (focus on open wherever the engine's
+  `showModal()` focusing steps put it — in Chromium the panel, a
+  `data-autofocus` descendant notwithstanding; in Firefox the first focusable
+  control in the content), and a non-modal sheet on its own keeps its
+  documented contract (no scrim, no scroll lock, page interactive, dismissal
+  by `purpose`, `finalFocusRef` focused after every close, the element focused
+  when it was shown focused again when it closes while focus is inside it, and
+  focus on open where that engine's `show()` focusing steps put it — the panel
+  in Chromium, the first control in Firefox, likewise)
+  while its host changes from `show()` with a page-level `z-index` to the top
+  layer with none (FR11). One exception, visual only: under
+  `prefers-reduced-motion: reduce` a lone sheet's entrance and exit follow
+  FR15 (no transform travel; a cross-fade on a coarse pointer or after a
+  touch drag's release, an immediate change otherwise) where the released
+  motion ran its transforms shortened — a motion change under a preference,
+  no change to any state, event, or focus outcome. Two modal sheets open at
+  once stack (FR5) instead of presenting as unrelated dialogs that each dim
+  the page
+- Controlled/uncontrolled behavior: unchanged; `isOpen` stays fully controlled,
+  and a sheet never writes another sheet's state (FR8)
+- Migration decision: none for callers of BottomSheet. Flows written with
+  `BottomSheetSwitcher` migrate to standalone steps under
+  `component:BottomSheetSwitcher` DEP-0015
 
 Consumer migration instructions belong in consumer docs and release notes.
 
@@ -68,6 +111,12 @@ Consumer migration instructions belong in consumer docs and release notes.
 - Standalone sheet presentation, including its optional native-dialog Scrim.
 - The native dialog every sheet renders, standalone or switcher-managed
   (`component:BottomSheetSwitcher` DEC-1).
+- The stack of presented modal sheets in one document: their order, which one
+  is on top, how far a covered sheet recedes, which backdrop paints the one
+  scrim, and the native top-layer order that realizes it (FR5–FR7, DEC-2).
+- The replace handoff between a sheet closing and a sheet opening in the same
+  update (FR9–FR10).
+- The top-layer hosting of a non-modal sheet (FR11).
 
 **Does not own / non-goals**
 
@@ -76,28 +125,54 @@ 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).
-- Shared layer hosting or dismissal policy.
+  (`component:BottomSheetSwitcher` DEC-1). The flow as a whole is one level of
+  the stack (FR12).
+- Shared layer hosting or dismissal policy. The Escape and platform-close order
+  is `family:overlay-dismissal`'s; the stack only tells it which sheet can
+  take a close request (FR7).
+- Which `Dialog`, `Drawer`, `Popover`, or other layer paints above a sheet;
+  those keep their own hosting (`architecture:layer-runtime`). A `Dialog`
+  opened from a sheet is not a stack level.
 
 ## Public concepts
 
-No new public concept is introduced. Consumer props and usage remain documented
-in `BottomSheet.doc.mjs`.
+No new public concept is introduced. Stacking and the replace handoff are
+behavior of the existing `isOpen` / `onOpenChange` contract: a sheet opened
+while another modal sheet is open stacks on it; a sheet that closes in the same
+update as one other sheet opens, from a control inside it, is replaced by it.
+There is no stack component, context, or opt-in prop. Consumer props and usage
+remain documented in `BottomSheet.doc.mjs`.
 
 ## Behavioral and layout contract
 
-| 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` |
+| 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`                                                                        |
+| FR5  | Modal sheets presented in one document form one stack ordered by open order: the sheet opened most recently is on top; sheets opening in one update are ordered by tree order (a sheet before the sheets rendered in its content, siblings in source order), and the first painted frame already shows that order. Only sheets of one document stack.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | DEC-2                                                                                                   |
+| FR6  | A covered modal sheet stays mounted with its state, recedes behind the top sheet, and is blocked: the browser's modal rules block it, and when it contains no presented sheet it is also `inert` and `aria-hidden`. Exactly one backdrop is visible for a stack — the bottom open sheet's — and a change of scrim owner lands with no transition, so the page dim is constant through a push, a pop, and a handoff.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | DEC-2                                                                                                   |
+| FR7  | Escape, a scrim tap, a swipe, and a platform close request reach only the top sheet of a stack, through that sheet's own `onOpenChange` and `purpose`; a covered sheet, and a replaced sheet during its handoff, report themselves absent to the shared `family:overlay-dismissal` stack while that lasts, so the order among sheets is the sheet stack's and the shared stack stays one registry.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | DEC-2; `family:overlay-dismissal/FR2`, `/FR3`                                                           |
+| FR8  | A sheet rendered in another sheet's content is presented only while its host is open: it leaves the top layer with its host and is presented again, on top, if its own `isOpen` is still true when the host reopens. Its `isOpen` is never written by the host.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | DEC-2                                                                                                   |
+| FR9  | Closing the top sheet returns focus into the sheet it reveals: to the element that opened the closing sheet when that element is inside the revealed sheet, else to the revealed sheet's panel; an explicit `finalFocusRef` outside the revealed sheet yields to its panel in the same way. The last sheet of a stack keeps the standalone rule: `finalFocusRef`, else the opener. Closing every sheet of a stack in one update returns focus once, to the bottom sheet's `finalFocusRef` or opener, after the last dialog has closed. A close driven by the stack itself never moves focus.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | DEC-2                                                                                                   |
+| FR10 | When exactly one standalone sheet closes and exactly one opens in the same update, both of one document and one modality, the closing sheet was the top sheet of its group — its document's modal stack, or, for non-modal sheets, the one open non-modal sheet (FR11) — with the opening sheet set aside, neither dialog contains the other, and the actor — the control last pressed, or, with no fresh press, the element focused when the update began — is inside the closing sheet's dialog or is none (no fresh press, and nothing or only the document body focused, as when code changes the step while focus has fallen to the body), the opening sheet replaces the closing one: it enters above the retained sheet; a retained sheet whose top edge is above the entering sheet's resting top edge moves down to meet it at the same time; the retained sheet fades only after both motions complete; it is `inert` and `aria-hidden` from the first frame and takes no dismissal request; the scrim owner is FR6's, the bottom open sheet: when the retained sheet is that owner (a replace at the bottom of the stack) its backdrop keeps the one visible scrim until it leaves and the entering sheet's backdrop takes over with no transition, and when the replace runs above a covered sheet that sheet stays the owner and the retained sheet's backdrop is transparent throughout, so it only fades; focus moves into the entering sheet; and the entering sheet adopts the retained sheet's focus-return target, so closing the flow returns focus to its first opener. A close and an open that fail any condition — different updates, a covered sheet closing, several sheets changing, a sheet closing with its host, or a control outside the closing sheet acting — keep the ordinary push and pop motion and their own focus return.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | DEC-2                                                                                                   |
+| FR11 | A non-modal sheet (`hasScrim={false}`) is presented in the browser's top layer as a manual popover with no backdrop, no scroll lock, and no focus trap, and carries no page-level `z-index`; where the Popover API is absent it is presented with `show()` in page stacking order as a reduced fallback. A non-modal sheet shown while a modal dialog that does not contain it is open (a modal sheet, a `Dialog`) is inert under that modal, so it does not enter the top layer yet — there it would paint above the modal while a press on it lands on the modal — and is presented with `show()` beneath the modal, with no page-level `z-index`; a modal on its way out (inert, hidden) counts as gone. Once no such modal is open the sheet enters the top layer as a manual popover, a top-layer toast viewport re-entering above it (FR14), so page content never paints over an interactive non-modal sheet (`spec:AST-027` FR8). A non-modal sheet rendered inside the modal's content is not inert and enters the top layer at once. Non-modal sheets never stack, recede, or own a scrim, and never pair with a modal sheet; because they never stack, the one open non-modal sheet of a document is always the top of its own group, so two non-modal sheets replace each other under FR10 — the closing one being that top — with no backdrop. On a lone open, focus goes where the engine's own `show()` focusing steps would put it when they enter the sheet, and no `data-autofocus` preference is added over them (the released behavior, kept, and the same rule as a modal sheet's `showModal()`): in Chromium the panel, whose focusing steps take the first focusable area including a `tabindex="-1"` container; in Firefox the first focusable control in the content, which is the `data-autofocus` field only when it comes first; in WebKit wherever its `show()` lands. Where the manual-popover host's own focusing steps would land elsewhere than that engine's `show()` (Chromium's `showPopover()` lands on the first control), focus arrives where `show()` would have put it without passing through any control — no control receives a focus or a blur on the way, so a field validating on blur does not fire on open; when the sheet is replacing the sheet the person was in, it takes focus, and a `data-autofocus` descendant then wins (AR4). On close an explicit `finalFocusRef` is focused wherever focus is, and otherwise the element focused when the sheet was shown is focused again only while focus is still inside the sheet — the native dialog's own return rule, kept. | DEC-2; `spec:AST-027/FR8`; `architecture:layer-runtime`                                                 |
+| FR12 | A modal `BottomSheetSwitcher` flow is one level of the stack: the dialog of its active step is the flow's level, keeps the flow's rank across the flow's own handoffs, recedes and is blocked when covered, yields its backdrop to the stack's scrim owner, stands down from dismissal while covered, and returns focus by FR9. A standalone sheet rendered in a step's content stacks above the flow and leaves with the step (FR8). A switcher step is never paired under FR10.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | DEC-2; `component:BottomSheetSwitcher/DEC-1`                                                            |
+| FR13 | Every open scrim sheet supplies its dialog as a passive global outlet for app-global surfaces such as toasts (`spec:AST-003` FR18: each active native modal, a covered sheet included), and a modal `BottomSheetSwitcher` flow supplies its active step's dialog — the one its host dialog resolves to, following each handoff; the retained step's dialog, inert and fading, never hosts. Among sheets, the latest outlet — the one a global host renders into — follows the stack's order, not the order the sheets were supplied in: the top sheet is the latest, so a toast lands in the top sheet and never in a covered, inert one, and when the top sheet closes the sheet it reveals is the latest again and takes the host back. A sheet is raised only among sheet outlets: an outlet supplied later by another modal (a `Dialog` opened from a sheet) stays above every sheet until it closes. A sheet, or a flow, stops supplying as soon as it starts closing, and a native `close` event that fires while its dialog is open again (the stack re-showing it, or a reopen during its exit) does not take its outlet away.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | DEC-2; `spec:AST-003/FR16`, `/FR18`; `architecture:layer-runtime`; `component:BottomSheetSwitcher/FR10` |
+| FR14 | When a non-modal sheet enters the top layer, a top-layer toast viewport shown before it leaves and re-enters the top layer in place, keeping focus inside it, so toasts paint above the sheet.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | DEC-2; `architecture:layer-runtime`                                                                     |
+| FR15 | Under `prefers-reduced-motion: reduce` the recede, the return from receded, a push's entrance, a pop's exit and the replace handoff — and a `BottomSheetSwitcher` step's, which shares the sheet panel's motion — follow `design:reduced-motion`, keyed on its queries (`prefers-reduced-motion: reduce`, with `pointer: coarse` for the cross-fade): no transform motion runs (DR1) — a covered sheet appears in its receded place and size the frame the push lands and returns the same way, the entering sheet appears in its final place, the retained sheet does not align down; on a coarse pointer the entering sheet fades in and the leaving or retained sheet fades out where it is, opacity only, in 200 ms or less (DR2); a dismissal the release of a touch drag started (a swipe past the dismiss line) fades out in place the same way on every pointer (DR2's drag-release clause); on any other pointer every other change is immediate (DR3); the handoff's steps run in the released order, so the retained sheet is hidden and its dialog closed once its fade ends. The constant page dim through a push, a pop and a handoff (FR6) holds as it does with motion.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | DEC-2; `design:reduced-motion`                                                                          |
+| FR16 | An open modal sheet is a focus region through Core's shared focus-region module (`component:Dialog/DEC-2`): in the top sheet, Tab from the last tabbable control moves focus to the first and Shift+Tab from the first moves focus to the last, so focus never leaves the sheet for the browser's own interface. A covered or closing sheet does not answer Tab, and a non-modal sheet contains nothing (FR11).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `component:Dialog/DEC-2`                                                                                |
 
 ### Allowed variation
 
 - Caller-provided children may vary without becoming BottomSheet-owned anatomy.
 - Height, snap points, motion phase, and standalone versus switcher hosting may
   vary without changing the four-part anatomy recorded here.
+- The recede geometry of a covered sheet (its scale and offset per depth), the
+  handoff motion curve, and the order in which the entering and alignment
+  motions of a replace complete may vary under theme motion tokens while FR6
+  and FR10's ordering and inertness hold.
 
 ### Representative states
 
@@ -107,16 +182,72 @@ in `BottomSheet.doc.mjs`.
 - 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).
+- Stacked: two or more modal sheets presented in one document; the top sheet is
+  interactive, each covered sheet is receded and blocked, one Scrim is visible.
+- Replacing: a retained sheet and an entering sheet both presented through the
+  handoff, the retained one inert — still painting the Scrim when it is the
+  bottom open sheet (FR6), transparent when a covered sheet beneath owns it —
+  then only the entering sheet.
+- Non-modal: a sheet presented as a manual popover in the top layer with no
+  Scrim; the page remains interactive.
+- Reduced motion: the Stacked and Replacing states above with no transform
+  motion — the covered sheet in its receded place at once, the entering and
+  leaving sheets cross-fading on a coarse pointer and changing at once on any
+  other, except a dismissal a touch drag's release started, which fades out in
+  place on every pointer (FR15, `design:reduced-motion`).
 
 ### Transformation and precedence order
 
 - Content area inset: the `padding` prop, then the theme's `padding` properties
   on `bottom-sheet`, then `--spacing-4` on every logical edge.
-- No new height, gesture, or motion precedence rule is introduced.
+- Stack order: open order, then tree order for sheets opening in one update
+  (FR5). A sheet that closes and reopens takes a new place on top.
+- Native top-layer order is derived from the stack order, not trusted: where
+  the order the dialogs were shown in diverges from the stack order, the
+  stack order holds in the first painted frame (FR5), and no dialog below the
+  first divergence is presented again — a sheet whose place is already right
+  fires no native `close`.
+- A same-update close and open is tested against FR10 in that order of
+  conditions; the first failing condition makes it a push and a pop.
+- No new height or gesture precedence rule is introduced.
 
 ### Performance and resources
 
-- No new performance or resource rule is introduced.
+- Element jobs (`architecture:component-style-authoring` INV7; the
+  open-layer allowance of `spec:AST-017` FR60, DEC-29). An open sheet's frame
+  has these elements, each with one job:
+  - the dialog carries the sheet's dialog role, modality and the top layer
+    when the sheet is modal, and holds the panel at the block end with its
+    own grid; a covered sheet's recede (FR6) is this element's transform;
+  - the panel paints the `bottom-sheet` target;
+  - the grabber bar is the drag handle, and its `::before` draws the handle;
+  - the body is the scroll area;
+  - the content box carries the padding and is the observed content box (FR3);
+  - the edge tint gives iOS Safari's toolbar the sheet's color: its own
+    element outside the panel's transform, so it stays flush with the
+    viewport's bottom edge at every detent, rendered only while the sheet is
+    presented;
+  - in a BottomSheetSwitcher, each sheet's positioner holds its panel at the
+    block end and hides a sheet that is not presented, so one dialog can
+    switch between sheets.
+- The handle's pill is a pseudo-element and a standalone sheet's dialog holds
+  the panel in place, so a standalone sheet's frame has no positioner or pill
+  element of its own.
+- Elements a presenting component adds beyond this frame are its own to
+  justify.
+- **PR1 — One stack per document.** Sheets rendered by every copy of the
+  package loaded on a page that shares the stack protocol, and by every React
+  root on it, form one stack per document: their order is their open order,
+  whichever copy or root rendered them. The protocol version is part of the
+  document-global key the copies meet under; a copy on another protocol
+  version keeps a stack of its own, ordering only the sheets it renders, so
+  two copies of different versions on one page are two independent stacks
+  and neither reads the other's state. No public API reaches the ordering.
+- **PR2 — No per-level backdrop cost.** A stack paints one visible backdrop
+  whatever its depth — the scrim owner's, the bottom open sheet's under FR6 —
+  and every other backdrop in the stack, a covered sheet's or a sheet's above
+  the owner, is transparent, not removed (a switcher flow's dialogs likewise,
+  `component:BottomSheetSwitcher` FR10).
 
 ## Accessibility contract
 
@@ -128,15 +259,52 @@ in `BottomSheet.doc.mjs`.
 - **AR2 — Focus continuity.** Content, overflow, or eligibility changes MUST NOT
   move focus. Pointer/programmatic body focus never delegates. A focused body
   losing overflow remains programmatically focusable.
+- **AR3 — Covered and replaced sheets are not exposed.** A covered sheet that
+  contains no presented sheet, and a replaced sheet through its handoff, are
+  `inert` and `aria-hidden="true"`; the top or entering sheet is the only
+  exposed dialog. A covered sheet that contains the top sheet is left alone,
+  because the top sheet's modality already excludes it (FR6, FR10). Each
+  sheet keeps its own role and accessible name; a non-modal sheet's manual
+  popover host changes neither.
+- **AR4 — Focus follows the person through a stack.** Opening the top sheet
+  moves focus into it; a replace moves focus into the entering step whatever
+  the native host did; a pop returns focus into the revealed sheet; the last
+  close and a close of the whole stack return focus by FR9. A sheet opened on
+  its own, modal or not, focuses wherever the engine's native focusing steps
+  land when the released host presents it, with no `data-autofocus`
+  preference added (the released behavior): in Chromium the panel, in Firefox
+  the first focusable control in the content (a `data-autofocus` field when
+  it comes first), in WebKit wherever its steps land; a non-modal sheet's
+  manual-popover host lands where that engine's `show()` would have (FR11). The one deliberate
+  exception is a sheet entering as a replacement (FR10), whose focus is
+  placed after the native focusing steps because they may have left it in the
+  replaced sheet, or on the entering panel: there a `data-autofocus` descendant is focused first, else
+  the panel, so a step flow that opens on a field keeps the keyboard on it.
+
+- **AR5 — What assistive technology perceives of a push, a pop, and a
+  replace.** The stack adds no announcement of its own to a push or a pop:
+  it fires no live region, so focus entering the top sheet (push) or
+  returning into the revealed sheet (pop, FR9) is what a screen reader
+  reports, and the covered sheet is hidden meanwhile (AR3). Messages the
+  sheets' own content owes are not the stack's and are delivered by their
+  owners' rules — a message pending in a closing sheet reaches the person
+  through the sheet revealed beneath it (`spec:AST-086` FR14). A replace is perceived as focus
+  entering the new step: focus lands on the entering step's `data-autofocus`
+  field or else its panel (AR4), so the entering dialog's accessible name is
+  announced as focus enters it, and the retained step is hidden from the
+  first frame of the handoff (AR3); the stack announces nothing of the
+  retained step's leaving.
 
 ## Design relationships
 
-| Anatomy or state | Design requirement                                                                    | Representation authority       | Hierarchy role | Component contract |
-| ---------------- | ------------------------------------------------------------------------------------- | ------------------------------ | -------------- | ------------------ |
-| Sheet panel      | Presents the painted bottom-edge surface and owns panel geometry and motion.          | Current source and public docs | Prominent      | FR1, FR2           |
-| Content area     | Provides the scrolling, inset area for caller-provided sheet content.                 | Current source and tests       | Prominent      | FR1, FR2, FR4      |
-| Handle           | Presents the decorative grab affordance and owns the panel's drag interaction region. | Current source and tests       | Supporting     | FR1, FR2           |
-| Scrim            | Dims and blocks the page in a scrim-backed host.                                      | Current source and public docs | Supporting     | FR1, FR2           |
+| Anatomy or state | Design requirement                                                                                                                          | Representation authority       | Hierarchy role | Component contract |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | -------------- | ------------------ |
+| Sheet panel      | Presents the painted bottom-edge surface and owns panel geometry and motion.                                                                | Current source and public docs | Prominent      | FR1, FR2           |
+| Content area     | Provides the scrolling, inset area for caller-provided sheet content.                                                                       | Current source and tests       | Prominent      | FR1, FR2, FR4      |
+| Handle           | Presents the decorative grab affordance and owns the panel's drag interaction region.                                                       | Current source and tests       | Supporting     | FR1, FR2           |
+| Scrim            | Dims and blocks the page in a scrim-backed host; one is visible for a stack.                                                                | Current source and public docs | Supporting     | FR1, FR2, FR6      |
+| Covered sheet    | Recedes behind the top sheet (a small scale-down and upward offset per depth, the second step shared by every deeper sheet) and is blocked. | DEC-2                          | Supporting     | FR6                |
+| Replaced sheet   | Holds its place or aligns down to the entering sheet, then fades; keeps the Scrim until it leaves when it is the bottom open sheet (FR6).   | DEC-2                          | Supporting     | FR10               |
 
 Content area, Handle, and Scrim are stable visible parts, but no current public
 target reaches them. Their `none` dispositions record factual reachability, not
@@ -177,20 +345,42 @@ a decision that they must remain unthemeable.
   and records that sheets retain local scrim and swipe behavior.
 - `spec:AST-025` owns effective scroll measurement, overflow and containment,
   automatic keyboard-owner selection, and focus continuity.
+- BottomSheet's on-screen keyboard behavior is owned by `spec:AST-099`.
 - `family:overlay-dismissal` owns shared Escape and platform-close ordering. A
-  standalone BottomSheet registers with the shared stack while it is presented;
-  a switcher-hosted sheet is covered by BottomSheetSwitcher's registration.
+  standalone BottomSheet registers with the shared stack while it is presented
+  and reports itself absent while covered or replaced (FR7); a switcher-hosted
+  sheet is covered by BottomSheetSwitcher's registration.
+- `spec:AST-027` FR8 owns top-layer hosting for non-modal surfaces; a
+  standalone non-modal sheet's manual-popover host satisfies it (FR11), and no
+  page-level band remains on that path.
+- `architecture:layer-runtime` owns the private outlet registry and the toast
+  viewport's hosting; FR13 and FR14 here own only how sheets take part in
+  them (which sheet is the latest outlet, and the toast viewport's re-entry
+  above a non-modal sheet),
+  and that record states the shipped behavior once it ships.
+- `spec:AST-017` FR7 gives stacking, the replace handoff, and the non-modal
+  host their `[feat]` tag and FR25 admits them in a patch (additive and
+  implementation-equivalent); FR26–FR29 govern the switcher's deprecation
+  under `component:BottomSheetSwitcher` DEP-0015.
+- `component:BottomSheetSwitcher` DEC-1 owns a flow's own handoff and the
+  presentation of its step dialogs; FR12 here owns only the flow's place as a
+  level of the stack.
 
 ## Verification map
 
-| Contract            | Verification                                                                                       | Representative states                                                    | Mutation or failure expectation                                                                         | Audit section                     |
-| ------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- | --------------------------------- |
-| FR1                 | `BottomSheet.test.tsx` render, content, Handle, and scrim behavior suites                          | Modal, non-modal, and switcher presentations                             | Removing a documented part fails existing content, structure, or dismissal assertions.                  | `audit:BottomSheet/anatomy`       |
-| FR2                 | Panel target assertion, source inspection, and theming target inventories                          | Sheet panel, Content area, Handle, and Scrim                             | Removing the panel target or documenting an unshipped child target fails evidence or inventory.         | `audit:BottomSheet/theming`       |
-| FR3, AR1–AR2        | `BottomSheetKeyboard.test.tsx`; `BottomSheetKeyboard.a11y.browser.spec.ts`; open Storybook stories | fitting/overflow, plain text, usable/unusable/dynamic descendants, focus | Missing/duplicate keyboard access, stale ownership, focus movement, or broken content-box layout fails. | `audit:BottomSheet/accessibility` |
-| Layout evidence     | `BottomSheetPanel.test.tsx`                                                                        | Floating Handle and scrolling Content area                               | Reordering or merging the stable parts fails existing panel structure and style assertions.             | `audit:BottomSheet/anatomy`       |
-| FR4                 | `BottomSheetPanel.test.tsx` container padding tests; `derivedVarRegistry.test.ts`                  | default, `padding` prop, theme `padding`, lone padded Section child      | The published inset differs from the applied padding, or a lone padded Section changes geometry.        | `audit:BottomSheet/anatomy`       |
-| Theming anatomy map | `scripts/check-knowledge.mjs`                                                                      | Canonical anatomy and current target inventory                           | Missing, extra, prefixed, stale, or multiply assigned mappings fail repository validation.              | `audit:BottomSheet/theming`       |
+| Contract                    | Verification                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Representative states                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Mutation or failure expectation                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Audit section                     |
+| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
+| FR1                         | `BottomSheet.test.tsx` render, content, Handle, and scrim behavior suites                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Modal, non-modal, and switcher presentations                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Removing a documented part fails existing content, structure, or dismissal assertions.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `audit:BottomSheet/anatomy`       |
+| FR2                         | Panel target assertion, source inspection, and theming target inventories                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Sheet panel, Content area, Handle, and Scrim                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Removing the panel target or documenting an unshipped child target fails evidence or inventory.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `audit:BottomSheet/theming`       |
+| FR3, AR1–AR2                | `BottomSheetKeyboard.test.tsx`; `BottomSheetKeyboard.a11y.browser.spec.ts`; open Storybook stories                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | fitting/overflow, plain text, usable/unusable/dynamic descendants, focus                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Missing/duplicate keyboard access, stale ownership, focus movement, or broken content-box layout fails.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `audit:BottomSheet/accessibility` |
+| Layout evidence             | `BottomSheetPanel.test.tsx`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Floating Handle and scrolling Content area                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Reordering or merging the stable parts fails existing panel structure and style assertions.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `audit:BottomSheet/anatomy`       |
+| FR4                         | `BottomSheetPanel.test.tsx` container padding tests; `derivedVarRegistry.test.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | default, `padding` prop, theme `padding`, lone padded Section child                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | The published inset differs from the applied padding, or a lone padded Section changes geometry.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `audit:BottomSheet/anatomy`       |
+| Element jobs                | Open-sheet element count test against the named job list                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | modal and non-modal sheet, scrim and no scrim                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | An element in the open sheet's frame with no named job, or a named job with no element                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |                                   |
+| Theming anatomy map         | `scripts/check-knowledge.mjs`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Canonical anatomy and current target inventory                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Missing, extra, prefixed, stale, or multiply assigned mappings fail repository validation.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `audit:BottomSheet/theming`       |
+| FR5–FR9, FR12–FR15, AR3–AR5 | Stacking unit suite (jsdom, native dialog methods stubbed); real-browser per-frame sampling of transforms, backdrop opacity, hit-testing, and focus on the stacking stories in Chromium, WebKit, and real Safari; a real-browser accessibility-tree check (`spec:AST-020`, `spec:AST-009` FR3) that a lone sheet, a stack of two and three, and a replace handoff expose exactly one `dialog`, the top or entering sheet, with its name, while covered and replaced sheets are hidden, that the stack renders no live region of its own, and that focus enters the entering step's `data-autofocus` field or panel on a replace; a real-browser run with reduced motion emulated on a fine and on a coarse pointer, sampling per frame that no transform animates, that the covered sheet is in its receded place from the frame the push lands, that on a coarse pointer the entering and leaving sheets change opacity only within 200 ms and on a fine pointer at once, that a swipe dismissal fades out in place on a fine pointer, that the dim is constant and that the handoff still completes | siblings, separate components, nested in content, inside a switcher step, a switcher flow as a level, out-of-tree-order opens, same-update deep link, depth 1–3, Escape/scrim/swipe/platform close, covered close, close of the whole stack, focus after each pop, two package copies, a second document                                                                                                                                                                                                                                                                                                                                       | A covered or replaced sheet is exposed in the accessibility tree, the top sheet is exposed without role `dialog` or its name, a covered sheet stays interactive, a second backdrop paints, the dim dips or doubles on a handoff, a dismissal reaches a covered sheet, a nested sheet's state is written or it stays open invisibly, or focus lands on `body` after a pop or a close of the whole stack.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `audit:BottomSheet/behavior`      |
+| FR10–FR11                   | Replace unit suite (jsdom); real-browser parity of the standalone flow against the switcher's handoff — per-frame transforms, opacity, page dim, focus, settled pixels — in Chromium and WebKit, and real Safari for hosting, dim, toast order, and focus; a per-engine lone-open focus probe in Chromium, Firefox and WebKit comparing the sheet's focus on open against that engine's bare `show()` and `showModal()` on the same markup, and recording the focus and blur events the sheet's first control receives on open (none)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | push, pop, different updates, covered close, nested, a replace above a covered sheet (the bottom sheet keeps the scrim, the retained sheet only fades), switcher flow, a lone sheet; handoff in both completion orders; reversal mid-handoff in both directions and both tree orders; unrelated owners from a page control; non-modal replace, reversal, `show()` fallback; a non-modal sheet opened from a modal sheet or a `Dialog` and rendered outside it (while the modal is open, and once it has closed, with positioned page content), one opened in the update that closes a modal sheet, and one rendered inside the modal's content | A replace is recognized for unrelated owners or missed for a real step flow, the retained sheet is exposed or dismissable, the scrim dips, the replaced step stays on screen after a reversal, focus does not enter the step or return to the flow's opener, a non-modal sheet carries a page-level `z-index`, a toast paints under a non-modal sheet, or a lone sheet's focus on open, modal or not, differs from where that engine's released native host (`showModal()`, or `show()` for a non-modal sheet) puts it — in Chromium the panel, with a ring only after keyboard input and a `data-autofocus` field left unfocused; in Firefox the first focusable control — a control inside the sheet receives a focus or a blur on a lone open that `show()` would not have given it, or a replacement entry fails to focus its `data-autofocus` field. A non-modal sheet rendered outside an open modal paints above it while a press lands on the modal, or stays beneath page content once that modal has gone. | `audit:BottomSheet/behavior`      |
+| FR13–FR14                   | Toast viewport hosting suite (jsdom, native dialog methods and popover state stubbed); real-browser hit-testing of a toast raised from the top sheet, from a Dialog opened from a sheet after an inner sheet closed, from a sheet re-shown by a reversal, and over a non-modal sheet                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | a lone sheet; a stack of two; sheet → Dialog → sheet → close the inner sheet; a reversal and a reopen during exit, with the stale native `close`; a non-modal sheet shown after the viewport; a modal switcher flow alone, through a handoff and its close; a flow stacked over a standalone sheet and a standalone sheet over a flow; a non-modal flow                                                                                                                                                                                                                                                                                        | A toast renders in a covered or inert sheet, a Dialog opened from a sheet loses the toast to the sheet beneath it, a re-shown sheet loses its outlet to the stale `close`, a toast raised from a switcher step lands behind the flow or in its retained step, or a toast paints beneath a non-modal sheet.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `audit:BottomSheet/behavior`      |
+| FR16                        | `BottomSheet.test.tsx` focus-region suite                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Modal and non-modal sheets; Tab and Shift+Tab at the sheet's edge                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Tab from the last control leaves a modal sheet, or a non-modal sheet captures Tab                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `audit:BottomSheet/accessibility` |
 
 Existing tests directly assert the Sheet panel target, Content area placement,
 Handle structure, and scrim behavior. Source and public target metadata confirm
@@ -213,6 +403,47 @@ A real flow-root content box supplies the hook's observation seam while preservi
 representative margin, float, percentage-height, flex/grid-child, and hug-height
 behavior.
 
+### DEC-2 — Sheets stack by open order and replace on a same-update switch
+
+**Reference:** `component:BottomSheet/DEC-2`
+**Decider:** imdreamrunner, 2026-10-23
+
+Every modal sheet keeps its own open state and its own native dialog. A sheet
+opened while another modal sheet is open stacks on top of it: the stack is
+ordered by open order with tree order deciding ties within one update, exactly
+one backdrop is visible, covered sheets recede and are blocked, dismissal
+reaches only the top sheet, and the native top layer is put in that order
+before the first paint when the browser's own order would differ (FR5–FR7).
+A sheet rendered in another sheet's content is part of it: it leaves and
+returns with its host and its state stays the caller's (FR8). When the top
+sheet closes in the same update that one other standalone sheet of the same
+modality opens, from a control inside the closing sheet, the opening sheet
+replaces it with the one handoff a step flow needs — entering above, the
+retained sheet aligning down when taller and fading after both motions, one
+steady scrim, focus into the entering step, the first opener kept for the
+flow's close — so a multi-step flow is one standalone sheet per step and one
+state value (FR10). Non-modal sheets are hosted in the top layer as manual
+popovers, never stack, and replace each other the same way (FR11). A
+`BottomSheetSwitcher` flow is one level (FR12). The ordering is one per
+document across React roots and across the package copies that share the
+stack protocol (PR1; a copy on another protocol version keeps its own stack),
+because the coordinated thing — a document's top layer — is wider than any
+React tree. Nothing here is public API; a lone modal sheet never notices the
+stack.
+Rejected: an ordered list of steps on the switcher (`activeSheets`), because
+it changes the switcher's public contract, requires every level of a flow to
+live under one switcher, and cannot order a sheet opened from elsewhere.
+Rejected: a `<BottomSheetStack>` provider or shared dialog that composes
+levels, because a React context cannot reach a second root, a second copy of
+the package, or a widget mounted outside it, while module-level singletons
+already own document-wide facts here (the dismissal stack, the modal outlet
+registry); the only scoping a provider adds is a "same level" boundary, which
+FR10's actor condition supplies without a wrapper.
+Rejected: a `stacked` or `replaces` prop to opt a sheet in, because a lone
+sheet is unaffected and one state value already says what a flow means.
+Rejected: a page-level `z-index` on a non-modal sheet to order a replace,
+because `spec:AST-027` forbids a new band; the top layer orders it.
+
 ## Open questions
 
 - **OQ1 — Should Content area, Handle, or Scrim gain a stable public theming