@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/BottomSheet/BottomSheetSwitcher.doc.mjs

@@ -142,7 +142,7 @@ export const docs = {
     },
   },
   description:
-    'Coordinates multiple BottomSheets as a mutually exclusive flow. One activeSheet ID selects the only interactive sheet; during a handoff, the new sheet enters above the inert previous sheet. If the new sheet is shorter, the previous sheet simultaneously moves down until their top edges align, then fades after both transforms complete. Each child sheet renders its own native <dialog>, exactly like a standalone sheet: modal flows present each sheet with showModal(), no-scrim flows with show(). The browser supplies modality: the page is inert and focus stays in the top-layer dialog, so both hold across a handoff; the switcher holds the shared body scroll lock once for the whole modal flow. The switcher coordinates the rest: one scrim paints at a time, focus returns to the element that opened the flow, its ref, id, and data-testid resolve to the dialog hosting the active sheet, and its other dialog props and handlers apply to every sheet dialog.',
+    'Deprecated: write each step as its own BottomSheet with isOpen, controlled by one state value that names the open step. Closing the top sheet and opening the next in the same update, from a control inside the open step, runs the same replace handoff (see BottomSheet, Replacing a sheet), with no sheetId and no switcher; a step changed from a control outside the flow (a page control, or code after focus left the step) closes and opens with ordinary push and pop motion. BottomSheetSwitcher keeps working until a future minor release removes it: a flow used on its own behaves as released (with two fixes: a toast raised from a step renders above the flow and can be pressed, and under reduced motion its steps follow the reduced-motion rule), and a flow stacked with other sheets is one level of the stack (it recedes and is blocked when covered, shares the one scrim, and stands down from dismissal while covered). Modal and hasScrim={false} flows migrate the same way. Coordinates multiple BottomSheets as a mutually exclusive flow. One activeSheet ID selects the only interactive sheet; during a handoff, the new sheet enters above the inert previous sheet. If the new sheet is shorter, the previous sheet simultaneously moves down until their top edges align, then fades after both transforms complete. Each child sheet renders its own native <dialog>: a modal flow presents each sheet with showModal(), as a standalone modal sheet does, so the browser supplies modality (the page is inert and focus stays in the top-layer dialog, so both hold across a handoff) and the switcher holds the shared body scroll lock once for the whole modal flow. A no-scrim flow presents each sheet with show() inside the isolated flow wrapper of the switcher, which orders the step dialogs with local values; this differs from a standalone hasScrim={false} sheet, which is hosted in the top layer as a manual popover with no page-level z-index, and it is one reason to migrate. The switcher coordinates the rest: one scrim paints at a time, focus returns to the element that opened the flow, its ref, id, and data-testid resolve to the dialog hosting the active sheet, and its other dialog props and handlers apply to every sheet dialog.',
   props: [
     {
       name: 'ref',
@@ -187,17 +187,17 @@ export const docs = {
   usage: {
     anatomy,
     description:
-      "Coordinates a multi-step bottom-sheet flow, one native dialog per sheet; set activeSheet to a nested BottomSheet's sheetId to open or switch steps, and to null to close.",
+      "Deprecated: write each step as its own BottomSheet with isOpen, controlled by one state value that names the open step. Closing the top sheet and opening the next in the same update, from a control inside the open step, runs the same replace handoff (see BottomSheet, Replacing a sheet), with no sheetId and no switcher; a step changed from a control outside the flow (a page control, or code after focus left the step) closes and opens with ordinary push and pop motion. BottomSheetSwitcher keeps working until a future minor release removes it: a flow used on its own behaves as released (with two fixes: a toast raised from a step renders above the flow and can be pressed, and under reduced motion its steps follow the reduced-motion rule), and a flow stacked with other sheets is one level of the stack (it recedes and is blocked when covered, shares the one scrim, and stands down from dismissal while covered). Modal and hasScrim={false} flows migrate the same way. Set activeSheet to a nested BottomSheet's sheetId to open or switch steps, and to null to close.\n\nStacking. A scrim flow is one level in the stack of open sheets (see BottomSheet, Stacking). Open it while a standalone sheet is open and the flow sits on top of that sheet, which recedes and is blocked; open a standalone sheet while the flow is open, from a step's content or from anywhere else, and that sheet sits on top while the whole flow recedes as one. Switching the step in place never changes the flow's position. Escape, the scrim, a swipe, and a platform close request reach only the top level: the flow's onActiveSheetChange(null) when the flow is on top, the standalone sheet's onOpenChange(false) when that sheet is. A standalone sheet rendered inside a step's content is presented only while that step is the active one: it leaves when the flow switches step or closes, its isOpen stays yours, and it is presented again, on top, if the step returns while it is still open. Only the bottom level's backdrop dims the page. A no-scrim flow stays out of the stack.",
     bestPractices: [
       {
         guidance: true,
         description:
-          'Use when each step depends on the previous one and only one step needs attention at a time.',
+          'Prefer one standalone BottomSheet per step with one state value naming the open step; the replace handoff is the same and nothing has to be nested under a switcher.',
       },
       {
         guidance: true,
         description:
-          'Give every child a unique sheetId and non-empty label, choose its purpose to match dismissal requirements, and follow the WAI-ARIA Dialog (Modal) pattern for scrim-backed flows: https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/.',
+          'Migrate an existing flow in place: replace activeSheet / onActiveSheetChange with one step value, give each step isOpen={step === id} and a guarded onOpenChange (clear the step only if it is still the open one) in place of sheetId, remove the wrapper and move its hasScrim onto every step. Map the other switcher props: onCancel becomes a guarded onOpenChange on each step (ignore false while the flow must stay open) — a standalone sheet reports Escape, the platform close, the scrim tap and the swipe all as onOpenChange(false) with no reason, so the guard holds the step against all of them while it applies, and a veto of Escape alone has no equivalent; the only per-path lever is purpose (form keeps Escape and blocks the scrim tap and the swipe; required blocks all three and exposes the step as an alertdialog). A consumer aria-label or aria-labelledby becomes each step label, which names its dialog. ref, id, data-testid, className, style, xstyle and the other dialog props have no dialog-level equivalent: a standalone sheet sends its ref and base props to the panel div and its dialog is implementation, so a test or anchor that needs the dialog queries the panel closest("dialog"), and dialog-level styling is dropped.',
       },
       {
         guidance: false,
@@ -207,35 +207,31 @@ export const docs = {
       {
         guidance: false,
         description:
-          "Don't use the switcher when multiple panels must stay interactive or visible together; activeSheet intentionally selects one interactive step.",
+          "Don't use a step flow when multiple panels must stay interactive or visible together; a flow intentionally selects one interactive step.",
       },
     ],
   },
   examples: [
     {
-      label: 'Three-step flow',
-      code: `const [activeSheet, setActiveSheet] = useState(null);
+      label: 'Replacement: the same three-step flow as standalone sheets',
+      code: `const [step, setStep] = useState(null);
 
 <>
-  <Button label="Start" onClick={() => setActiveSheet('details')} />
-  <BottomSheetSwitcher
-    activeSheet={activeSheet}
-    onActiveSheetChange={setActiveSheet}>
-    <BottomSheet sheetId="details" label="Details" height="hug">
-      <SetupDetails />
-      <Button label="Continue" onClick={() => setActiveSheet('preferences')} />
-    </BottomSheet>
-    <BottomSheet sheetId="preferences" label="Preferences" height="hug">
-      <Preferences />
-      <Button label="Back" onClick={() => setActiveSheet('details')} />
-      <Button label="Continue" onClick={() => setActiveSheet('confirm')} />
-    </BottomSheet>
-    <BottomSheet sheetId="confirm" label="Confirm" height="hug">
-      <Confirmation />
-      <Button label="Back" onClick={() => setActiveSheet('preferences')} />
-      <Button label="Done" onClick={() => setActiveSheet(null)} />
-    </BottomSheet>
-  </BottomSheetSwitcher>
+  <Button label="Start" onClick={() => setStep('details')} />
+  <BottomSheet isOpen={step === 'details'} onOpenChange={o => !o && setStep(c => (c === 'details' ? null : c))} label="Details" height="hug">
+    <SetupDetails />
+    <Button label="Continue" onClick={() => setStep('preferences')} />
+  </BottomSheet>
+  <BottomSheet isOpen={step === 'preferences'} onOpenChange={o => !o && setStep(c => (c === 'preferences' ? null : c))} label="Preferences" height="hug">
+    <Preferences />
+    <Button label="Back" onClick={() => setStep('details')} />
+    <Button label="Continue" onClick={() => setStep('confirm')} />
+  </BottomSheet>
+  <BottomSheet isOpen={step === 'confirm'} onOpenChange={o => !o && setStep(c => (c === 'confirm' ? null : c))} label="Confirm" height="hug">
+    <Confirmation />
+    <Button label="Back" onClick={() => setStep('preferences')} />
+    <Button label="Done" onClick={() => setStep(null)} />
+  </BottomSheet>
 </>`,
     },
   ],
@@ -244,21 +240,21 @@ export const docs = {
 /** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
-    'controller for mutually exclusive multi-step BottomSheets, one native dialog per sheet',
+    'deprecated: use one standalone BottomSheet per step with one state value naming the open step (same replace handoff when stepped from inside the open step, no sheetId); keeps working until a future minor removes it. controller for mutually exclusive multi-step BottomSheets, one native dialog per sheet; a scrim flow is one level of the bottom-sheet stack (stacks over or under standalone sheets in open order, recedes as a whole, switching steps keeps its place)',
   usage: {
     anatomy,
     description:
-      "Coordinates a multi-step bottom-sheet flow, one native dialog per sheet; set activeSheet to a nested BottomSheet's sheetId to open or switch steps, and to null to close.",
+      "Deprecated: write each step as a standalone BottomSheet with isOpen driven by one state value; a same-update close and open from inside the open step is the same replace handoff. Still works: set activeSheet to a nested BottomSheet's sheetId to open or switch steps, and to null to close. A scrim flow stacks with standalone sheets as one level; a standalone sheet inside a step leaves when the step is left and returns with it while still open.",
     bestPractices: [
       {
         guidance: true,
         description:
-          'Use when each step depends on the previous one and only one step needs attention at a time.',
+          'Prefer one standalone BottomSheet per step with one state value naming the open step; the replace handoff is the same and nothing has to be nested under a switcher.',
       },
       {
         guidance: true,
         description:
-          'Give every child a unique sheetId and non-empty label, choose its purpose to match dismissal requirements, and follow the WAI-ARIA Dialog (Modal) pattern for scrim-backed flows: https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/.',
+          'Migrate an existing flow in place: replace activeSheet / onActiveSheetChange with one step value, give each step isOpen={step === id} and a guarded onOpenChange (clear the step only if it is still the open one) in place of sheetId, remove the wrapper and move its hasScrim onto every step. Map the other switcher props: onCancel becomes a guarded onOpenChange on each step (ignore false while the flow must stay open) — a standalone sheet reports Escape, the platform close, the scrim tap and the swipe all as onOpenChange(false) with no reason, so the guard holds the step against all of them while it applies, and a veto of Escape alone has no equivalent; the only per-path lever is purpose (form keeps Escape and blocks the scrim tap and the swipe; required blocks all three and exposes the step as an alertdialog). A consumer aria-label or aria-labelledby becomes each step label, which names its dialog. ref, id, data-testid, className, style, xstyle and the other dialog props have no dialog-level equivalent: a standalone sheet sends its ref and base props to the panel div and its dialog is implementation, so a test or anchor that needs the dialog queries the panel closest("dialog"), and dialog-level styling is dropped.',
       },
       {
         guidance: false,
@@ -268,7 +264,7 @@ export const docsDense = {
       {
         guidance: false,
         description:
-          "Don't use the switcher when multiple panels must stay interactive or visible together; activeSheet intentionally selects one interactive step.",
+          "Don't use a step flow when multiple panels must stay interactive or visible together; a flow intentionally selects one interactive step.",
       },
     ],
   },

package/src/BottomSheet/BottomSheetSwitcher.spec.md

@@ -7,12 +7,14 @@ authority: current
 archive_reason: null
 superseded_by: null
 approved_by: imdreamrunner
-approved_at: 2026-10-21
+approved_at: 2026-10-24
 owners: [cixzhang]
 review_triggers: [public-api, behavior, layout, theming, accessibility]
 verified_by:
   [
     packages/core/src/BottomSheet/BottomSheetSwitcher.test.tsx,
+    packages/core/src/BottomSheet/BottomSheetStacking.test.tsx,
+    packages/core/src/Toast/ToastViewport.modalHost.test.tsx,
     packages/core/src/BottomSheet/__tests__/BottomSheetNativeModal.a11y.browser.spec.ts,
     apps/storybook/stories/BottomSheetSwitcher.stories.tsx,
     scripts/check-knowledge.mjs,
@@ -27,7 +29,14 @@ architecture:
     architecture:public-component-api,
   ]
 contributing: []
-system_specs: [spec:AST-002, spec:AST-027]
+system_specs:
+  [
+    spec:AST-002,
+    spec:AST-027,
+    spec:AST-017/FR26,
+    spec:AST-017/FR28,
+    spec:AST-017/FR29,
+  ]
 ---
 
 # BottomSheetSwitcher component contract
@@ -36,22 +45,60 @@ system_specs: [spec:AST-002, spec:AST-027]
 
 BottomSheetSwitcher coordinates a mutually exclusive sequence of BottomSheet
 children, each presented in its own native dialog (DEC-1), without adding a
-prop or changing a default. Where the shipped switcher does not yet meet a
-requirement, the row carries a present-tense implementation gap note. The
+prop or changing a default. Its public lifecycle state is `deprecated`
+(`spec:AST-017` FR26, DEC-3, DEP-0015): it is supported and maintained, every
+requirement in this record stays in force, and the replacement — one standalone
+`BottomSheet` per step driven by one state value, which `component:BottomSheet`
+FR10 replaces in place when the step changes from inside the open step — is
+what maintained docs, templates, stories, and agent guidance teach. Removal
+happens only in a future declared minor through a `[breaking]` change. The
 modality, identifier, and theming questions below stay open.
 
 ## Compatibility and migration
 
 - Released default preserved: `yes`
 - Compatibility class: nonbreaking; public props, defaults, exports, visual
-  output, and transition behavior stay unchanged. The element the `ref` resolves
+  output, and transition behavior stay unchanged, except that under reduced
+  motion a handoff follows `design:reduced-motion` (FR3), a visual-only motion
+  change under `spec:AST-017` FR3. The element the `ref` resolves
   to, and that it changes on a handoff, is implementation rather than public
-  contract (DEC-2)
+  contract (DEC-2). A switcher flow presented on its own behaves as released,
+  with one fix: a toast raised from a step renders above the flow and can be
+  pressed (FR10, `component:BottomSheet` FR13), where it rendered behind the
+  flow before.
+  A switcher flow presented while other sheets are open is one level of the
+  stack `component:BottomSheet` FR12 describes; that is behavior of the stack,
+  not a change to the switcher's own contract
+- Lifecycle: `deprecated` (DEC-3, DEP-0015). Deprecation adds no production
+  runtime behavior and no warning in a rendered application (`spec:AST-017`
+  FR29); the `@deprecated` metadata lives on the TypeScript declarations of
+  `BottomSheetSwitcher`, `BottomSheetSwitcherProps`, and `BottomSheet`'s
+  `sheetId`, and the consumer docs carry the replacement route (FR29a, FR29b).
 - Controlled/uncontrolled behavior: `activeSheet` remains fully controlled
-- Migration decision: none
+- Migration decision: DEC-3; the migration is DEP-0015's
 
 Consumer migration instructions belong in consumer docs and release notes.
 
+### DEP-0015 — Deprecate `BottomSheetSwitcher` in favour of standalone step sheets
+
+| Field            | Value                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| id               | `DEP-0015`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| cleanup          | none yet; the removal is decided for a future declared minor                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| package          | `@astryxdesign/core`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| surface          | `BottomSheetSwitcher`, `BottomSheetSwitcherProps`, and the `sheetId` prop of `BottomSheet`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| old contract     | A multi-step flow is a `BottomSheetSwitcher` whose `activeSheet` names one nested `BottomSheet` by `sheetId`; stepping runs the handoff of FR2–FR3 and FR8                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| replacement      | One standalone `BottomSheet` per step with `isOpen={step === id}`, driven by one state value; closing the open step and opening the next in the same update, from a control inside the open step (or from code while focus is in it), runs the same handoff (`component:BottomSheet` FR10), for modal and `hasScrim={false}` flows alike. A step changed by a control outside the flow's sheets — a page control beside a non-modal flow, or code acting while focus is on a page control — is a close and an open with their own push and pop motion, where the switcher ran its handoff on any `activeSheet` change; code acting while focus is in the step or on the document body still runs the handoff (`component:BottomSheet` FR10's actor is inside the step, or none)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| direct authority | DEC-3 here; `component:BottomSheet` DEC-2 and FR10 own the replacement's behavior. Owners: `cixzhang`, `imdreamrunner`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| warning          | `@deprecated` on the declarations; consumer docs, templates, stories, and release notes name the replacement. No runtime warning (`spec:AST-017` FR29)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| migration        | Ordered and testable, per flow: (1) replace `activeSheet` / `onActiveSheetChange` with one `step` value; (2) give each step `isOpen={step === 'id'}` and `onOpenChange={isOpen => !isOpen && setStep(current => (current === 'id' ? null : current))}` in place of `sheetId="id"`; (3) remove the wrapper, moving its `hasScrim` onto every step; (4) keep the step controls as they are (`setStep('next')`); (5) a flow stepped by a control outside its sheets (a page control beside a non-modal flow, or code acting while focus is on a page control) gets push and pop motion in place of the handoff — move such a control into the step, or accept the motion; code acting while focus is in the step or on the body keeps the handoff; (6) the switcher's other props: `onCancel` becomes a guarded `onOpenChange` on each step — one that ignores `false` while the flow must stay open — which keeps the step's dialog role; a standalone sheet reports Escape, the platform close, the scrim tap, and the swipe all as `onOpenChange(false)` with no reason, so the guard holds the step open against all of them while it applies, where the switcher's `onCancel` vetoed only the cancel request; a veto of Escape alone has no equivalent, and the only per-path lever is `purpose` (`form` keeps Escape and blocks the scrim tap and the swipe; `required` blocks all three and exposes the step as an `alertdialog`); there is no per-event veto; a consumer `aria-label` / `aria-labelledby` becomes each step's `label`, which names its dialog; `ref`, `id`, `data-testid`, `className`, `style`, `xstyle`, and the other dialog props have no dialog-level equivalent — a standalone sheet's `ref` and base props reach its panel `<div>` and its dialog is implementation — so a test or an anchor that needs the dialog queries the panel's `closest('dialog')`, and dialog-level styling is dropped |
+| codemod          | None; the rewrite moves state the caller owns and is short enough to read                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| downstream       | The maintained published surfaces migrate in the deprecation patch (`spec:AST-017` FR29c): the CLI block templates and the stories. `@astryxdesign/lab` is marked `private` and is published to npm only under the `@canary` dist-tag, never as a stable `latest` release; `spec:AST-017` calls it "the private canary-only Lab package" (FR27), lists private packages among its non-goals, puts them outside the published compatibility promise (FR2), and says canary-only surfaces carry no stable compatibility promise, which this record reads as FR29c's "maintained Astryx packages" not reaching Lab, so Lab's migration is optional under it: Lab's `MobileTokenizer` and `MobilePowerSearch` are migrated, so no maintained surface uses the switcher. Whether `spec:AST-017` is read that way is its owner's to settle. The switcher's own stories remain as its labelled reference.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| transition       | no prior transition                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| state            | `deprecated`: supported, documented with its replacement, unchanged at runtime — the deprecation patch `spec:AST-017` FR28 requires before a removal, projected through declarations and docs (FR29a, FR29b).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| open decision    | Which declared minor removes the surface, and whether a renamed compatibility export precedes the removal; either is a `[breaking]` change of a declared minor (`spec:AST-017` FR28, FR31)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| target plan      | Removal in a future declared minor through a `[breaking]` Changeset; no release is named                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+
 ## Ownership boundary
 
 **Owns**
@@ -73,32 +120,35 @@ Consumer migration instructions belong in consumer docs and release notes.
   local visual styling — owned by `component:BottomSheet`.
 - Page-level stacking or clipping escape — owned by
   `architecture:layer-runtime` and `spec:AST-027`.
-- An ordered visible sheet stack — proposed separately by open `BottomSheetStack`
-  work and not part of this component.
+- The stack of presented sheets, its order, its one visible scrim, and the
+  replace handoff between standalone sheets — owned by `component:BottomSheet`
+  DEC-2. A switcher flow takes part as one level (FR10 here, FR12 there); it
+  does not order itself against other sheets.
 
 ## Public concepts
 
-| Concept             | Closed values or states                              | Meaning                                                                                                                                                                                                      | Availability by variant/orientation/state                                      | Default                                | Owner                                                                     | Stability | Invalid-value behavior                                                                     |
-| ------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ | -------------------------------------- | ------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------ |
-| Active sheet        | `null` or one nested BottomSheet `sheetId`           | Selects the only interactive child, or closes the flow                                                                                                                                                       | All presentations                                                              | `null` is closed; the prop is required | `component:BottomSheetSwitcher`                                           | released  | A non-matching or duplicate id is not given a safe public fallback by the current contract |
-| Shared presentation | `true` / `false` through `hasScrim`                  | Selects the current modal scrim-backed host or non-modal no-scrim host                                                                                                                                       | Entire flow                                                                    | `true`                                 | `component:BottomSheetSwitcher`                                           | released  | Boolean only                                                                               |
-| Child identity      | Non-empty `sheetId` on each direct BottomSheet child | Associates controlled selection, labeling, purpose, and transition state with a child                                                                                                                        | Direct nested BottomSheet children                                             | none                                   | `component:BottomSheet`                                                   | released  | Empty ids warn and stay hidden; duplicate-id behavior is not specified                     |
-| Dismissal request   | `onActiveSheetChange(null)`                          | Reports an allowed implicit close without taking control from the caller                                                                                                                                     | Escape/platform close, scrim click, or swipe according to active child purpose | none                                   | `component:BottomSheetSwitcher`; `family:overlay-dismissal` owns ordering | released  | The caller may retain its controlled value                                                 |
-| Dialog surface      | inherited dialog props plus `ref` and `onCancel`     | Dialog props and handlers, `onCancel` included, reach every sheet dialog; `ref`, `id`, and `data-testid` resolve to the host dialog, which is never null for an object ref while a sheet is mounted (DEC-2). | Entire flow                                                                    | none                                   | `component:BottomSheetSwitcher`                                           | released  | Component-owned semantics and handlers retain precedence                                   |
+| Concept             | Closed values or states                              | Meaning                                                                                                                                                                                                      | Availability by variant/orientation/state                                      | Default                                | Owner                                                                     | Stability             | Invalid-value behavior                                                                     |
+| ------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ | -------------------------------------- | ------------------------------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------ |
+| Active sheet        | `null` or one nested BottomSheet `sheetId`           | Selects the only interactive child, or closes the flow                                                                                                                                                       | All presentations                                                              | `null` is closed; the prop is required | `component:BottomSheetSwitcher`                                           | deprecated (DEP-0015) | A non-matching or duplicate id is not given a safe public fallback by the current contract |
+| Shared presentation | `true` / `false` through `hasScrim`                  | Selects the current modal scrim-backed host or non-modal no-scrim host                                                                                                                                       | Entire flow                                                                    | `true`                                 | `component:BottomSheetSwitcher`                                           | deprecated (DEP-0015) | Boolean only                                                                               |
+| Child identity      | Non-empty `sheetId` on each direct BottomSheet child | Associates controlled selection, labeling, purpose, and transition state with a child                                                                                                                        | Direct nested BottomSheet children                                             | none                                   | `component:BottomSheet`                                                   | deprecated (DEP-0015) | Empty ids warn and stay hidden; duplicate-id behavior is not specified                     |
+| Dismissal request   | `onActiveSheetChange(null)`                          | Reports an allowed implicit close without taking control from the caller                                                                                                                                     | Escape/platform close, scrim click, or swipe according to active child purpose | none                                   | `component:BottomSheetSwitcher`; `family:overlay-dismissal` owns ordering | deprecated (DEP-0015) | The caller may retain its controlled value                                                 |
+| Dialog surface      | inherited dialog props plus `ref` and `onCancel`     | Dialog props and handlers, `onCancel` included, reach every sheet dialog; `ref`, `id`, and `data-testid` resolve to the host dialog, which is never null for an object ref while a sheet is mounted (DEC-2). | Entire flow                                                                    | none                                   | `component:BottomSheetSwitcher`                                           | deprecated (DEP-0015) | Component-owned semantics and handlers retain precedence                                   |
 
 ## Behavioral and layout contract
 
-| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Basis                                                    |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
-| FR1 | Zero or one child sheet is interactive for each controlled `activeSheet` value; all other children are hidden or retained inert and `aria-hidden` during a transition.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Current source, docs, and tests                          |
-| FR2 | Each child sheet owns one native dialog. Opening a sheet presents its dialog once; a handoff presents the entering sheet's dialog above the retained one and closes the retained dialog only after its panel has faded. Returning to a sheet whose dialog is still open beneath a newer one re-presents it so the interactive sheet is the topmost layer.                                                                                                                                                                                                                                                                                                                                   | DEC-1                                                    |
-| FR3 | During a handoff, the entering sheet is above the retained sheet. A taller retained sheet aligns down to a shorter entering sheet, and the retained sheet fades only after required transform motion completes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Current source and transition tests                      |
-| FR4 | Closing retains the outgoing sheet through its exit, then closes the dialog. A modal flow restores focus to the element captured when that modal flow opened.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Current source and focus tests                           |
-| FR5 | `hasScrim=true` uses `showModal()`, a native backdrop, and native focus containment, and locks page scroll: the page does not scroll while a modal flow is presented; the lock is held continuously across a handoff, never released and re-acquired between steps; it still holds beneath a `Dialog` opened from a step; it is released after the flow's exit (DEC-1). `hasScrim=false` uses `show()` without a backdrop or scroll lock and leaves the page interactive. In a non-modal flow the sheet dialogs order themselves with local values inside the switcher's isolated flow wrapper (DEC-1); the page-level value that wrapper carries remains a `spec:AST-027` conformance gap. | DEC-1; `spec:AST-027` FR2, FR4, FR8                      |
-| FR6 | The active child purpose governs implicit dismissal: `info` allows Escape, scrim click, and swipe; `form` allows Escape; `required` blocks all three and exposes `alertdialog`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Current BottomSheet docs and switcher tests              |
-| FR7 | While visible, the switcher participates in `family:overlay-dismissal`; one Escape or platform close request reaches only the topmost present layer, and descendants receive a deeper logical layer scope.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `family:overlay-dismissal` and the audit regression test |
-| FR8 | One backdrop paints the flow's scrim at a time: the retained sheet's dialog keeps it through a handoff and the entering dialog takes it over without a fade when the retained dialog closes. A stale gesture from an outgoing sheet cannot change the flow's scrim, and unmounting a retained sheet cannot keep its dialog open or the flow's modal layer held.                                                                                                                                                                                                                                                                                                                             | DEC-1; current tests                                     |
-| FR9 | The switcher forwards neutral dialog attributes, styling inputs, and composed handlers, `onCancel` included, to every sheet dialog, so a handler fires for whichever sheet dialog raises the event; renders `id` and `data-testid` on the host dialog only, so each appears once in the document; attaches its ref to the host dialog; and preserves its owned ARIA and dismissal behavior. An object ref's `current` is never `null` while a sheet is mounted. A callback ref follows React's semantics on a handoff: a cleanup it returned runs when it detaches from the old host; a callback ref without a cleanup is called with `null` on detach, then with the new host.             | DEC-1, DEC-2; `architecture:public-component-api` INV8   |
+| ID   | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Basis                                                                 |
+| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------- |
+| FR1  | Zero or one child sheet is interactive for each controlled `activeSheet` value; all other children are hidden or retained inert and `aria-hidden` during a transition.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Current source, docs, and tests                                       |
+| FR2  | Each child sheet owns one native dialog. Opening a sheet presents its dialog once; a handoff presents the entering sheet's dialog above the retained one and closes the retained dialog only after its panel has faded. Returning to a sheet whose dialog is still open beneath a newer one re-presents it so the interactive sheet is the topmost layer.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | DEC-1                                                                 |
+| FR3  | During a handoff, the entering sheet is above the retained sheet. A taller retained sheet aligns down to a shorter entering sheet, and the retained sheet fades only after required transform motion completes. Under reduced motion the handoff follows `design:reduced-motion`: no transform motion runs, and the sheets cross-fade (DR2) or change at once (DR3) in the same order.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Current source and transition tests; `design:reduced-motion` DR2, DR3 |
+| FR4  | Closing retains the outgoing sheet through its exit, then closes the dialog. A modal flow restores focus to the element captured when that modal flow opened.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Current source and focus tests                                        |
+| FR5  | `hasScrim=true` uses `showModal()`, a native backdrop, and native focus containment, and locks page scroll: the page does not scroll while a modal flow is presented; the lock is held continuously across a handoff, never released and re-acquired between steps; it still holds beneath a `Dialog` opened from a step; it is released after the flow's exit (DEC-1). `hasScrim=false` uses `show()` without a backdrop or scroll lock and leaves the page interactive. In a non-modal flow the sheet dialogs order themselves with local values inside the switcher's isolated flow wrapper (DEC-1); the page-level value that wrapper carries remains a `spec:AST-027` conformance gap.                                                                                                                                                                                                                                                                                                                        | DEC-1; `spec:AST-027` FR2, FR4, FR8                                   |
+| FR6  | The active child purpose governs implicit dismissal: `info` allows Escape, scrim click, and swipe; `form` allows Escape; `required` blocks all three and exposes `alertdialog`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Current BottomSheet docs and switcher tests                           |
+| FR7  | While visible, the switcher participates in `family:overlay-dismissal`; one Escape or platform close request reaches only the topmost present layer, and descendants receive a deeper logical layer scope.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `family:overlay-dismissal` and the audit regression test              |
+| FR8  | One backdrop paints the flow's scrim at a time: the retained sheet's dialog keeps it through a handoff and the entering dialog takes it over without a fade when the retained dialog closes. A stale gesture from an outgoing sheet cannot change the flow's scrim, and unmounting a retained sheet cannot keep its dialog open or the flow's modal layer held.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | DEC-1; current tests                                                  |
+| FR10 | Presented while other modal sheets are open, a modal switcher flow is one level of the `component:BottomSheet` stack: the active step's dialog is the level and keeps the flow's place across the flow's own handoffs; when covered, the flow's dialogs recede and are blocked as covered sheets are, its backdrop is transparent while a lower sheet owns the one scrim, and its dismissal registration stands down; when it closes over a lower sheet, focus returns into that sheet by `component:BottomSheet` FR9. A modal flow's host dialog is a passive global outlet for toasts like a standalone scrim sheet's, following each handoff and ranked among sheets by the stack (`component:BottomSheet` FR13). Under reduced motion a flow's steps move as `component:BottomSheet` FR15 says, the same panel motion as standalone sheets (FR3). A standalone sheet rendered in a step's content stacks above the flow and leaves with the step. A step is never paired in a replace with a standalone sheet. | `component:BottomSheet` DEC-2, FR12                                   |
+| FR9  | The switcher forwards neutral dialog attributes, styling inputs, and composed handlers, `onCancel` included, to every sheet dialog, so a handler fires for whichever sheet dialog raises the event; renders `id` and `data-testid` on the host dialog only, so each appears once in the document; attaches its ref to the host dialog; and preserves its owned ARIA and dismissal behavior. An object ref's `current` is never `null` while a sheet is mounted. A callback ref follows React's semantics on a handoff: a cleanup it returned runs when it detaches from the old host; a callback ref without a cleanup is called with `null` on detach, then with the new host.                                                                                                                                                                                                                                                                                                                                    | DEC-1, DEC-2; `architecture:public-component-api` INV8                |
 
 ### Allowed variation
 
@@ -110,20 +160,23 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ### Representative states
 
-| State      | Required invariant                                                                                                                                                               | Allowed variation                                                                        |
-| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
-| Closed     | Every sheet dialog is closed and no child is interactive.                                                                                                                        | Child panels may remain mounted but hidden.                                              |
-| First open | Matching child is visible and interactive in its own dialog.                                                                                                                     | Child-owned height and content.                                                          |
-| Handoff    | Entering child is interactive in its own dialog; retained child's dialog stays open, inert, and hidden from accessibility APIs until it fades, and keeps painting the one scrim. | Alignment offset depends on measured panel geometry.                                     |
-| Closing    | Outgoing child is retained inert while exit motion completes; modal focus and scroll ownership remain until close.                                                               | Theme-controlled duration.                                                               |
-| Modal      | Native modal host, backdrop, native focus containment, and the page scroll lock are active.                                                                                      | Active child's `purpose` controls implicit dismissal.                                    |
-| Non-modal  | Native non-modal host has no backdrop or scroll lock and background content remains interactive.                                                                                 | The current clipping/stacking limitation is a conformance gap, not an allowed exception. |
+| State      | Required invariant                                                                                                                                                                                                                                                                                  | Allowed variation                                                                        |
+| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| Closed     | Every sheet dialog is closed and no child is interactive.                                                                                                                                                                                                                                           | Child panels may remain mounted but hidden.                                              |
+| First open | Matching child is visible and interactive in its own dialog.                                                                                                                                                                                                                                        | Child-owned height and content.                                                          |
+| Handoff    | Entering child is interactive in its own dialog; retained child's dialog stays open, inert, and hidden from accessibility APIs until it fades, and keeps painting the one scrim when the flow owns it — transparent while a lower sheet owns the stack's scrim (FR10, `component:BottomSheet` FR6). | Alignment offset depends on measured panel geometry.                                     |
+| Closing    | Outgoing child is retained inert while exit motion completes; modal focus and scroll ownership remain until close.                                                                                                                                                                                  | Theme-controlled duration.                                                               |
+| Modal      | Native modal host, backdrop, native focus containment, and the page scroll lock are active.                                                                                                                                                                                                         | Active child's `purpose` controls implicit dismissal.                                    |
+| Non-modal  | Native non-modal host has no backdrop or scroll lock and background content remains interactive.                                                                                                                                                                                                    | The current clipping/stacking limitation is a conformance gap, not an allowed exception. |
+| Stacked    | The flow is covered by, or covers, standalone modal sheets: as a covered level its dialogs recede and are blocked and one scrim is visible for the whole stack (FR10).                                                                                                                              | Recede geometry under `component:BottomSheet` DEC-2.                                     |
 
 ### Transformation and precedence order
 
 - **ORD1 — Handoff completion.** Select next child → mark previous child retained
   and inert → start entering transform and any required retained alignment → wait
-  for both transforms → fade retained child → hide it.
+  for both transforms → fade retained child → hide it. Under reduced motion the
+  transform steps are skipped and the entering and retained children cross-fade
+  or change at once (`design:reduced-motion` DR2, DR3), keeping this order.
 - **ORD2 — Label precedence.** Consumer `aria-label` wins; otherwise consumer
   `aria-labelledby` wins; otherwise the active or retained child label names the
   dialog.
@@ -189,16 +242,25 @@ Consumer migration instructions belong in consumer docs and release notes.
 - `architecture:public-component-api` and `spec:AST-002` own the released prop,
   DOM, ref, and compatibility surface.
 - `spec:AST-027` identifies the non-modal `show()` plus page-level `z-index` path
-  as a migration gap, not an exception.
+  as a migration gap, not an exception. The standalone sheet's non-modal path
+  is hosted in the top layer (`component:BottomSheet` FR11); the switcher's
+  own non-modal flow wrapper keeps the gap, which its deprecation leaves to be
+  closed by removal rather than by re-hosting.
+- `spec:AST-017` FR26, FR28, and FR29 govern the lifecycle state, the
+  deprecation patch, and the no-runtime-warning rule that DEP-0015 follows.
+- `component:BottomSheet` DEC-2 owns the stack a flow takes part in and the
+  replacement pattern the deprecation points to.
 
 ## Verification map
 
-| Contract         | Verification                                                                  | Representative states                                                                                                  | Mutation or failure expectation                                                                                                                                              | Audit section                             |
-| ---------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
-| FR1–FR4, FR8     | `BottomSheetSwitcher.test.tsx`                                                | closed, first open, handoffs in either completion order, rapid replacement, unmount, close                             | A child becomes interactive at the wrong time, a retained child disappears early, a second backdrop paints, or a sheet dialog's lifecycle breaks.                            | `audit:BottomSheetSwitcher/behavior`      |
-| FR5–FR7, AR1–AR3 | `BottomSheetSwitcher.test.tsx`; `BottomSheetNativeModal.a11y.browser.spec.ts` | modal/non-modal, info/form/required, nested layer, IME, focus return, scroll lock in engines, non-modal local ordering | Modality, dismissal order, naming, inertness, scroll lock, or focus behavior diverges, or a sheet dialog takes a page-level z-index.                                         | `audit:BottomSheetSwitcher/accessibility` |
-| FR9              | `BottomSheetSwitcher.test.tsx`; export checks                                 | ref across open/handoff/close/unmount, callback-ref cleanup, `id` once, DOM/ARIA/data/events, class, style, xstyle     | A supported input is dropped or duplicated, an object ref is null while a sheet is mounted or skips a cleanup, or an input overrides component-owned semantics accidentally. | `audit:BottomSheetSwitcher/api`           |
-| Theming anatomy  | `scripts/check-knowledge.mjs`; theming tests                                  | dialog, delegated sheet panel, scrim                                                                                   | A non-painting host gains a target, a delegated panel loses its owner, or the scrim gap disappears without review.                                                           | `audit:BottomSheetSwitcher/theming`       |
+| Contract         | Verification                                                                                                                                                                          | Representative states                                                                                                                                     | Mutation or failure expectation                                                                                                                                                                                                                   | Audit section                             |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
+| FR1–FR4, FR8     | `BottomSheetSwitcher.test.tsx`                                                                                                                                                        | closed, first open, handoffs in either completion order, rapid replacement, unmount, close; a handoff under reduced motion on a coarse and a fine pointer | A child becomes interactive at the wrong time, a retained child disappears early, a second backdrop paints, or a sheet dialog's lifecycle breaks. Under reduced motion, a handoff that moves a sheet, or on a coarse pointer does not cross-fade. | `audit:BottomSheetSwitcher/behavior`      |
+| FR5–FR7, AR1–AR3 | `BottomSheetSwitcher.test.tsx`; `BottomSheetNativeModal.a11y.browser.spec.ts`                                                                                                         | modal/non-modal, info/form/required, nested layer, IME, focus return, scroll lock in engines, non-modal local ordering                                    | Modality, dismissal order, naming, inertness, scroll lock, or focus behavior diverges, or a sheet dialog takes a page-level z-index.                                                                                                              | `audit:BottomSheetSwitcher/accessibility` |
+| FR9              | `BottomSheetSwitcher.test.tsx`; export checks                                                                                                                                         | ref across open/handoff/close/unmount, callback-ref cleanup, `id` once, DOM/ARIA/data/events, class, style, xstyle                                        | A supported input is dropped or duplicated, an object ref is null while a sheet is mounted or skips a cleanup, or an input overrides component-owned semantics accidentally.                                                                      | `audit:BottomSheetSwitcher/api`           |
+| Theming anatomy  | `scripts/check-knowledge.mjs`; theming tests                                                                                                                                          | dialog, delegated sheet panel, scrim                                                                                                                      | A non-painting host gains a target, a delegated panel loses its owner, or the scrim gap disappears without review.                                                                                                                                | `audit:BottomSheetSwitcher/theming`       |
+| FR10             | `component:BottomSheet`'s stacking suite (the switcher-as-a-level cases); real-browser dim and recede sampling of a flow stacked over, and under, a standalone sheet                  | switcher base covered by a standalone sheet, switcher on top of a standalone sheet, a sheet in a step's content, flow closing over a lower sheet          | Two backdrops paint, the covered level does not recede, a covered flow takes Escape, or focus lands on `body` when the flow closes over a sheet.                                                                                                  | `audit:BottomSheetSwitcher/behavior`      |
+| DEP-0015         | Declaration and consumer-doc inspection (the switcher's and `component:BottomSheet`'s consumer doc); `@deprecated` metadata on the three declarations; CLI template and story sources | the switcher's declarations, docs, templates, and stories, and BottomSheet's consumer doc                                                                 | A declaration lacks `@deprecated`, a maintained template, story or BottomSheet's consumer doc teaches the switcher as the multi-step route, or a production runtime branch, log, or output changes with the deprecation.                          | `audit:BottomSheetSwitcher/api`           |
 
 ## Decision log
 
@@ -256,6 +318,39 @@ visual output and no public API surface changes.
 Rejected: classifying the moving ref as a breaking change, because no public
 API, documented interaction, or visual output changes.
 
+### DEC-3 — The switcher is deprecated in favour of standalone step sheets
+
+**Reference:** `component:BottomSheetSwitcher/DEC-3`
+**Decider:** imdreamrunner, 2026-10-23
+
+A multi-step flow is written as one standalone `BottomSheet` per step driven
+by one state value; closing the open step and opening the next in the same
+update, from a control inside the open step or from code while focus is in
+it, runs the handoff the switcher runs between its steps
+(`component:BottomSheet` FR10), with no `sheetId` and no wrapper, for modal
+and non-modal flows alike. The one case the replacement treats differently is
+a step changed by a control outside the flow's sheets — a page control
+beside a non-modal flow, or code acting while focus is on a page control —
+which the switcher hands off and the standalone sheets close and open with
+their own motion, because from outside the sheets a close and an open are two
+sheets' own changes, not one person's move between steps; code acting while
+focus is in the step or on the document body keeps the handoff
+(`component:BottomSheet` FR10: the actor is inside the step, or none). The switcher therefore has no
+job of its own left
+and is `deprecated` (DEP-0015): it keeps working as released, every
+requirement of this record stays in force, its declarations carry
+`@deprecated`, maintained docs and templates teach the replacement, and no
+production runtime behavior changes. The removal is a `[breaking]` change of a
+future declared minor (`spec:AST-017` FR28, FR31) and is not decided here.
+Rejected: keeping the switcher as the one supported flow API, because the
+same handoff then needs two implementations and callers must choose between
+two mental models for one UI.
+Rejected: removing the switcher in the same release that ships the
+replacement, because a patch cannot carry a `[breaking]` change
+(`spec:AST-017` FR25, FR31) and released flows must keep working.
+Rejected: a development-mode warning on render, because a whole-component
+deprecation projects through its declarations and docs (`spec:AST-017` FR29).
+
 ## Open questions
 
 - **OQ1 — Should modality and scrim paint remain coupled behind `hasScrim`, or