Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs: define layer runtime architecture (#5741)

Cindy Zhang397e0c68be33
diff --git a/docs/architecture/layer-runtime.md b/docs/architecture/layer-runtime.md
new file mode 100644
index 0000000000..c78cb823f0
--- /dev/null
+++ b/docs/architecture/layer-runtime.md
@@ -0,0 +1,329 @@
+---
+schema_version: 1
+template_version: 1
+kind: architecture
+id: architecture:layer-runtime
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-08-30
+owners: [cixzhang, imdreamrunner]
+applies_to:
+ [
+ packages/core/src/Layer/,
+ packages/core/src/Popover/,
+ packages/core/src/Dialog/,
+ packages/core/src/DropdownMenu/,
+ packages/core/src/Tooltip/,
+ packages/core/src/HoverCard/,
+ packages/core/src/Toast/,
+ packages/core/src/CommandPalette/,
+ packages/core/src/hooks/useFocusTrap.ts,
+ packages/core/src/hooks/useMenuHover.ts,
+ ]
+verified_by:
+ [
+ packages/core/src/Layer/useLayer.test.tsx,
+ packages/core/src/Layer/layerHost.test.ts,
+ packages/core/src/Layer/anchorName.test.ts,
+ packages/core/src/Layer/useLayerDismissal.test.tsx,
+ packages/core/src/Layer/layerDismissalInvariants.test.tsx,
+ packages/core/src/Popover/Popover.test.tsx,
+ packages/core/src/DropdownMenu/DropdownMenu.test.tsx,
+ packages/core/src/DropdownMenu/DropdownMenuSubMenu.test.tsx,
+ packages/core/src/hooks/useFocusTrap.test.tsx,
+ packages/core/src/hooks/useMenuHover.test.tsx,
+ packages/core/src/Toast/ToastViewport.test.tsx,
+ ]
+deciding_specs: []
+---
+
+# Layer runtime
+
+This record describes the layer runtime shipped on current `main`. Accepted but
+unimplemented changes live in `spec:AST-003`; they are not current architecture.
+
+## Purpose
+
+Layered UI must escape clipping, stay positioned against its trigger, preserve
+nearby theme and writing context, and reconcile browser-owned visibility with
+React state.
+
+This record separates DOM hosting, browser top-layer promotion, positioning, and
+current dismissal plumbing. A component does not inherit every behavior merely
+because it uses one of those mechanisms.
+
+## System model
+
+### Browser hosts and corrective portals
+
+A browser host determines whether and how a surface enters the browser's top
+layer:
+
+- `popover="auto"` provides native top-layer promotion, light dismissal, close
+ requests, and the browser's auto-popover stack;
+- `popover="manual"` provides top-layer promotion without native light dismissal
+ or auto-popover exclusivity;
+- `dialog.showModal()` provides a native modal boundary, backdrop, inert outside
+ content, and platform close requests;
+- `dialog.show()` provides a non-modal dialog in its containing context; and
+- ordinary DOM rendering provides none of those browser guarantees.
+
+A React portal changes DOM placement. It is not itself a top-layer host and
+cannot use `z-index` to outrank a native modal dialog.
+
+`useLayer` keeps a context layer at its JSX position when that position is safe.
+When parsing, interactive-content, or inline-formatting constraints make that
+position unsafe, it portals only beyond the outermost unsafe ancestor. A
+persistent `<template>` marker preserves the intended position so the host can be
+resolved again when the render call moves. The nearest safe host preserves live
+CSS custom-property inheritance; direction and writing mode are copied only when
+the portal would otherwise lose them.
+
+A normal React portal retains React context. `architecture:theme-application`
+owns Theme provider behavior; this record owns where a layer's DOM is hosted.
+
+### Positioning
+
+`useLayer` has three positioning modes:
+
+- **context / anchor:** the trigger receives a unique CSS `anchor-name`; the
+ surface receives `position-anchor`, logical `position-area`, and ordered
+ fallback positions;
+- **context / custom:** the trigger and `position-anchor` relationship remain,
+ while the caller owns geometry, fallback, offset, and direction handling; and
+- **fixed:** the caller supplies viewport `x` and `y` coordinates and receives no
+ CSS-anchor geometry.
+
+Anchor names form a list so several layers may share one trigger without
+clobbering one another. Standard placement uses the `self-*` logical keyword
+family so inherited direction controls RTL behavior. Every anchored placement
+can flip across either axis. Centered placements also gain span fallbacks so the
+surface can move along the alignment axis near viewport edges. Clearance is
+applied to both edges of the placement axis so a flip retains the gap.
+
+Popover adds component-specific viewport sizing and overflow behavior above this
+geometry. Those constraints are not universal Layer behavior.
+
+### Current browser support behavior
+
+Native Popover API plus CSS Anchor Positioning provide the complete behavior
+implemented by the main path: top-layer promotion, native light dismiss,
+auto-popover stacking and association, logical anchor geometry, and browser
+fallback placement.
+
+When `showPopover` or `hidePopover` is unavailable, `useLayer` falls back to
+changing `display`. Explicit component controls can still show and hide mounted
+content, callbacks and React state still update, and fixed coordinates still
+apply. This fallback does not reproduce top-layer promotion, native outside or
+close-request behavior, auto-popover exclusivity or nesting, invoker focus order,
+anchored geometry, or collision fallbacks.
+
+Public docs do not yet state this reduced behavior as a support boundary. The
+accepted support contract and documentation change are owned by `spec:AST-003`.
+
+### Current Popover lifecycle and light dismissal
+
+Public `useLayer` defaults to `popover="manual"`; Popover-family APIs normally
+select `popover="auto"`. Browser-initiated closes are observed through the queued
+`toggle` event. The browser may already have hidden the surface before `isOpen`,
+`onHide`, or controlled-state synchronization catches up.
+
+`gestureCounter` identifies the physical pointer or keyboard gesture in flight.
+`useLayer` records the gesture associated with a browser close and
+`wasJustDismissed()` prevents that same press from reopening a trigger.
+DropdownMenu and Selector-family trigger paths consume this guard.
+
+`useMenuHover` adds a real native invoker relationship for applicable auto
+popovers. It separately suppresses the synthetic `mouseenter` produced when a
+closing panel exposes a stationary trigger, while allowing a genuine later hover.
+
+Controls that sit beside an open layer can temporarily gain `popovertarget`
+during a press so native light dismissal does not mistake them for outside
+interaction. Their click action is cancelled as an invoker toggle so the control
+can perform its own action without closing the layer.
+
+### Current dismissal plumbing
+
+`family:overlay-dismissal` owns the shipped Escape/platform-close membership
+contract. The current shared stack registers present layers with `close` or
+`block` behavior and orders them by logical depth, DOM containment, then stable
+registration sequence. `useFocusTrap` adapts an active trap with `onEscape` into
+that stack.
+
+Tooltip, HoverCard, Dialog, Popover, DropdownMenu, Lightbox, and MobileNav all
+register with the shared stack. Tooltip and HoverCard report current DOM presence;
+Popover and DropdownMenu register through `useFocusTrap`; Dialog, Lightbox, and
+MobileNav additionally ask `shouldDismissOnCloseRequest()` before acting on native
+platform close requests. Other family members still use local Escape handling as
+listed in `family:overlay-dismissal`.
+
+Outside interaction is not coordinated by the shared stack. Current paths are
+independent:
+
+- auto popovers use native light dismiss;
+- native dialogs handle backdrop clicks locally;
+- ContextMenu uses a local outside `mousedown` listener;
+- Tooltip and HoverCard use hover/focus loss plus a touch-only outside listener;
+- sheets own scrim and swipe behavior; and
+- dropdown submenus encode their root-close relationship locally through
+ `DropdownMenuContext`.
+
+The shared stack exposes `isTopmostLayer()`, but current outside, backdrop, touch,
+and swipe paths do not use it. There is no shared interaction-owner role,
+association graph, branch registry, or outside-branch resolution operation on
+current `main`.
+
+### Current global and nonparticipating surfaces
+
+LayerProvider supplies Toast configuration and mounts ToastViewport. It is not a
+general portal host for all layers. Without a provider, `useToast` creates a
+separate React root under `document.body` and mirrors root theme attributes onto
+it.
+
+ToastViewport uses `popover="manual"` for top-layer promotion and documents an
+above-dialog intent. A body-level manual popover remains behind an active native
+modal, so the current root/fallback host does not fulfill that intent. Toast
+state also lives inside the viewport.
+
+CommandPalette composes native Dialog. Its normal launcher presentation therefore
+uses `showModal()`; its documentation/showcase `isInline` path does not. It
+currently handles Escape on its own element as well as composing Dialog.
+
+Banner and FieldStatus are in-flow. `useAnnounce` is nonvisual. AlertDialog,
+imperative Dialog, Lightbox, and ordinary Popover-family surfaces are
+interaction-local. `useKeyboardHint`, Carousel's control overlay, and visual-only
+layers use Layer rendering without joining Escape/platform dismissal.
+
+## Boundaries and invariants
+
+- **INV1 — Corrective portals preserve locality.** A context layer stays inline
+ when safe and otherwise moves only outside the outermost unsafe ancestor.
+- **INV2 — Hosting and promotion are separate.** A React portal moves DOM. Native
+ Popover or modal Dialog APIs control top-layer participation and modal
+ boundaries.
+- **INV3 — Positioning modes do not leak.** Anchor mode owns logical placement and
+ fallbacks; custom mode owns its geometry; fixed mode owns explicit coordinates.
+- **INV4 — Shared anchors compose.** One layer adding or removing its anchor name
+ does not overwrite names belonging to sibling layers.
+- **INV5 — Logical placement remains direction-aware.** Standard anchored
+ placement derives from the surface's inherited writing direction and keeps
+ clearance after a fallback flip.
+- **INV6 — Native close reconciliation is single-fired.** Programmatic hide and
+ browser close do not double-fire state or `onHide` updates.
+- **INV7 — Existing native-light-dismiss guards identify gestures.** The same
+ physical press that closes a Layer cannot immediately reopen it; menu-hover also
+ suppresses exposure-induced hover.
+- **INV8 — Current Escape delivery follows registered layers.** The shared stack
+ uses present `close` and `block` entries in its current depth, containment, and
+ stable-registration order.
+- **INV9 — Outside channels remain component-owned and uncoordinated.** Current
+ backdrop, pointer, touch, hover/focus, and swipe handlers act through their
+ owning component or browser mechanism rather than one shared branch operation.
+- **INV10 — LayerProvider is Toast configuration, not a universal layer host.**
+ Trigger-associated layers resolve near their JSX position independently of the
+ provider.
+
+This record does not make future eligible-owner, branch-association, global-host,
+or browser-support requirements current. It does not own component focus entry or
+return, modal semantics, channel admission policy, public controlled/uncontrolled
+APIs, visual treatment, or theming anatomy.
+
+## Current gaps and accepted change
+
+Current gaps are observable facts, not current target behavior:
+
+- Tooltip currently consumes Escape ahead of an associated Popover, menu, or
+ Dialog instead of acting as passive information.
+- There is no distinction between active, blocking, passive, and visual-only
+ registration roles.
+- Outside interaction cannot resolve a whole associated menu/submenu branch or a
+ nested child branch through shared infrastructure.
+- Backdrop, manual outside, touch, and swipe paths do not share the existing
+ gesture claim or one association model.
+- Toast's root and fallback hosts remain behind active native modals.
+- CommandPalette's local Escape handler bypasses shared owner selection.
+- The reduced browser fallback is not documented as non-equivalent.
+- Existing tests simulate Popover `toggle` and DOM nesting; they do not prove
+ native pointer light dismissal, top-layer/modal ordering, real anchor geometry,
+ SSR parser repair, or nested portal behavior in supported browsers.
+
+`spec:AST-003` is the accepted, unimplemented change that owns requirements,
+migration, verification, and completion criteria for these gaps. This record must
+be updated only as that work ships.
+
+## Change coupling
+
+- A change to `useLayer` hosting or lifecycle verifies safe inline placement,
+ corrective portals, host relocation, show/hide reconciliation, theme
+ inheritance, writing context, and reduced-browser behavior.
+- A positioning change verifies all placement/alignment combinations in LTR and
+ RTL, viewport-edge fallbacks, offsets after flips, shared anchors, custom mode,
+ and fixed mode.
+- A Popover lifecycle change verifies programmatic and browser closes, controlled
+ state, temporary invoker association, and same-gesture trigger behavior.
+- A dismissal-stack change updates `family:overlay-dismissal` when membership or
+ Escape/platform delivery changes.
+- A local outside, backdrop, touch, hover, or swipe change preserves the owning
+ component's policy and verifies interactions with nested surfaces.
+- A Toast host change preserves queued and visible toasts, timers, focus handoff,
+ theme context, and ordering.
+- A CommandPalette host change preserves native modality, search state, focus
+ entry/return, and controlled close behavior.
+- A browser fallback change updates public `useLayer` and Popover docs and tests
+ for both the native path and actual fallback.
+
+## Owning code
+
+- `Layer/useLayer.tsx` owns Popover API lifecycle, state reconciliation,
+ anchor/fixed/custom rendering, trigger source, and current same-gesture memory.
+- `Layer/layerHost.ts` owns safe inline versus nearest corrective portal placement.
+- `Layer/anchorName.ts` owns composition of anchor names on one trigger.
+- `Layer/gestureCounter.ts` owns physical pointer/key gesture identity.
+- `Layer/layerStack.ts`, `Layer/useLayerDismissal.ts`, and
+ `Layer/LayerDepthContext.tsx` own current registration, presence, ordering, and
+ Escape/platform routing.
+- `Popover/usePopover.tsx` owns focus-trap composition and default native light
+ dismiss for Popover-family surfaces.
+- `hooks/useFocusTrap.ts` adapts dismissible traps into current shared
+ registration; it does not own component focus policy.
+- `hooks/useMenuHover.ts` owns hover-open confirmation, native invoker wiring,
+ menu focus, and exposure-induced re-hover suppression.
+- `Layer/useTouchTrigger.ts` owns touch trigger classification and the current
+ touch-only outside listener for Tooltip/HoverCard.
+- `DropdownMenuContext` and `DropdownMenuSubMenu` own the current local
+ menu-cascade parent-close chain.
+- Dialog families own native modal/backdrop presentation and their local channel
+ policies.
+- `LayerProvider`, `ToastContext`, `useToast`, and `ToastViewport` own current
+ notification state, dispatch, and viewport rendering.
+- CommandPalette owns command search and selection; Dialog owns its native modal
+ host.
+- `family:overlay-dismissal` owns Escape/platform-close membership.
+ `architecture:interaction-modality` owns last-input modality.
+ `architecture:public-component-api` owns public component and hook contracts.
+ `architecture:theme-application` owns provider and portal theme context.
+
+## Deciding specs
+
+No system spec changes the shipped runtime described here.
+
+`spec:AST-003` is accepted but unimplemented. It defines the approved next
+runtime and must move to `shipped` before its requirements are incorporated into
+this current architecture record.
+
+## Verification
+
+| Invariant | Evidence | Failure signal |
+| ---------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| INV1, INV2 | `useLayer.test.tsx` and `layerHost.test.ts` | Invalid DOM, stale host, lost theme/writing context, or portal mistaken for top-layer promotion |
+| INV3–INV5 | `useLayer.test.tsx` and `anchorName.test.ts` | A mode leaks geometry, RTL resolves from the wrong context, fallback clips, or a sibling anchor is lost |
+| INV6, INV7 | `useLayer.test.tsx`, `Popover.test.tsx`, `DropdownMenu.test.tsx`, and `useMenuHover.test.tsx` | Duplicate close callback or the same press/re-hover reopens a surface |
+| INV8 | `useLayerDismissal.test.tsx`, `layerDismissalInvariants.test.tsx`, and `useFocusTrap.test.tsx` | Current top registered layer is skipped, two layers close, or a blocker leaks through |
+| INV9 | Representative Dialog, ContextMenu, Tooltip/HoverCard, and BottomSheet source/tests | A current local channel silently changes ownership or policy |
+| INV10 | `LayerProvider.tsx`, `useToast.tsx`, and `ToastViewport.test.tsx` | Provider begins relocating ordinary layers or Toast fallback loses its current lifecycle |
+
+Current unit coverage proves emitted styles, reducers, state transitions, and DOM
+placement. Native Popover, `<dialog>`, focus, top-layer ordering, and rendered
+anchor geometry require real Chromium and WebKit evidence when changed.
diff --git a/docs/specs/AST-003/spec.md b/docs/specs/AST-003/spec.md
new file mode 100644
index 0000000000..4ee114225a
--- /dev/null
+++ b/docs/specs/AST-003/spec.md
@@ -0,0 +1,323 @@
+---
+schema_version: 1
+template_version: 1
+kind: system-spec
+id: spec:AST-003
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-08-30
+phase: accepted
+owners: [cixzhang, imdreamrunner]
+affects_architecture:
+ [
+ architecture:layer-runtime,
+ architecture:interaction-modality,
+ architecture:public-component-api,
+ ]
+affects_families: [family:overlay-dismissal]
+affects_contributing: []
+affects_consumer_docs: []
+---
+
+# Layer coordination and global hosting system spec
+
+## Intent
+
+Make every layered interaction close the intended owner or interaction branch,
+without transient surfaces shielding it or one pointer gesture closing and then
+reopening it. Selected app-global systems must remain visible and operable above
+native modal dialogs through browser-valid native hosting.
+
+The full anchored-layer contract must also state its platform dependency honestly:
+native Popover API plus CSS Anchor Positioning provide full behavior; unsupported
+browsers receive a usable reduced fallback, not equivalent behavior.
+
+## Non-goals
+
+- Making every layer dismissible through every channel.
+- Replacing component-owned focus, modality, outside-dismiss policy, backdrop,
+ swipe threshold, hover timing, open-state API, animation, or visual treatment.
+- Giving every overlay a global or above-modal mode.
+- Replacing native Popover and CSS Anchor Positioning with a legacy positioning
+ and dismissal polyfill.
+- Changing the public API merely to expose internal owner, branch, or gesture
+ bookkeeping.
+
+## Requirements
+
+### Interaction ownership and association
+
+- **FR1 — Coordination models interaction roles.** A registered surface is an
+ active dismiss owner, a blocking owner, or a passive dependent. A visual-only
+ surface does not register as an interaction owner.
+- **FR2 — Active owners may dismiss.** An active owner owns task or interaction
+ state and invokes its component-owned close behavior when the selected channel
+ participates.
+- **FR3 — Blocking owners consume without closing.** A blocking owner prevents a
+ channel from reaching an owner behind it. Required Dialog is the representative
+ Escape/platform case.
+- **FR4 — Passive dependents never shield owners.** Tooltip is passive. It does
+ not win or block dismissal and disappears as a consequence when its associated
+ owner or trigger interaction closes.
+- **FR5 — Associations are explicit.** Every active or blocking owner records an
+ optional parent owner and an interaction-branch root. A passive dependent
+ records its associated owner or trigger without creating an owner node or
+ branch boundary.
+
+### Channel-specific arbitration
+
+- **FR6 — Escape and platform close select one eligible owner.** One-at-a-time
+ channels select the highest associated active or blocking owner whose
+ component policy participates. Active closes, blocking consumes, passive and
+ visual-only surfaces are skipped.
+- **FR7 — Outside interaction resolves branches.** Outside interaction is
+ evaluated against owner surfaces, associated triggers or invokers, and branch
+ relationships. It does not reuse visual or registration topmost order.
+- **FR8 — Menu cascades close as one branch.** DropdownMenu and its open flyout
+ submenus share one branch root. Outside that root closes the root and every
+ open submenu.
+- **FR9 — Nested child branches can close independently.** A distinct nested
+ Popover creates a child branch. Interaction inside the parent branch but
+ outside the child closes only the child; interaction outside both resolves
+ both affected branches according to component policy.
+- **FR10 — Component policy stays with the component.** Shared coordination
+ determines the eligible owner or affected branch. The owning component or
+ family determines whether that channel dismisses, blocks, or passes.
+
+### Same-interaction protection
+
+- **FR11 — Pointer dismissal claims the interaction before closing.** Every
+ pointer-driven outside, light-dismiss, backdrop, touch, or swipe path that can
+ collide with an associated trigger records a branch claim before visibility
+ changes.
+- **FR12 — Every reopen path honors the claim.** Associated triggers, native
+ invokers, `show()`, and toggle paths refuse the same physical gesture. A later
+ gesture may reopen.
+- **FR13 — Browser event order is irrelevant.** The claim works whether native
+ close is observed before or after click. Timestamp windows do not substitute
+ for gesture identity.
+- **FR14 — Menu hover suppresses exposure-induced hover.** When a closing panel
+ exposes a stationary trigger, the resulting synthetic `mouseenter` does not
+ reopen the branch. A genuine leave and later hover may open it again.
+
+### Native hosting for selected global systems
+
+- **FR15 — Global admission is explicit.** A system receives above-modal global
+ hosting only through an owner-approved update to `architecture:layer-runtime`.
+ Ordinary trigger- or task-associated overlays remain local.
+- **FR16 — Toast is globally hosted.** ToastViewport remains visible and operable
+ above the current native modal. Toast remains passive in layer dismissal:
+ Escape/platform arbitration skips it, and auto-hide, explicit controls, or a
+ direct toast swipe dismiss only the toast.
+- **FR17 — CommandPalette is a global active owner in launcher mode.** Normal
+ CommandPalette uses a later native modal host and forms an active interaction
+ branch above the prior modal. `isInline` previews are not global or modal.
+- **FR18 — Native modal ancestry supplies passive global hosting.** The app has a
+ root global outlet and each active native modal supplies an outlet in its DOM.
+ Passive global hosts render into the latest active modal outlet, falling back
+ to the root outlet when no modal is active. An ordinary body portal or
+ `z-index` is not sufficient.
+- **FR19 — Global state survives rehosting.** Toast dispatch, visible entries,
+ timers, focus handoff, and collision state live above the selected outlet so
+ modal opening or closing does not reset them.
+- **FR20 — Current nonqualifiers stay local.** Banner and FieldStatus remain
+ in-flow; `useAnnounce` remains nonvisual; AlertDialog, imperative Dialog,
+ Lightbox, and ordinary Popover-family surfaces remain task- or
+ trigger-associated.
+
+### Anchored-layer support requirements
+
+- **FR21 — Native features define full anchored behavior.** Supported native
+ Popover API plus CSS Anchor Positioning provide top-layer promotion, native
+ light dismissal, auto-popover association, logical anchor geometry, and
+ collision fallbacks.
+- **FR22 — Unsupported browsers receive a usable reduced fallback.** Explicit
+ controls still show and hide mounted content, callbacks and React state update,
+ and fixed coordinates apply. The fallback is not required to reproduce native
+ top-layer, outside-dismiss, close-request, auto-stack, invoker focus-order,
+ anchor-geometry, or collision behavior.
+- **FR23 — Public docs state the boundary.** `useLayer`, Popover, and relevant
+ component docs distinguish full native behavior from reduced fallback behavior
+ without calling the fallback equivalent.
+
+### Implementation requirements
+
+- **IR1 — Coordination exposes two operations.** Shared infrastructure provides
+ an eligible-owner resolver for one-at-a-time channels and an associated-branch
+ resolver for outside interaction. One generic `isTopmost` operation cannot
+ implement both contracts.
+- **IR2 — Branch identity is reusable.** Dropdown submenu context projects its
+ existing root-close chain into shared branch identity. Independent nested
+ Popovers create child branches rather than joining a menu cascade accidentally.
+- **IR3 — Gesture claims extend the existing owner.** Branch claims build on
+ `gestureCounter` rather than introducing per-component timestamp heuristics.
+- **IR4 — Native global outlets are narrow infrastructure.** Global outlet
+ selection does not become a public `global` prop on Layer or Popover.
+- **IR5 — Runtime behavior changes stay atomic.** Eligibility, branch
+ coordination, gesture claims, global hosting, and support documentation may
+ ship as separate changes while preserving this one accepted contract.
+
+### Platform support
+
+- Supported feature/engine floor: the full contract applies where native Popover
+ API and CSS Anchor Positioning are supported by Astryx's published browser
+ matrix.
+- Unsupported behavior: browsers below that feature floor receive FR22 only.
+ Native modal Dialog behavior remains subject to the supported dialog floor.
+- Browser evidence: native light dismissal, invoker behavior, top-layer order,
+ focus/inertness, modal outlets, and anchor geometry require real Chromium and
+ WebKit. Playwright WebKit is not evidence of Safari-specific behavior.
+
+## Current-state impact
+
+Current `main` does not satisfy this spec completely:
+
+- the stack has `close` and `block` but no passive role; Tooltip currently
+ consumes Escape ahead of associated owners;
+- no shared owner/branch association graph or outside-branch resolver exists;
+- DropdownMenuSubMenu has a local parent-close chain, but outside channels do not
+ consume shared branch identity;
+- native light dismiss has gesture memory, and menu hover has re-hover
+ suppression, but local backdrop, touch, swipe, and manual outside paths do not
+ share branch claims;
+- body/root Toast hosts remain behind active native modal dialogs;
+- Toast state lives inside ToastViewport rather than above a movable outlet;
+- CommandPalette uses native Dialog but handles Escape locally; and
+- reduced fallback behavior exists in code but is not fully described in public
+ docs.
+
+### Migration and adoption plan
+
+1. **Owner and branch model.** Extend layer registration with active, blocking,
+ and passive roles plus parent-owner and branch-root association. Add pure
+ eligible-owner and outside-branch resolvers. Preserve the current
+ Escape/platform contract for existing active/blocking members while migrating.
+2. **Eligibility migration.** Make Tooltip passive and update Tooltip-over-owner
+ tests. Keep HoverCard active because it can own interactive content. Migrate
+ CommandPalette and the local Escape implementations tracked by
+ `family:overlay-dismissal` onto eligible-owner delivery.
+3. **Branch migration.** Project DropdownMenuContext's root/submenu chain into a
+ shared branch. Add independent child branches for nested Popovers. Migrate
+ native auto light dismiss, ContextMenu outside press, dialog backdrop, touch,
+ and sheet swipe/scrim channels without changing their component policies.
+4. **Gesture claims.** Generalize current Layer close memory into a branch claim
+ recorded before pointer-driven closure. Require every associated reopen path
+ to consult it. Preserve menu-hover's exposure suppression.
+5. **Global native host.** Add root and modal outlets with activation order. Lift
+ Toast state above the render outlet, render its manual-popover viewport inside
+ the selected outlet, and preserve state through rehosting. Keep CommandPalette
+ on native Dialog and verify it as a later active modal owner.
+6. **Support projection.** Update public Layer/Popover/component docs with the
+ full native contract and reduced fallback. Add the browser matrix required
+ below.
+7. **Architecture promotion.** As each requirement ships, update
+ `architecture:layer-runtime` from observed gaps to shipped invariants. Move
+ this spec to `shipped` only after every completion criterion is met.
+
+No migration step adds a broad public API by default. A new public prop or hook
+still follows `architecture:public-component-api` and `spec:AST-002`.
+Interaction modality continues to follow `architecture:interaction-modality`.
+
+## Verification
+
+| Contract | Verification | Representative states | Mutation or failure expectation |
+| --------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| FR1–FR6 | Pure registry/resolver tests plus family interaction tests | active, blocking, passive Tooltip, visual-only, controlled owner | Passive surface wins, blocker leaks, or wrong owner closes |
+| FR7–FR10 | Branch resolver tests and real-browser outside interaction | root menu with two submenu levels; parent + child Popover; associated trigger | Outside root leaves submenu open, or child-only outside closes parent |
+| FR11–FR14 | Gesture-counter and browser event-order tests | native light dismiss before/after click; menu button; hover-open; touch; backdrop; swipe | Same gesture reopens any associated trigger or exposed hover reopens panel |
+| FR15–FR20 | Chromium/WebKit native host tests | Toast at root; Toast through one/two modals; CommandPalette above modal; ordinary local Popover | Global surface is behind/inert, loses state, or ordinary overlay becomes global |
+| FR21–FR23 | Supported/unsupported browser matrix and public-doc checks | anchor/fixed/custom; auto/manual; explicit controls; absent feature APIs | Docs promise equivalence or reduced fallback is unusable |
+| IR1–IR3 | API/type tests and mutation tests for resolvers/claims | one-at-a-time channel versus branch channel | One topmost query is reused for outside branches or timestamps replace identity |
+| IR4, IR5 | Public-surface snapshot and atomic change review | local Popover, global Toast, global CommandPalette | Generic global prop appears or unrelated behaviors are coupled in one change |
+
+### Completion criteria
+
+This spec is complete only when:
+
+- Tooltip is passive in Escape/platform and outside-branch coordination;
+- eligible-owner and associated-branch operations are shared and adopted by all
+ members named by `family:overlay-dismissal` for their relevant channels;
+- outside a dropdown/menu root closes its entire open submenu cascade, while
+ child-branch outside behavior preserves its parent when appropriate;
+- every pointer-driven branch dismissal uses the branch gesture claim and every
+ associated reopen path honors it;
+- Toast remains visible and operable above zero, one, and two active native
+ modals without losing entries, timers, theme, or focus handoff;
+- normal CommandPalette opens above an existing modal and participates as the
+ selected active owner;
+- ordinary overlays remain local and cannot opt into global hosting without an
+ approved record change;
+- public docs describe full native support and the reduced fallback accurately;
+- required Chromium and WebKit browser matrices pass; and
+- `architecture:layer-runtime` and `family:overlay-dismissal` reflect the shipped
+ implementation without listing these items as gaps.
+
+## Decision log
+
+### DEC-1 — Dismissal follows eligible interaction ownership
+
+**Reference:** `spec:AST-003/DEC-1`
+**Decider:** `cixzhang`, `2026-08-30`
+
+Escape and platform close select the topmost eligible active or blocking owner,
+not the topmost visible or registered surface. Tooltip is passive and cannot
+shield a Popover, menu, Dialog, or associated interactive element beneath it.
+
+Rejected: letting every visible transient layer consume one Escape. That makes
+supplementary information block the interaction the user is trying to dismiss.
+
+### DEC-2 — Outside interaction resolves associated branches
+
+**Reference:** `spec:AST-003/DEC-2`
+**Decider:** `cixzhang`, `2026-08-30`
+
+Outside interaction has different scope from Escape. Outside a dropdown or menu
+cascade closes the whole associated root branch, including every open submenu.
+Interaction outside only a distinct nested child branch closes that child while
+preserving the parent when the event remains inside the parent branch.
+
+Rejected: reusing one visually topmost gate for every channel. One-at-a-time and
+branch-scoped interactions have different user intent.
+
+### DEC-3 — Dismissing gestures are claimed across the branch
+
+**Reference:** `spec:AST-003/DEC-3`
+**Decider:** `cixzhang`, `2026-08-30`
+
+A pointer gesture that dismisses a branch is claimed before close. It cannot
+continue into an associated trigger and immediately reopen any surface in that
+branch. Menu-hover also suppresses the synthetic hover created when a closing
+panel exposes its trigger.
+
+Rejected: timestamp-only debounce. Gesture identity must survive either browser
+event order without delaying a deliberate next interaction.
+
+### DEC-4 — Selected global systems use native above-modal hosting
+
+**Reference:** `spec:AST-003/DEC-4`
+**Decider:** `cixzhang`, `2026-08-30`
+
+Toast and normal CommandPalette are the current selected global systems. They may
+and must appear above active native modal dialogs through browser-valid native
+hosting. This does not make ordinary overlays global.
+
+Rejected: relying on a body portal or high `z-index`. Neither can cross a native
+modal top-layer boundary.
+
+### DEC-5 — Full anchored behavior depends on native platform features
+
+**Reference:** `spec:AST-003/DEC-5`
+**Decider:** `cixzhang`, `2026-08-30`
+
+Native Popover API plus CSS Anchor Positioning define the full anchored-layer
+contract. Unsupported browsers receive a documented usable reduced fallback,
+not equivalent positioning, stacking, association, or dismissal behavior.
+
+Rejected: describing the current `display` fallback as a polyfill. It does not
+implement the missing browser systems.
+
+## Open questions
+
+None.