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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.