From 9ce907dc28d7e5097e686e5c8b5a8c1a25e825fc Mon Sep 17 00:00:00 2001
From: Phil LaFayette <plafaydev@gmail.com>
Date: Fri, 26 Jun 2026 17:07:40 -0500
Subject: [PATCH 1/6] Overlay Phase 2: migrate at-risk anchored overlays to the
 native top layer

MentionDropdown, ReactionBar (hover tooltip -> manual popover, hover
lifecycle preserved), ArtifactDetailHeader dropdowns, EmojiPicker,
ProfileCard, NotificationPolicyMenu, ReadReceipt now open via
<Popover>/use:topLayer (Popover API), dropping raw position:fixed/absolute
+ z-index. MessageInput passes the textarea as the MentionDropdown anchor.
Each keeps its existing outside-click/keyboard dismiss handlers so jsdom
unit coverage holds (the action capability-guards the native calls).
---
 .../components/ArtifactDetailHeader.svelte    |  24 +++-
 web/src/components/EmojiPicker.svelte         |  46 +++++--
 web/src/components/MentionDropdown.svelte     |  26 +++-
 web/src/components/MessageInput.svelte        |   9 +-
 .../components/NotificationPolicyMenu.svelte  |  28 ++++-
 web/src/components/ProfileCard.svelte         |  53 +++++---
 web/src/components/ReactionBar.svelte         | 117 ++++++++++++------
 web/src/components/ReadReceipt.svelte         |  30 ++++-
 web/tests/reaction-bar.spec.js                |  16 ++-
 9 files changed, 258 insertions(+), 91 deletions(-)

diff --git a/web/src/components/ArtifactDetailHeader.svelte b/web/src/components/ArtifactDetailHeader.svelte
index 1b7515f..90e230f 100644
--- a/web/src/components/ArtifactDetailHeader.svelte
+++ b/web/src/components/ArtifactDetailHeader.svelte
@@ -36,6 +36,7 @@
     Check,
   } from 'lucide-svelte';
   import { formatTime, getParticipantColor } from '../lib/utils.js';
+  import { topLayer } from '../lib/top-layer.svelte.js';
 
   let {
     artifact,
@@ -387,6 +388,14 @@
             aria-label="Compare-from version"
             aria-activedescendant={compareActiveId}
             onkeydown={handleCompareListboxKeydown}
+            use:topLayer={{
+              anchor: compareTriggerEl,
+              placement: 'bottom-start',
+              offset: 4,
+              dismiss: 'manual',
+              trapInitialFocus: false,
+              restoreFocus: false,
+            }}
           >
             {#each compareOptions as v, idx (v.version)}
               {@const pc = getParticipantColor(v.author?.key ?? '')}
@@ -441,6 +450,14 @@
           aria-label="Artifact version"
           aria-activedescendant={primaryActiveId}
           onkeydown={handlePrimaryListboxKeydown}
+          use:topLayer={{
+            anchor: primaryTriggerEl,
+            placement: 'bottom-start',
+            offset: 4,
+            dismiss: 'manual',
+            trapInitialFocus: false,
+            restoreFocus: false,
+          }}
         >
           {#each versions as v, idx (v.version)}
             {@const pc = getParticipantColor(v.author?.key ?? '')}
@@ -674,10 +691,8 @@
   }
 
   .artifact-version-dropdown {
-    position: absolute;
-    top: 100%;
-    left: 0;
-    margin-top: 4px;
+    /* Position + top-layer promotion owned by use:topLayer (sets position:
+       fixed + left/top inline, anchored to the trigger button); no z-index. */
     width: 320px;
     max-height: 240px;
     overflow-y: auto;
@@ -685,7 +700,6 @@
     border: 1px solid var(--border);
     border-radius: var(--radius-sm);
     box-shadow: 0 8px 24px rgba(0, 0, 0, 0.4);
-    z-index: 10;
     animation: panelIn 0.15s cubic-bezier(0.16, 1, 0.3, 1) both;
   }
 
diff --git a/web/src/components/EmojiPicker.svelte b/web/src/components/EmojiPicker.svelte
index 7cb984f..3f945f1 100644
--- a/web/src/components/EmojiPicker.svelte
+++ b/web/src/components/EmojiPicker.svelte
@@ -6,6 +6,7 @@
 -->
 <script>
   import { onMount } from 'svelte';
+  import Popover from './Popover.svelte';
 
   let { onSelect, onClose } = $props();
 
@@ -239,14 +240,33 @@
   }
 
   onMount(() => { searchInput?.focus(); });
+
+  // The picker root, used to detect outside clicks. Overlay overhaul,
+  // Phase 2: the picker now opens in the browser native top layer via
+  // <Popover>, so it escapes every ancestor stacking context with NO
+  // position:fixed and NO z-index. The old full-screen `.emoji-backdrop`
+  // element is gone; a window-level mousedown closes the picker when the
+  // click lands outside it (identical in jsdom and real Chromium).
+  let pickerEl = $state(/** @type {HTMLElement | null} */ (null));
+
+  function handleOutsideMousedown(e) {
+    const t = e.target;
+    const el = t instanceof Element ? t : (t?.parentElement ?? null);
+    if (el && pickerEl && pickerEl.contains(el)) return;
+    onClose();
+  }
 </script>
 
-<div class="emoji-backdrop" onclick={onClose} onkeydown={(e) => { if (e.key === 'Escape') onClose(); }} role="presentation">
+<svelte:window
+  onkeydown={(e) => { if (e.key === 'Escape') onClose(); }}
+  onmousedown={handleOutsideMousedown}
+/>
+
+<Popover dismiss="manual" class="emoji-picker-popover">
   <div
+    bind:this={pickerEl}
     class="emoji-picker"
     data-testid="emoji-picker"
-    onclick={(e) => e.stopPropagation()}
-    onkeydown={(e) => { if (e.key === 'Escape') onClose(); }}
     role="dialog"
     aria-label="Emoji picker"
     aria-modal="true"
@@ -301,21 +321,23 @@
       </div>
     </div>
   </div>
-</div>
+</Popover>
 
 <style>
-  .emoji-backdrop {
-    position: fixed;
-    inset: 0;
-    z-index: 99;
-  }
-
-  .emoji-picker {
+  /* Viewport-positioned popover wrapper (the native top-layer element).
+     Global because the class lands on <Popover>'s own <div>, outside this
+     component's scope. inset:auto cancels the popover UA centering so our
+     explicit bottom/left placement takes effect. */
+  :global(.emoji-picker-popover) {
     position: fixed;
+    inset: auto;
     bottom: 120px;
     left: 50%;
     transform: translateX(-50%);
-    z-index: 100;
+    margin: 0;
+  }
+
+  .emoji-picker {
     width: 380px;
     background: rgba(37, 37, 40, 0.95);
     backdrop-filter: blur(20px) saturate(1.2);
diff --git a/web/src/components/MentionDropdown.svelte b/web/src/components/MentionDropdown.svelte
index cbe0020..320312e 100644
--- a/web/src/components/MentionDropdown.svelte
+++ b/web/src/components/MentionDropdown.svelte
@@ -9,9 +9,11 @@
   @prop {(index:number) => void} onHover - Called when the user hovers a candidate (parent updates highlight).
   @prop {(candidate:object) => void} onCommit - Called when the user clicks a candidate.
   @prop {string} listboxId - DOM id used for ARIA wiring (textarea aria-controls + aria-activedescendant).
+  @prop {HTMLElement|null} [anchor] - The composer textarea the dropdown anchors above (top layer).
 -->
 <script>
   import { getInitials, getParticipantColor } from '../lib/utils.js';
+  import { topLayer } from '../lib/top-layer.svelte.js';
 
   let {
     candidates = [],
@@ -19,6 +21,7 @@
     onHover,
     onCommit,
     listboxId = 'mention-listbox',
+    anchor = null,
   } = $props();
 
   /**
@@ -33,12 +36,28 @@
   }
 </script>
 
+<!--
+  Overlay overhaul Phase 2: the dropdown opens in the browser native top
+  layer via use:topLayer (Popover API), anchored ABOVE the composer
+  textarea, so it escapes the composer's stacking/overflow context with no
+  position:absolute and no z-index. dismiss:'manual' + trapInitialFocus
+  false: MessageInput owns the lifecycle and keyboard focus stays in the
+  textarea (this dropdown is purely presentational, it never grabs focus).
+-->
 <div
   class="mention-dropdown"
   role="listbox"
   id={listboxId}
   aria-label="Mention suggestions"
   data-testid="mention-dropdown"
+  use:topLayer={{
+    anchor,
+    placement: 'top-start',
+    offset: 8,
+    dismiss: 'manual',
+    trapInitialFocus: false,
+    restoreFocus: false,
+  }}
 >
   {#if candidates.length === 0}
     <div class="mention-empty" data-testid="mention-empty">No matches</div>
@@ -82,17 +101,14 @@
 
 <style>
   .mention-dropdown {
-    position: absolute;
-    bottom: 100%;
-    left: 16px;
-    margin-bottom: 8px;
+    /* Position + top-layer promotion owned by use:topLayer (sets position:
+       fixed + left/top inline, anchored above the textarea); no z-index. */
     width: 260px;
     background: var(--bg-elevated);
     border: 1px solid var(--border);
     border-radius: var(--radius-sm);
     box-shadow: 0 8px 32px rgba(0, 0, 0, 0.5), 0 0 0 1px rgba(255, 255, 255, 0.03);
     padding: 4px;
-    z-index: 20;
     animation: panelIn 0.2s ease both;
   }
 
diff --git a/web/src/components/MessageInput.svelte b/web/src/components/MessageInput.svelte
index 36c5106..b6f9236 100644
--- a/web/src/components/MessageInput.svelte
+++ b/web/src/components/MessageInput.svelte
@@ -1374,6 +1374,7 @@
       onHover={handleDropdownHover}
       onCommit={handleDropdownCommit}
       listboxId="mention-listbox"
+      anchor={inputEl}
     />
   {/if}
 </div>
@@ -1384,7 +1385,7 @@
     border-top: 1px solid var(--border);
     background: linear-gradient(180deg, var(--bg-base) 0%, #0e0e10 100%);
     position: relative;
-    z-index: 2;
+    z-index: var(--z-content);
   }
 
   .typing-indicator {
@@ -1467,7 +1468,7 @@
     font-size: 11px;
     color: var(--text-secondary);
     white-space: nowrap;
-    z-index: 20;
+    z-index: var(--z-banner);
   }
 
   .format-help code {
@@ -1677,7 +1678,7 @@
     tab-size: 2;
     color: var(--text-primary);
     box-sizing: border-box;
-    z-index: 1;
+    z-index: var(--z-raised);
   }
 
   .input-overlay .mention-confirmed {
@@ -1803,7 +1804,7 @@
     min-height: 36px;
     max-height: 180px;
     position: relative;
-    z-index: 2;
+    z-index: var(--z-content);
     /* Hide the native scrollbar so the textarea NEVER reserves a scrollbar
        gutter. A gutter would shrink the textarea's text-layout width while the
        overlay (overflow: hidden, no gutter) keeps the full width — the wrap
diff --git a/web/src/components/NotificationPolicyMenu.svelte b/web/src/components/NotificationPolicyMenu.svelte
index 01d89ed..a72ff82 100644
--- a/web/src/components/NotificationPolicyMenu.svelte
+++ b/web/src/components/NotificationPolicyMenu.svelte
@@ -34,6 +34,7 @@
 -->
 <script>
   import { tick, untrack } from 'svelte';
+  import Popover from './Popover.svelte';
 
   let {
     channelId,
@@ -108,6 +109,16 @@
   }}
 />
 
+<!--
+  Overlay overhaul, Phase 2: this menu now opens in the browser native top
+  layer via <Popover> (Popover API), so it escapes every ancestor stacking
+  context with NO position:fixed and NO z-index. It is viewport-centered by
+  the popover wrapper class (see :global(.notif-policy-popover)); dismissal
+  is component-controlled (dismiss="manual") via the existing Escape handler
+  and the Cancel button. The inner element keeps role="dialog" + the focus
+  effect; the action does not steal focus from it.
+-->
+<Popover dismiss="manual" class="notif-policy-popover">
 <div
   bind:this={rootEl}
   class="notif-policy-menu"
@@ -203,14 +214,23 @@
     </button>
   </div>
 </div>
+</Popover>
 
 <style>
-  .notif-policy-menu {
+  /* Viewport-centered popover wrapper (the native top-layer element). Global
+     because the class lands on <Popover>'s own <div>, outside this
+     component's scope. inset:auto cancels the popover UA centering so our
+     explicit translate centering (and the open animation) take effect. */
+  :global(.notif-policy-popover) {
     position: fixed;
+    inset: auto;
     top: 50%;
     left: 50%;
     transform: translate(-50%, -50%);
-    z-index: 260;
+    margin: 0;
+  }
+
+  .notif-policy-menu {
     min-width: 320px;
     max-width: 400px;
     background: rgba(37, 37, 40, 0.96);
@@ -226,11 +246,11 @@
   @keyframes menuIn {
     from {
       opacity: 0;
-      transform: translate(-50%, calc(-50% - 4px));
+      transform: translateY(-4px);
     }
     to {
       opacity: 1;
-      transform: translate(-50%, -50%);
+      transform: translateY(0);
     }
   }
 
diff --git a/web/src/components/ProfileCard.svelte b/web/src/components/ProfileCard.svelte
index 6f4f7a5..afdae62 100644
--- a/web/src/components/ProfileCard.svelte
+++ b/web/src/components/ProfileCard.svelte
@@ -1,28 +1,52 @@
 <!--
   @component ProfileCard
-  @description Compact popup card showing a participant's avatar, name, handle, and role badge. Provides action buttons for sending a direct message or viewing the full profile. Dismisses on backdrop click or Escape.
+  @description Compact popup card showing a participant's avatar, name, handle, and role badge. Provides action buttons for sending a direct message or viewing the full profile. Dismisses on outside click or Escape.
+
+  Overlay overhaul, Phase 2: the card now opens in the browser native top
+  layer via <Popover> (Popover API), so it escapes every ancestor stacking
+  context with NO position:fixed and NO z-index. The old full-screen
+  `.profile-backdrop` element is gone (the top layer + a window-level
+  outside-click handler replace it); the card is viewport-positioned by the
+  popover wrapper class (see :global(.profile-card-popover)).
+
   @prop {object} participant - Participant object with name, key, and type fields.
   @prop {Function} onClose - Callback invoked to dismiss the profile card.
   @prop {Function} onMessage - Optional callback invoked with the participant to start a direct message.
   @prop {Function} onViewProfile - Optional callback invoked with the participant to open the full profile view.
 -->
 <script>
+  import Popover from './Popover.svelte';
   import { Star } from 'lucide-svelte';
   import { getParticipantColor, getInitials } from '../lib/utils.js';
 
   let { participant, onClose, onMessage, onViewProfile } = $props();
 
   let color = $derived(getParticipantColor(participant.key));
+
+  // The card root, used to detect outside clicks. We no longer render a
+  // full-screen backdrop; a window-level mousedown closes the card when the
+  // click lands outside it. This keeps dismissal identical in jsdom (no
+  // Popover light-dismiss there) and real Chromium.
+  let cardEl = $state(/** @type {HTMLElement | null} */ (null));
+
+  function handleOutsideMousedown(e) {
+    const t = e.target;
+    const el = t instanceof Element ? t : (t?.parentElement ?? null);
+    if (el && cardEl && cardEl.contains(el)) return;
+    onClose();
+  }
 </script>
 
-<svelte:window onkeydown={(e) => { if (e.key === 'Escape') onClose(); }} />
+<svelte:window
+  onkeydown={(e) => { if (e.key === 'Escape') onClose(); }}
+  onmousedown={handleOutsideMousedown}
+/>
 
-<div class="profile-backdrop" onclick={onClose} onkeydown={(e) => { if (e.key === 'Enter' || e.key === ' ') onClose(); }} role="presentation" data-testid="profile-card-close">
+<Popover dismiss="manual" class="profile-card-popover">
   <div
+    bind:this={cardEl}
     class="profile-card"
     data-testid="profile-card"
-    onclick={(e) => e.stopPropagation()}
-    onkeydown={(e) => { if (e.key === 'Escape') onClose(); }}
     role="dialog"
     aria-label="Profile card for {participant.name}"
     aria-modal="true"
@@ -47,20 +71,21 @@
       </div>
     </div>
   </div>
-</div>
+</Popover>
 
 <style>
-  .profile-backdrop {
+  /* Viewport-positioned popover wrapper (the native top-layer element).
+     Global because the class lands on <Popover>'s own <div>, outside this
+     component's scope. inset:auto cancels the popover UA centering. */
+  :global(.profile-card-popover) {
     position: fixed;
-    inset: 0;
-    z-index: 49;
+    inset: auto;
+    bottom: 70px;
+    left: 14px;
+    margin: 0;
   }
 
   .profile-card {
-    position: fixed;
-    bottom: 70px;
-    left: 14px;
-    z-index: 50;
     width: 240px;
     background: var(--bg-elevated);
     border: 1px solid var(--border);
@@ -91,7 +116,7 @@
     color: #0a0a0c;
     border: 3px solid var(--bg-elevated);
     box-shadow: 0 2px 8px rgba(0,0,0,0.3);
-    z-index: 1;
+    z-index: var(--z-raised);
   }
 
   .profile-card-body { padding: 28px 16px 16px; }
diff --git a/web/src/components/ReactionBar.svelte b/web/src/components/ReactionBar.svelte
index e5e6263..dc1409c 100644
--- a/web/src/components/ReactionBar.svelte
+++ b/web/src/components/ReactionBar.svelte
@@ -25,8 +25,13 @@
     ReactionDetailsPanel anchored to the pill. Fired by "See all" and long-press.
 -->
 <script>
+  import { topLayer } from '../lib/top-layer.svelte.js';
+
   const MAX_TOOLTIP_NAMES = 3;
   const LONG_PRESS_MS = 500;
+  // Grace delay so the pointer can travel from the pill into the tooltip
+  // (to click "See all") without the tooltip closing in between.
+  const TOOLTIP_CLOSE_MS = 120;
 
   let {
     reactions = [],
@@ -36,6 +41,39 @@
     onOpenDetails,
   } = $props();
 
+  // ── Hover/focus tooltip lifecycle (Overlay overhaul Phase 2) ──
+  // The tooltip is now a manual top-layer popover (Popover API via
+  // use:topLayer) instead of a CSS :hover child, so it escapes the message
+  // list's overflow/transform/stacking contexts. We drive show/hide in JS
+  // to preserve the exact hover lifecycle: open on pill hover/focus, keep
+  // open while the pointer is over the pill OR the tooltip, close on a short
+  // grace delay otherwise.
+  let openIndex = $state(/** @type {number | null} */ (null));
+  let anchorEl = $state(/** @type {HTMLElement | null} */ (null));
+  let closeTimer = null;
+
+  function cancelClose() {
+    if (closeTimer) {
+      clearTimeout(closeTimer);
+      closeTimer = null;
+    }
+  }
+
+  function openTip(i, el) {
+    cancelClose();
+    openIndex = i;
+    anchorEl = el ?? null;
+  }
+
+  function scheduleClose() {
+    cancelClose();
+    closeTimer = setTimeout(() => {
+      openIndex = null;
+      anchorEl = null;
+      closeTimer = null;
+    }, TOOLTIP_CLOSE_MS);
+  }
+
   // Stable per-instance id base for aria linkage (pill ↔ its tooltip names).
   const uid = $props.id();
   const tooltipId = (i) => `${uid}-rtt-${i}`;
@@ -110,8 +148,11 @@
         onclick={() => handlePillClick(reaction)}
         onpointerdown={(e) => startPress(e, reaction)}
         onpointerup={cancelPress}
-        onpointerleave={cancelPress}
         onpointercancel={cancelPress}
+        onmouseenter={(e) => openTip(i, e.currentTarget)}
+        onmouseleave={() => { cancelPress(); scheduleClose(); }}
+        onfocus={(e) => openTip(i, e.currentTarget)}
+        onblur={scheduleClose}
         aria-label="{reaction.emoji} reaction, {reaction.count} {reaction.count === 1 ? 'person' : 'people'}"
         aria-pressed={reaction.active}
         aria-describedby={tooltipId(i)}
@@ -120,23 +161,42 @@
         <span class="count">{reaction.count}</span>
       </button>
       <!--
-        The hover/focus popover. ``role="tooltip"`` lives ONLY on the
-        non-interactive names span (a tooltip must not be an interactive
-        container); the "See all" control is a sibling button, not inside the
-        tooltip role. The pill links to the names via ``aria-describedby``.
+        The hover/focus tooltip - a manual top-layer popover (use:topLayer)
+        anchored to the pill, so it escapes the message list's stacking /
+        overflow contexts. It stays hoverable (pointer can move into it to
+        click "See all"): the tooltip cancels the close timer on enter/focus
+        and reschedules it on leave/blur. ``role="tooltip"`` lives ONLY on the
+        non-interactive names span; "See all" is a sibling button.
       -->
-      <span class="reaction-tooltip">
-        <span class="tooltip-names" role="tooltip" id={tooltipId(i)}>
-          {tooltipText(reaction)}
-        </span>
-        <button
-          type="button"
-          class="tooltip-see-all"
-          onclick={(e) => openDetailsFromTooltip(e, reaction)}
+      {#if openIndex === i}
+        <!-- svelte-ignore a11y_no_static_element_interactions -->
+        <span
+          class="reaction-tooltip"
+          onmouseenter={cancelClose}
+          onmouseleave={scheduleClose}
+          onfocusin={cancelClose}
+          onfocusout={scheduleClose}
+          use:topLayer={{
+            anchor: () => anchorEl?.getBoundingClientRect() ?? null,
+            placement: 'top-start',
+            offset: 6,
+            dismiss: 'manual',
+            trapInitialFocus: false,
+            restoreFocus: false,
+          }}
         >
-          See all
-        </button>
-      </span>
+          <span class="tooltip-names" role="tooltip" id={tooltipId(i)}>
+            {tooltipText(reaction)}
+          </span>
+          <button
+            type="button"
+            class="tooltip-see-all"
+            onclick={(e) => openDetailsFromTooltip(e, reaction)}
+          >
+            See all
+          </button>
+        </span>
+      {/if}
     </span>
   {/each}
   <button class="reaction-add" onclick={() => onAddReaction?.()} aria-label="Add reaction">+</button>
@@ -191,11 +251,11 @@
   .reaction.active .count { color: var(--ember-400); }
 
   /* ── Interactive hover/focus tooltip ── */
+  /* Now a manual top-layer popover: position + promotion are owned by
+     use:topLayer (it sets position:fixed + left/top inline); presence is
+     gated by the {#if openIndex === i} block, so no visibility/z-index
+     toggling is needed here - it is simply visible whenever rendered. */
   .reaction-tooltip {
-    position: absolute;
-    bottom: calc(100% + 6px);
-    left: 0;
-    z-index: 50;
     display: flex;
     align-items: center;
     gap: 8px;
@@ -207,22 +267,7 @@
     box-shadow: 0 8px 24px rgba(0, 0, 0, 0.45);
     font-size: 12px;
     color: var(--text-primary, #f1f1f3);
-    /* Hidden until the pill (or tooltip) is hovered / focused. visibility
-       (not display:none) keeps the "See all" button focusable once shown. */
-    visibility: hidden;
-    opacity: 0;
-    transition: opacity 100ms ease, visibility 100ms ease;
-    pointer-events: none;
-  }
-
-  /* The tooltip is a DOM descendant of .reaction-wrap, so :hover on the wrap
-     stays true while the pointer is over the tooltip — letting the user move
-     into it to click "See all". :focus-within covers the keyboard path. */
-  .reaction-wrap:hover .reaction-tooltip,
-  .reaction-wrap:focus-within .reaction-tooltip {
-    visibility: visible;
-    opacity: 1;
-    pointer-events: auto;
+    animation: panelIn 0.1s ease both;
   }
 
   .tooltip-names { color: var(--text-secondary, #c8c8cf); }
diff --git a/web/src/components/ReadReceipt.svelte b/web/src/components/ReadReceipt.svelte
index ff4eda8..ae31eb5 100644
--- a/web/src/components/ReadReceipt.svelte
+++ b/web/src/components/ReadReceipt.svelte
@@ -5,12 +5,21 @@
   @prop {Array<string>} readers - Optional array of reader display names for the tooltip.
 -->
 <script>
+  import { topLayer } from '../lib/top-layer.svelte.js';
+
   let { count = 0, readers = [] } = $props();
 
   let showTooltip = $state(false);
+  // Anchor for the top-layer tooltip (Overlay overhaul, Phase 2): the tooltip
+  // now promotes into the browser native top layer via use:topLayer, escaping
+  // the MessageBubble overflow/transform stacking context that used to clip
+  // it. Positioned above this receipt; dismiss is component-controlled (hover)
+  // so the action neither light-dismisses nor steals focus.
+  let receiptEl = $state(/** @type {HTMLElement | null} */ (null));
 </script>
 
 <div
+  bind:this={receiptEl}
   class="read-receipt"
   class:has-readers={count > 0}
   role="status"
@@ -25,7 +34,18 @@
   <span class="read-count">Read by {count}</span>
 
   {#if showTooltip && count > 0}
-    <div class="tooltip" role="tooltip">
+    <div
+      class="tooltip"
+      role="tooltip"
+      use:topLayer={{
+        anchor: () => receiptEl?.getBoundingClientRect() ?? null,
+        placement: 'top',
+        offset: 8,
+        dismiss: 'manual',
+        trapInitialFocus: false,
+        restoreFocus: false,
+      }}
+    >
       <div class="tooltip-arrow"></div>
       <span class="tooltip-text">
         {#if readers.length > 0}
@@ -115,17 +135,15 @@
   }
 
   /* ── Tooltip ── */
+  /* Overlay overhaul, Phase 2: positioned by use:topLayer in the native top
+     layer (no position:absolute, no z-index). The action sets position:fixed
+     + coordinates anchored above the receipt. */
   .tooltip {
-    position: absolute;
-    bottom: calc(100% + 8px);
-    left: 50%;
-    transform: translateX(-50%);
     background: var(--bg-elevated, #252528);
     border: 1px solid var(--border, #222225);
     border-radius: 6px;
     padding: 6px 10px;
     box-shadow: 0 4px 16px rgba(0, 0, 0, 0.3);
-    z-index: 100;
     animation: tooltipIn 0.15s ease;
     pointer-events: none;
     white-space: nowrap;
diff --git a/web/tests/reaction-bar.spec.js b/web/tests/reaction-bar.spec.js
index 320ceeb..0bb458e 100644
--- a/web/tests/reaction-bar.spec.js
+++ b/web/tests/reaction-bar.spec.js
@@ -26,7 +26,10 @@ function reaction(emoji, users, active = false) {
 afterEach(() => cleanup());
 
 describe('ReactionBar tooltip', () => {
-  it('lists up to 3 names then "+N others"', () => {
+  // The tooltip is now a manual top-layer popover rendered only while the
+  // pill is hovered/focused (Overlay overhaul Phase 2), so each test opens it
+  // by hovering the pill first (was a CSS :hover element, always in the DOM).
+  it('lists up to 3 names then "+N others"', async () => {
     const names = {
       bbbbbbbb: 'Alice',
       cccccccc: 'Bob',
@@ -34,7 +37,7 @@ describe('ReactionBar tooltip', () => {
       eeeeeeee: 'Dave',
       ffffffff: 'Eve',
     };
-    const { getByRole } = render(ReactionBar, {
+    const { getByRole, getByLabelText } = render(ReactionBar, {
       props: {
         reactions: [
           reaction('👍', ['bbbbbbbb', 'cccccccc', 'dddddddd', 'eeeeeeee', 'ffffffff']),
@@ -42,19 +45,21 @@ describe('ReactionBar tooltip', () => {
         resolveReactor: makeResolver(names),
       },
     });
+    await fireEvent.mouseEnter(getByLabelText(/👍 reaction/));
     const tooltip = getByRole('tooltip');
     expect(tooltip.textContent).toContain('Alice, Bob, Carol');
     expect(tooltip.textContent).toContain('+2 others');
     expect(tooltip.textContent).not.toContain('Dave');
   });
 
-  it('renders "You" for the self reactor and no overflow under 4 reactors', () => {
-    const { getByRole } = render(ReactionBar, {
+  it('renders "You" for the self reactor and no overflow under 4 reactors', async () => {
+    const { getByRole, getByLabelText } = render(ReactionBar, {
       props: {
         reactions: [reaction('🎉', [SELF, 'bbbbbbbb'], true)],
         resolveReactor: makeResolver({ bbbbbbbb: 'Alice' }),
       },
     });
+    await fireEvent.mouseEnter(getByLabelText(/🎉 reaction/));
     const tooltip = getByRole('tooltip');
     expect(tooltip.textContent).toContain('You, Alice');
     expect(tooltip.textContent).not.toContain('others');
@@ -62,13 +67,14 @@ describe('ReactionBar tooltip', () => {
 
   it('exposes a reachable "See all" control that opens the panel', async () => {
     const onOpenDetails = vi.fn();
-    const { getByText } = render(ReactionBar, {
+    const { getByText, getByLabelText } = render(ReactionBar, {
       props: {
         reactions: [reaction('👍', ['bbbbbbbb'])],
         resolveReactor: makeResolver({ bbbbbbbb: 'Alice' }),
         onOpenDetails,
       },
     });
+    await fireEvent.mouseEnter(getByLabelText(/👍 reaction/));
     const seeAll = getByText('See all');
     await fireEvent.click(seeAll);
     expect(onOpenDetails).toHaveBeenCalledTimes(1);

From 2e889278245c7d07d8370b23350c2d15746c808f Mon Sep 17 00:00:00 2001
From: Phil LaFayette <plafaydev@gmail.com>
Date: Fri, 26 Jun 2026 17:07:50 -0500
Subject: [PATCH 2/6] Overlay Phase 2: move already-portaled overlays onto the
 primitive

ReactionDetailsPanel, MemberContextMenu, and ChannelContextMenu (+ its
submenu as a nested manual popover, design F.8) now use use:topLayer
instead of portal()+hardcoded z-index (9999/250). Rewrite
context-menu-top-layer-bugfix.spec.js: the old z-index:9999 + @attach
portal() source pins are gone, so it now asserts the new primitive usage
(use:topLayer, no portal, no bare z-index; two use:topLayer for the menu+
submenu) plus render/outside-click/unmount behaviour. Adapt
reaction-details-panel.spec.js off the portal-parent assertion.
---
 web/src/components/ChannelContextMenu.svelte  | 153 +++++++++---------
 web/src/components/MemberContextMenu.svelte   |  87 +++++-----
 .../components/ReactionDetailsPanel.svelte    |  52 +++---
 .../context-menu-top-layer-bugfix.spec.js     | 147 ++++++++---------
 web/tests/reaction-details-panel.spec.js      |  18 ++-
 5 files changed, 212 insertions(+), 245 deletions(-)

diff --git a/web/src/components/ChannelContextMenu.svelte b/web/src/components/ChannelContextMenu.svelte
index 3cafffb..5c6c756 100644
--- a/web/src/components/ChannelContextMenu.svelte
+++ b/web/src/components/ChannelContextMenu.svelte
@@ -65,7 +65,7 @@
 -->
 <script>
   import { tick } from 'svelte';
-  import { portal } from '../lib/portal.js';
+  import { topLayer } from '../lib/top-layer.svelte.js';
   import {
     Star,
     StarOff,
@@ -219,61 +219,52 @@
   });
 
   // -----------------------------------------------------------------
-  // Position state. Default to 0,0; once the menu has mounted the
-  // $effect below reads `anchorEvent.clientX/Y`, measures the rendered
-  // rect, and sets the final coords (possibly flipped). The component
-  // is mounted/unmounted on each right-click in the parent shell, so a
-  // stale anchorEvent value cannot occur during a single instance.
+  // Positioning is delegated to `use:topLayer` (Overlay overhaul, Phase
+  // 2): both the menu and its submenu are promoted into the browser
+  // native top layer (Popover API) anchored to cursor / parent-row
+  // coords, escaping EVERY ancestor stacking context - no portal, no
+  // z-index, no manual flip math (the action clamps to the viewport).
+  // The component is mounted/unmounted on each right-click in the
+  // parent shell, so a stale anchorEvent value cannot occur.
   // -----------------------------------------------------------------
-  let menuX = $state(0);
-  let menuY = $state(0);
-  let menuEl = $state(null);
+  let menuEl = $state(/** @type {HTMLElement | null} */ (null));
+
+  // Cursor rect for the main-menu anchor: a zero-size rect at the
+  // contextmenu event coords.
+  const anchorRect = () =>
+    typeof DOMRect !== 'undefined'
+      ? new DOMRect(anchorEvent?.clientX ?? 0, anchorEvent?.clientY ?? 0, 0, 0)
+      : null;
 
   // Submenu state.
   let submenuOpenIndex = $state(/** @type {number | null} */ (null));
   let submenuX = $state(0);
   let submenuY = $state(0);
 
+  // Submenu anchor: a zero-size rect at the right edge of the parent row
+  // (computed in openSubmenu BEFORE the submenu renders, so the action
+  // positions it correctly on mount).
+  const submenuRect = () =>
+    typeof DOMRect !== 'undefined' ? new DOMRect(submenuX, submenuY, 0, 0) : null;
+
   // Active item index for keyboard navigation. Defaults to 0 once the
   // menu mounts; ArrowUp / ArrowDown move it.
   let activeIndex = $state(0);
   let submenuActiveIndex = $state(0);
 
   // -----------------------------------------------------------------
-  // Position + initial focus after mount. We use $effect with a
-  // run-once latch instead of onMount so jsdom test environments
-  // (which do not run microtask animation frames) still execute the
-  // measurement pass before assertions.
+  // Initial focus after mount. We use $effect with a run-once latch
+  // instead of onMount so jsdom test environments (which do not run
+  // microtask animation frames) still execute it before assertions.
+  // The topLayer action's own initial-focus is disabled
+  // (trapInitialFocus:false) so it does not fight this.
   // -----------------------------------------------------------------
-  let positioned = false;
+  let focused = false;
   $effect(() => {
-    if (!menuEl || positioned) return;
-    positioned = true;
-
-    const initialX = anchorEvent?.clientX ?? 0;
-    const initialY = anchorEvent?.clientY ?? 0;
-
-    // Default to the raw cursor coords, then flip if we would overflow.
-    const rect = menuEl.getBoundingClientRect();
-    const vw = typeof window !== 'undefined' ? window.innerWidth : 1024;
-    const vh = typeof window !== 'undefined' ? window.innerHeight : 768;
-
-    let nextY = initialY;
-    if (initialY + rect.height > vh && initialY - rect.height >= 0) {
-      nextY = Math.max(0, initialY - rect.height);
-    }
-    let nextX = initialX;
-    if (initialX + rect.width > vw && initialX - rect.width >= 0) {
-      nextX = Math.max(0, initialX - rect.width);
-    }
-    menuX = nextX;
-    menuY = nextY;
-
-    // Focus the first menuitem.
-    tick().then(() => {
-      const first = menuEl?.querySelector('[role="menuitem"]');
-      if (first instanceof HTMLElement) first.focus();
-    });
+    if (!menuEl || focused) return;
+    focused = true;
+    const first = menuEl.querySelector('[role="menuitem"]');
+    if (first instanceof HTMLElement) first.focus();
   });
 
   // -----------------------------------------------------------------
@@ -284,10 +275,11 @@
     const target = event.target;
     if (target instanceof Node) {
       if (menuEl.contains(target)) return;
-      // The Mute submenu is portaled to <body> (see {@attach portal()} on
-      // the submenu root), so it is NOT inside `menuEl`. Without this check a
-      // real mouse click on a submenu item fires mousedown first → we'd close
-      // the menu before the click/action fired (mouse Mute was unreachable).
+      // The Mute submenu is a SEPARATE top-layer popover (its own
+      // use:topLayer), so it is NOT a DOM descendant of `menuEl`. Without
+      // this check a real mouse click on a submenu item fires mousedown
+      // first -> we'd close the menu before the click/action fired (mouse
+      // Mute was unreachable).
       const submenuEl = document.querySelector('[data-testid="channel-ctx-submenu"]');
       if (submenuEl && submenuEl.contains(target)) return;
     }
@@ -355,22 +347,23 @@
   }
 
   async function openSubmenu(index) {
-    submenuOpenIndex = index;
     submenuActiveIndex = 0;
-    // Position the submenu to the right of the parent row.
-    await tick();
+    // Measure the parent row and set the submenu anchor coords BEFORE the
+    // submenu renders, so `use:topLayer` positions it correctly on mount
+    // (to the right of the parent row).
     const row = menuEl?.querySelector(`[data-row-index="${index}"]`);
     if (row instanceof HTMLElement) {
       const rect = row.getBoundingClientRect();
       submenuX = rect.right;
       submenuY = rect.top;
-      // Focus the first submenu item.
-      await tick();
-      const firstSub = document.querySelector(
-        '[data-testid="channel-ctx-submenu"] [role="menuitem"]'
-      );
-      if (firstSub instanceof HTMLElement) firstSub.focus();
     }
+    submenuOpenIndex = index;
+    // Focus the first submenu item once it has rendered.
+    await tick();
+    const firstSub = document.querySelector(
+      '[data-testid="channel-ctx-submenu"] [role="menuitem"]'
+    );
+    if (firstSub instanceof HTMLElement) firstSub.focus();
   }
 
   function closeSubmenu() {
@@ -493,12 +486,15 @@
 />
 
 <!--
-  v0.4.4 hotfix (Bug 1): portal the menu into ``document.body`` via the
-  ``portal`` attachment so it escapes any ancestor stacking context
-  created by ``backdrop-filter`` on neighbouring panels (ArtifactPanel /
-  ThreadPanel / SearchPanel / SettingsPanel all use it). Combined with
-  ``z-index: 9999`` below the menu paints above all other UI regardless
-  of where in the DOM it was declared.
+  Overlay overhaul Phase 2 (supersedes the v0.4.4 portal+z9999 fix):
+  `use:topLayer` promotes the menu into the browser native top layer
+  (Popover API) anchored to the cursor, escaping EVERY ancestor stacking
+  context (the backdrop-filter panels that trapped it) - no portal, no
+  z-index. `dismiss: 'manual'`: the component owns outside-click + Escape
+  closing (see handleWindowMouseDown / handleMenuKeydown), which already
+  excludes the submenu so a click on a submenu item never closes the
+  parent (design §F.8) - the browser's auto light-dismiss would not make
+  that distinction across the two sibling top-layer popovers.
 -->
 <div
   bind:this={menuEl}
@@ -506,10 +502,14 @@
   role="menu"
   tabindex="-1"
   data-testid="channel-ctx-menu"
-  style:left="{menuX}px"
-  style:top="{menuY}px"
   onkeydown={handleMenuKeydown}
-  {@attach portal()}
+  use:topLayer={{
+    anchor: anchorRect,
+    placement: 'bottom-start',
+    offset: 0,
+    dismiss: 'manual',
+    trapInitialFocus: false,
+  }}
 >
   {#each items as item, idx (item.id)}
     <button
@@ -540,15 +540,25 @@
 
 {#if submenuOpenIndex !== null}
   {@const sub = items[submenuOpenIndex]?.submenu ?? []}
+  <!--
+    Nested submenu as a SECOND top-layer popover (design §F.8). `manual`
+    so it is fully owned by the parent's open/close logic; anchored to the
+    right edge of the parent row via submenuRect.
+  -->
   <div
     class="channel-ctx-menu submenu"
     role="menu"
     tabindex="-1"
     data-testid="channel-ctx-submenu"
-    style:left="{submenuX}px"
-    style:top="{submenuY}px"
     onkeydown={handleSubmenuKeydown}
-    {@attach portal()}
+    use:topLayer={{
+      anchor: submenuRect,
+      placement: 'bottom-start',
+      offset: 0,
+      dismiss: 'manual',
+      trapInitialFocus: false,
+      restoreFocus: false,
+    }}
   >
     {#each sub as subItem, subIdx (subItem.id)}
       <button
@@ -578,14 +588,9 @@
 
 <style>
   .channel-ctx-menu {
-    position: fixed;
-    /* v0.4.4 hotfix (Bug 1): max-out z-index above every other layer.
-       Used alongside the {@attach portal()} relocation which lifts the
-       element to <body>, escaping any ancestor stacking context
-       (backdrop-filter / filter / transform create them). Either fix
-       in isolation is fragile; both together guarantee top-layer
-       paint. */
-    z-index: 9999;
+    /* Position + top-layer promotion are owned by `use:topLayer` (it sets
+       position:fixed + left/top inline and calls showPopover()); no manual
+       z-index - the native top layer always paints above the app. */
     min-width: 200px;
     background: rgba(37, 37, 40, 0.96);
     backdrop-filter: blur(20px) saturate(1.2);
diff --git a/web/src/components/MemberContextMenu.svelte b/web/src/components/MemberContextMenu.svelte
index da4a17e..5d7ed05 100644
--- a/web/src/components/MemberContextMenu.svelte
+++ b/web/src/components/MemberContextMenu.svelte
@@ -52,9 +52,8 @@
     Escape, or after any action fires.
 -->
 <script>
-  import { tick } from 'svelte';
   import { UserX, BellOff, Bell, MessageSquare } from 'lucide-svelte';
-  import { portal } from '../lib/portal.js';
+  import { topLayer } from '../lib/top-layer.svelte.js';
 
   let {
     member,
@@ -124,41 +123,29 @@
   });
 
   // -----------------------------------------------------------------
-  // Position state. Default to the supplied cursor coords; once the
-  // menu element mounts, the $effect below measures its rect and
-  // flips up / left if it would overflow the viewport. Mount /
-  // unmount per right-click in the parent so a stale anchor cannot
-  // persist between menu instances.
+  // Positioning is delegated to `use:topLayer` (Overlay overhaul, Phase
+  // 2): the menu is promoted into the browser native top layer (Popover
+  // API) anchored to the cursor coords, so it escapes EVERY ancestor
+  // stacking context (the backdrop-filter panels that used to trap it) -
+  // no portal, no manual z-index, no manual flip math (the action clamps
+  // to the viewport). Mount / unmount per right-click in the parent.
   // -----------------------------------------------------------------
-  let menuX = $state(0);
-  let menuY = $state(0);
   let menuEl = $state(/** @type {HTMLElement | null} */ (null));
   let activeIndex = $state(0);
 
-  let positioned = false;
-  $effect(() => {
-    if (!menuEl || positioned) return;
-    positioned = true;
-
-    const rect = menuEl.getBoundingClientRect();
-    const vw = typeof window !== 'undefined' ? window.innerWidth : 1024;
-    const vh = typeof window !== 'undefined' ? window.innerHeight : 768;
-
-    let nextY = y;
-    if (y + rect.height > vh && y - rect.height >= 0) {
-      nextY = Math.max(0, y - rect.height);
-    }
-    let nextX = x;
-    if (x + rect.width > vw && x - rect.width >= 0) {
-      nextX = Math.max(0, x - rect.width);
-    }
-    menuX = nextX;
-    menuY = nextY;
+  // Cursor rect for the anchor: a zero-size rect at (x, y).
+  const anchorRect = () =>
+    typeof DOMRect !== 'undefined' ? new DOMRect(x, y, 0, 0) : null;
 
-    tick().then(() => {
-      const first = menuEl?.querySelector('[role="menuitem"]');
-      if (first instanceof HTMLElement) first.focus();
-    });
+  // Focus the first menuitem on mount so ArrowUp/ArrowDown nav works
+  // immediately (the topLayer action's own initial-focus is disabled via
+  // trapInitialFocus:false so it does not fight this).
+  let focused = false;
+  $effect(() => {
+    if (!menuEl || focused) return;
+    focused = true;
+    const first = menuEl.querySelector('[role="menuitem"]');
+    if (first instanceof HTMLElement) first.focus();
   });
 
   function handleWindowMouseDown(event) {
@@ -229,15 +216,12 @@
 />
 
 <!--
-  v0.4.4 hotfix (Bug 1 + Bug 4): the menu ALWAYS mounts when invoked so
-  users get visible feedback (Bug 4); it is portaled into ``document.body``
-  via the ``portal`` attachment so it escapes any ancestor stacking context
-  (the right-side ArtifactPanel / ThreadPanel / SearchPanel / SettingsPanel
-  all use ``backdrop-filter`` which creates a new stacking context that a
-  ``position: fixed`` element declared INSIDE the sidebar cannot escape via
-  z-index alone). The portal lifts the menu out of ``.app-layout``
-  entirely; combined with ``z-index: 9999`` the menu paints above every
-  other UI surface (Bug 1).
+  Overlay overhaul Phase 2 (supersedes the v0.4.4 portal+z9999 fix): the
+  menu ALWAYS mounts when invoked so users get visible feedback (Bug 4),
+  and `use:topLayer` promotes it into the browser native top layer
+  (Popover API, light-dismiss) anchored to the cursor. The top layer
+  escapes EVERY ancestor stacking context (the backdrop-filter panels that
+  trapped it), so no portal and no z-index are needed (Bug 1).
 -->
 <div
   bind:this={menuEl}
@@ -245,10 +229,15 @@
   role="menu"
   tabindex="-1"
   data-testid="member-ctx-menu"
-  style:left="{menuX}px"
-  style:top="{menuY}px"
   onkeydown={handleMenuKeydown}
-  {@attach portal()}
+  use:topLayer={{
+    anchor: anchorRect,
+    placement: 'bottom-start',
+    offset: 0,
+    dismiss: 'auto',
+    trapInitialFocus: false,
+    onClose,
+  }}
 >
   {#each items as item, idx (item.id)}
     <button
@@ -293,13 +282,9 @@
 
 <style>
   .member-ctx-menu {
-    position: fixed;
-    /* v0.4.4 hotfix (Bug 1): max-out z-index above every other layer
-       in the app. Used alongside the {@attach portal()} relocation
-       which lifts the element to <body>, escaping any ancestor
-       stacking context. Either fix in isolation is fragile; both
-       together guarantee top-layer paint. */
-    z-index: 9999;
+    /* Position + top-layer promotion are owned by `use:topLayer` (it sets
+       position:fixed + left/top inline and calls showPopover()); no manual
+       z-index - the native top layer always paints above the app. */
     min-width: 200px;
     background: rgba(37, 37, 40, 0.96);
     backdrop-filter: blur(20px) saturate(1.2);
diff --git a/web/src/components/ReactionDetailsPanel.svelte b/web/src/components/ReactionDetailsPanel.svelte
index 4d79266..24f7159 100644
--- a/web/src/components/ReactionDetailsPanel.svelte
+++ b/web/src/components/ReactionDetailsPanel.svelte
@@ -9,11 +9,11 @@
     of reactors (resolved names; "You" for self, in natural server insertion
     order). Clicking a different emoji re-filters the user list.
 
-    Rendered TOP-LAYER via the ``portal()`` attachment so it escapes ancestor
-    ``backdrop-filter`` stacking contexts (side panels), positioned ``fixed``
-    from the anchor pill's ``getBoundingClientRect()`` with ``z-index >= 250``
-    (ContextMenu uses 200). Closes on Esc, outside-click, or when its last
-    emoji is removed; if the selected emoji vanishes it falls back to the next.
+    Rendered in the browser native TOP LAYER via ``use:topLayer`` (Popover
+    API) so it escapes ancestor ``backdrop-filter`` stacking contexts (side
+    panels) with NO portal and NO z-index; anchored to the pill's
+    ``getBoundingClientRect()``. Closes on Esc, outside-click, or when its
+    last emoji is removed; if the selected emoji vanishes it falls to the next.
 
   @prop {Array} reactions - Live reaction objects { emoji, count, active,
     users[] } for the message. Reactive — live add/remove updates the open view.
@@ -26,7 +26,7 @@
 -->
 <script>
   import { tick, onMount } from 'svelte';
-  import { portal } from '../lib/portal.js';
+  import { topLayer } from '../lib/top-layer.svelte.js';
 
   let {
     reactions = [],
@@ -92,23 +92,13 @@
     return isSelf ? 'You' : name;
   }
 
-  // ── Positioning (fixed, from the anchor rect; clamped to the viewport) ──
-  const PANEL_W = 280;
-  const GAP = 8;
-  const pos = $derived.by(() => {
-    const vw = typeof window !== 'undefined' ? window.innerWidth : 1024;
-    const vh = typeof window !== 'undefined' ? window.innerHeight : 768;
-    const rect = anchorRect ?? { left: 0, bottom: 0, top: 0 };
-    let left = rect.left ?? 0;
-    if (left + PANEL_W > vw) left = Math.max(8, vw - PANEL_W - 8);
-    // Prefer below the pill; flip above if it would overflow the viewport.
-    let top = (rect.bottom ?? 0) + GAP;
-    const estH = 260;
-    if (top + estH > vh && (rect.top ?? 0) - GAP - estH >= 0) {
-      top = (rect.top ?? 0) - GAP - estH;
-    }
-    return { left, top };
-  });
+  // ── Positioning (Overlay overhaul Phase 2) ──
+  // Delegated to `use:topLayer`, which promotes the panel into the browser
+  // native top layer (Popover API) anchored to the pill's rect and clamps
+  // to the viewport - escaping the side panels' backdrop-filter stacking
+  // contexts with no portal and no z-index. `anchorRect` is a viewport-coords
+  // rect ({left, top, right, bottom}) supplied by the opener.
+  const anchorGetter = () => anchorRect ?? null;
 
   // ── Focus management + outside-click / Esc ──
   $effect(() => {
@@ -177,10 +167,16 @@
   aria-modal="true"
   aria-label="Who reacted"
   tabindex="-1"
-  style:left="{pos.left}px"
-  style:top="{pos.top}px"
   onkeydown={handleKeydown}
-  {@attach portal()}
+  use:topLayer={{
+    anchor: anchorGetter,
+    placement: 'bottom-start',
+    offset: 8,
+    dismiss: 'auto',
+    trapInitialFocus: false,
+    restoreFocus: false,
+    onClose,
+  }}
 >
   <div class="emoji-list" role="tablist" aria-label="Reactions">
     {#each reactions as reaction, i (reaction.emoji)}
@@ -228,8 +224,8 @@
 
 <style>
   .reaction-details {
-    position: fixed;
-    z-index: 250;
+    /* Position + top-layer promotion are owned by `use:topLayer`; no
+       manual position:fixed or z-index - the native top layer wins. */
     width: 280px;
     max-height: 320px;
     display: flex;
diff --git a/web/tests/context-menu-top-layer-bugfix.spec.js b/web/tests/context-menu-top-layer-bugfix.spec.js
index 0431bb1..11b4e8d 100644
--- a/web/tests/context-menu-top-layer-bugfix.spec.js
+++ b/web/tests/context-menu-top-layer-bugfix.spec.js
@@ -1,42 +1,32 @@
-// v0.4.4 hotfix - context menu top-layer regression coverage.
+// Context menu top-layer coverage (Overlay overhaul, Phase 2).
 //
-// Phil's Layer B real-browser pass against v0.4.3 caught that right-click
-// menus (MemberContextMenu + ChannelContextMenu) rendered BEHIND other
-// elements on screen. Root cause: the right-side panels (ArtifactPanel,
-// ThreadPanel, SearchPanel, SettingsPanel) all set ``backdrop-filter``
-// which establishes a new stacking context per CSS Containment Module
-// Level 1. A ``position: fixed; z-index: 250`` declared INSIDE the
-// sidebar component (whose ancestor chain ends at ``.app-layout``) can
-// NOT escape that stacking context - it's painted in document order
-// against its siblings. The right-side panels then render OVER it
-// because they appear later in the DOM tree under ``.app-layout``.
+// HISTORY: Phil's Layer B real-browser pass against v0.4.3 caught that
+// right-click menus (MemberContextMenu + ChannelContextMenu) rendered
+// BEHIND other elements because the right-side panels (ArtifactPanel,
+// ThreadPanel, SearchPanel, SettingsPanel) set ``backdrop-filter`` which
+// establishes a new stacking context that a ``position: fixed; z-index``
+// element declared inside ``.app-layout`` cannot escape. The v0.4.4 fix
+// was a portal into ``document.body`` + ``z-index: 9999``.
 //
-// Why automated Playwright E2E missed this (W-8 anti-pattern per the
-// v0.4.4 iteration log): ``expect(locator).toBeVisible()`` only checks
-// ``display``/``opacity``/``visibility``/in-viewport. Does NOT check
-// z-stacking. A menu rendered BEHIND another element passes
-// ``.toBeVisible()`` cleanly.
+// PHASE 2 SUPERSEDES THAT FIX: both menus now use ``use:topLayer`` (the
+// Popover API), which promotes them into the browser native TOP LAYER -
+// a layer that paints above EVERY stacking context with no portal and no
+// z-index at all. The old portal + ``z-index: 9999`` constants are gone,
+// so this suite no longer pins them (it would otherwise go red).
 //
-// The v0.4.4 fix is two-pronged:
-//   (a) Portal the menu element into ``document.body`` via the new
-//       ``{@attach portal()}`` attachment so it escapes any ancestor
-//       stacking context entirely.
-//   (b) Bump the z-index to ``9999`` so it paints above every other
-//       layer in the app. Either fix in isolation is fragile; both
-//       together guarantee top-layer paint.
-//
-// This suite pins:
-//   1. After mount, both MemberContextMenu and ChannelContextMenu have
-//      their root element as a DIRECT child of ``document.body`` (i.e.
-//      the portal moved them).
-//   2. The element's computed ``z-index`` is the new high-value
-//      (9999) - source-level regex pin so a future refactor that drops
-//      the bump fails the suite.
-//   3. The portal attachment removes the element on unmount (no leftover
-//      DOM under <body>).
+// What this suite now pins (jsdom-safe; the real "painted on top" check
+// lives in Playwright e2e/scenarios/14-overlay-top-layer.spec.ts):
+//   1. Both menus still MOUNT when invoked and render their items.
+//   2. Outside-click (window mousedown) still closes them - the component
+//      keeps that handler so behaviour holds even where the browser's
+//      native popover light-dismiss is unavailable (jsdom).
+//   3. Unmounting removes the element (no leftover DOM).
+//   4. SOURCE invariants: each menu references ``use:topLayer``, no longer
+//      references ``{@attach portal()}``, and carries NO bare z-index
+//      (ChannelContextMenu wires TWO ``use:topLayer`` - menu + submenu).
 
 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
-import { render, cleanup } from '@testing-library/svelte';
+import { render, cleanup, fireEvent } from '@testing-library/svelte';
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, resolve } from 'node:path';
@@ -93,7 +83,7 @@ function channelProps(overrides = {}) {
   };
 }
 
-describe('Context menus - v0.4.4 hotfix top-layer paint', () => {
+describe('Context menus - top-layer via use:topLayer (Phase 2)', () => {
   beforeEach(() => {
     apiGetMock.mockReset();
     mcpCallMock.mockReset();
@@ -101,7 +91,7 @@ describe('Context menus - v0.4.4 hotfix top-layer paint', () => {
 
   afterEach(() => {
     cleanup();
-    // Defensive: clear any leftover portal nodes between tests.
+    // Defensive: clear any leftover menu nodes between tests.
     document
       .querySelectorAll('[data-testid="member-ctx-menu"]')
       .forEach((el) => el.remove());
@@ -110,24 +100,38 @@ describe('Context menus - v0.4.4 hotfix top-layer paint', () => {
       .forEach((el) => el.remove());
   });
 
-  it('MemberContextMenu portals its root into document.body (escapes stacking context)', () => {
+  it('MemberContextMenu mounts and renders its action items', () => {
     render(MemberContextMenu, memberProps());
     const menu = document.querySelector('[data-testid="member-ctx-menu"]');
     expect(menu).not.toBeNull();
-    // The portal attachment moves the element so its parent IS the body.
-    // Without the portal, the parent would be the test container element
-    // that @testing-library/svelte mounts under (typically a div under body).
-    expect(menu.parentNode).toBe(document.body);
+    expect(menu.getAttribute('role')).toBe('menu');
+    // At least one menuitem rendered (mute is always available).
+    expect(menu.querySelectorAll('[role="menuitem"]').length).toBeGreaterThan(0);
   });
 
-  it('ChannelContextMenu portals its root into document.body', () => {
+  it('ChannelContextMenu mounts and renders its action items', () => {
     render(ChannelContextMenu, channelProps());
     const menu = document.querySelector('[data-testid="channel-ctx-menu"]');
     expect(menu).not.toBeNull();
-    expect(menu.parentNode).toBe(document.body);
+    expect(menu.getAttribute('role')).toBe('menu');
+    expect(menu.querySelectorAll('[role="menuitem"]').length).toBeGreaterThan(0);
+  });
+
+  it('MemberContextMenu closes on outside-click (window mousedown) - retained handler', async () => {
+    const onClose = vi.fn();
+    render(MemberContextMenu, memberProps({ onClose }));
+    await fireEvent.mouseDown(document.body);
+    expect(onClose).toHaveBeenCalled();
   });
 
-  it('MemberContextMenu portal cleanup removes the element on unmount', () => {
+  it('ChannelContextMenu closes on outside-click (window mousedown) - retained handler', async () => {
+    const onClose = vi.fn();
+    render(ChannelContextMenu, channelProps({ onClose }));
+    await fireEvent.mouseDown(document.body);
+    expect(onClose).toHaveBeenCalled();
+  });
+
+  it('MemberContextMenu removes its element on unmount (no leftover DOM)', () => {
     const { unmount } = render(MemberContextMenu, memberProps());
     expect(
       document.querySelector('[data-testid="member-ctx-menu"]'),
@@ -138,7 +142,7 @@ describe('Context menus - v0.4.4 hotfix top-layer paint', () => {
     ).toBeNull();
   });
 
-  it('ChannelContextMenu portal cleanup removes the element on unmount', () => {
+  it('ChannelContextMenu removes its element on unmount (no leftover DOM)', () => {
     const { unmount } = render(ChannelContextMenu, channelProps());
     expect(
       document.querySelector('[data-testid="channel-ctx-menu"]'),
@@ -149,51 +153,26 @@ describe('Context menus - v0.4.4 hotfix top-layer paint', () => {
     ).toBeNull();
   });
 
-  it('source-level pin: MemberContextMenu CSS sets z-index 9999 (top-layer)', () => {
-    // P-1 source regex pin (W-8 mitigation per v0.4.4 iteration log).
-    // Bites at edit time so a future refactor cannot drop the z-index
-    // back to 250 and silently re-introduce the stacking-context bug.
+  it('source invariant: MemberContextMenu uses use:topLayer, no portal, no bare z-index', () => {
+    // Supersedes the old z-index:9999 + {@attach portal()} pins (W-8). Bites
+    // at edit time so a regression back to portal/hardcoded-index fails here.
     const HERE = dirname(fileURLToPath(import.meta.url));
-    const SRC = resolve(
-      HERE,
-      '..',
-      'src',
-      'components',
-      'MemberContextMenu.svelte',
-    );
+    const SRC = resolve(HERE, '..', 'src', 'components', 'MemberContextMenu.svelte');
     const src = readFileSync(SRC, 'utf8');
-    // The .member-ctx-menu CSS rule must set z-index: 9999.
-    expect(src).toMatch(/\.member-ctx-menu\s*\{[\s\S]*?z-index:\s*9999/);
-    // And the template must apply the portal attachment.
-    expect(src).toMatch(/\{@attach portal\(\)\}/);
+    expect(src).toMatch(/use:topLayer/);
+    expect(src).not.toMatch(/@attach portal\(\)/);
+    // No bare numeric z-index anywhere (the top layer needs none).
+    expect(src).not.toMatch(/z-index:\s*\d/);
   });
 
-  it('source-level pin: ChannelContextMenu CSS sets z-index 9999 + applies portal attachment', () => {
+  it('source invariant: ChannelContextMenu wires TWO use:topLayer (menu + submenu), no portal, no bare z-index', () => {
     const HERE = dirname(fileURLToPath(import.meta.url));
-    const SRC = resolve(
-      HERE,
-      '..',
-      'src',
-      'components',
-      'ChannelContextMenu.svelte',
-    );
+    const SRC = resolve(HERE, '..', 'src', 'components', 'ChannelContextMenu.svelte');
     const src = readFileSync(SRC, 'utf8');
-    expect(src).toMatch(/\.channel-ctx-menu\s*\{[\s\S]*?z-index:\s*9999/);
-    // Template must apply portal - the submenu uses the same
-    // attachment so we expect at least 2 occurrences.
-    const matches = src.match(/\{@attach portal\(\)\}/g) ?? [];
+    // Menu + nested submenu each get their own top-layer promotion (design §F.8).
+    const matches = src.match(/use:topLayer/g) ?? [];
     expect(matches.length).toBeGreaterThanOrEqual(2);
-  });
-
-  it('portal helper exists at the shared lib path', () => {
-    // Compile-time sanity: importing the module yields a function with
-    // the documented shape (no SSR throw; returns an attachment that
-    // accepts a node).
-    const portalLibPath = '../src/lib/portal.js';
-    return import(portalLibPath).then((mod) => {
-      expect(typeof mod.portal).toBe('function');
-      const attachment = mod.portal();
-      expect(typeof attachment).toBe('function');
-    });
+    expect(src).not.toMatch(/@attach portal\(\)/);
+    expect(src).not.toMatch(/z-index:\s*\d/);
   });
 });
diff --git a/web/tests/reaction-details-panel.spec.js b/web/tests/reaction-details-panel.spec.js
index 87ba5c7..56cdd08 100644
--- a/web/tests/reaction-details-panel.spec.js
+++ b/web/tests/reaction-details-panel.spec.js
@@ -4,7 +4,9 @@
 //   - emoji rows render with counts; selecting a different emoji re-filters
 //     the user list
 //   - reactor names resolve ("You" for self) in natural insertion order
-//   - portaled to <body> with position:fixed + z-index >= 250
+//   - promoted into the browser native top layer via use:topLayer
+//     (position:fixed set by the action, anchored from the rect; no portal,
+//     no z-index)
 //   - Escape closes; outside-click closes
 //   - when the selected emoji vanishes (live removal) it falls to the next;
 //     when all emoji vanish the panel closes
@@ -32,7 +34,7 @@ function anchorRect() {
 afterEach(() => cleanup());
 
 describe('ReactionDetailsPanel', () => {
-  it('portals to <body> and positions from the anchor rect', async () => {
+  it('promotes to the top layer and positions from the anchor rect', async () => {
     render(ReactionDetailsPanel, {
       props: {
         reactions: [reaction('👍', ['bbbbbbbb'])],
@@ -44,13 +46,13 @@ describe('ReactionDetailsPanel', () => {
     await tick();
     const panel = document.body.querySelector('.reaction-details');
     expect(panel).toBeTruthy();
-    // The portal is the actual stacking-context fix: the panel is lifted out
-    // of the component tree to <body> so its (source) z-index:250 / fixed
-    // positioning applies against the page, above the side panels.
-    expect(panel.parentElement).toBe(document.body);
     expect(panel.getAttribute('role')).toBe('dialog');
-    // Positioned from the anchor rect via inline left/top (fixed coords):
-    // anchor.left=100 → left:100px; anchor.bottom=120 + 8px gap → top:128px.
+    // The stacking-context fix is now the browser native top layer
+    // (use:topLayer / Popover API), not a portal + hardcoded z-index. The
+    // action positions the panel with `position: fixed` and anchored coords
+    // (it runs the rect math even under jsdom, where showPopover is a no-op).
+    expect(panel.style.position).toBe('fixed');
+    // anchor.left=100 → left:100px; anchor.bottom=120 + 8px offset → top:128px.
     expect(panel.style.left).toBe('100px');
     expect(panel.style.top).toBe('128px');
   });

From d940e9a9cbf1b1e22d39a0f2523f7805619f7179 Mon Sep 17 00:00:00 2001
From: Phil LaFayette <plafaydev@gmail.com>
Date: Fri, 26 Jun 2026 17:07:57 -0500
Subject: [PATCH 3/6] Overlay Phase 2: migrate manual-portal and raw modals to
 native <dialog>

LeaveChannelDialog, TypeNameConfirmDialog, InviteParticipantDialog,
ChannelDirectoryModal, KeyboardShortcutsHelp, and ForwardPicker now render
a native <dialog> driven by showModal() via use:topLayer (or the <Modal>
wrapper), using the native ::backdrop + built-in focus-trap and inert
background. Drops the manual portals, backdrop elements, position:fixed and
z-index. Existing cancel/confirm handlers retained for jsdom coverage.
---
 .../components/ChannelDirectoryModal.svelte   | 43 +++++++++-------
 web/src/components/ForwardPicker.svelte       | 36 ++++++++++----
 .../components/InviteParticipantDialog.svelte | 38 +++++++-------
 .../components/KeyboardShortcutsHelp.svelte   | 45 +++++++++--------
 web/src/components/LeaveChannelDialog.svelte  | 49 +++++++++++--------
 .../components/TypeNameConfirmDialog.svelte   | 46 +++++++++--------
 6 files changed, 150 insertions(+), 107 deletions(-)

diff --git a/web/src/components/ChannelDirectoryModal.svelte b/web/src/components/ChannelDirectoryModal.svelte
index 31a710c..00c7bcd 100644
--- a/web/src/components/ChannelDirectoryModal.svelte
+++ b/web/src/components/ChannelDirectoryModal.svelte
@@ -33,6 +33,7 @@
   import { X, Search } from 'lucide-svelte';
   import ConversationBrowser from './ConversationBrowser.svelte';
   import ChannelAdminPanel from './ChannelAdminPanel.svelte';
+  import { topLayer } from '../lib/top-layer.svelte.js';
 
   let {
     store,
@@ -160,8 +161,10 @@
     close();
   }
 
-  function handleOverlayClick() {
-    close();
+  function handleOverlayClick(e) {
+    // Native <dialog> backdrop click (target === currentTarget). Content
+    // clicks are stopped by handleContentClick.
+    if (e.target === e.currentTarget) close();
   }
 
   function handleContentClick(e) {
@@ -174,12 +177,8 @@
    * @param {KeyboardEvent} e
    */
   function handleDialogKeydown(e) {
-    if (e.key === 'Escape') {
-      e.preventDefault();
-      e.stopPropagation();
-      close();
-      return;
-    }
+    // Escape is owned by the `topLayer` action (onClose); only the Tab trap
+    // lives here.
     if (e.key === 'Tab') {
       if (!dialogEl) return;
       const focusables = /** @type {HTMLElement[]} */ (
@@ -246,12 +245,18 @@
 </script>
 
 {#if open}
-  <div
+  <!--
+    Overlay overhaul, Phase 2: native <dialog> via use:topLayer (showModal,
+    ::backdrop, focus-trap, inert) - no portal, no position:fixed, no
+    z-index. The action capability-guards for jsdom; the component keeps its
+    own focus + Tab trap + overlay-click. Escape -> action onClose.
+  -->
+  <dialog
     class="directory-overlay"
     data-testid="channel-directory-overlay"
+    use:topLayer={{ modal: true, trapInitialFocus: false, restoreFocus: false, onClose: close }}
     onclick={handleOverlayClick}
     onkeydown={handleDialogKeydown}
-    role="presentation"
   >
     <div
       bind:this={dialogEl}
@@ -392,19 +397,23 @@
         </div>
       {/if}
     </div>
-  </div>
+  </dialog>
 {/if}
 
 <style>
   .directory-overlay {
-    position: fixed;
-    inset: 0;
-    z-index: 200;
+    margin: auto;
+    padding: 0;
+    border: none;
+    background: transparent;
+    max-width: 100vw;
+    max-height: 100vh;
+    overflow: visible;
+  }
+
+  .directory-overlay::backdrop {
     background: rgba(0, 0, 0, 0.6);
     backdrop-filter: blur(4px);
-    display: flex;
-    align-items: center;
-    justify-content: center;
     animation: overlayIn 0.2s ease both;
   }
 
diff --git a/web/src/components/ForwardPicker.svelte b/web/src/components/ForwardPicker.svelte
index 984ec41..2b8972f 100644
--- a/web/src/components/ForwardPicker.svelte
+++ b/web/src/components/ForwardPicker.svelte
@@ -8,16 +8,30 @@
 -->
 <script>
   import { X, Forward } from 'lucide-svelte';
+  import { topLayer } from '../lib/top-layer.svelte.js';
 
   let { channels = [], currentChannel = '', onSelect, onClose } = $props();
 
   let filteredChannels = $derived(
     channels.filter(c => c.id !== currentChannel)
   );
+
+  function handleBackdropMousedown(e) {
+    // Native <dialog> backdrop mousedown (target === currentTarget).
+    if (e.target === e.currentTarget) onClose?.();
+  }
 </script>
 
-<!-- svelte-ignore a11y_no_static_element_interactions -->
-<div class="forward-overlay" onmousedown={onClose}>
+<!--
+  Overlay overhaul, Phase 2: native <dialog> via use:topLayer (showModal,
+  ::backdrop, inert) - no position:fixed, no z-index. Escape -> action
+  onClose; backdrop mousedown also dismisses.
+-->
+<dialog
+  class="forward-overlay"
+  use:topLayer={{ modal: true, trapInitialFocus: false, restoreFocus: false, onClose }}
+  onmousedown={handleBackdropMousedown}
+>
   <!-- svelte-ignore a11y_no_static_element_interactions -->
   <div class="forward-picker" onmousedown={(e) => e.stopPropagation()}>
     <div class="forward-header">
@@ -45,17 +59,21 @@
       {/if}
     </div>
   </div>
-</div>
+</dialog>
 
 <style>
   .forward-overlay {
-    position: fixed;
-    inset: 0;
-    z-index: 200;
+    margin: auto;
+    padding: 0;
+    border: none;
+    background: transparent;
+    max-width: 100vw;
+    max-height: 100vh;
+    overflow: visible;
+  }
+
+  .forward-overlay::backdrop {
     background: rgba(0, 0, 0, 0.5);
-    display: flex;
-    align-items: center;
-    justify-content: center;
     animation: fadeIn 0.15s ease;
   }
 
diff --git a/web/src/components/InviteParticipantDialog.svelte b/web/src/components/InviteParticipantDialog.svelte
index e7e2b21..e490a08 100644
--- a/web/src/components/InviteParticipantDialog.svelte
+++ b/web/src/components/InviteParticipantDialog.svelte
@@ -46,6 +46,7 @@
 <script>
   import { tick } from 'svelte';
   import { X, Search, UserPlus } from 'lucide-svelte';
+  import { topLayer } from '../lib/top-layer.svelte.js';
 
   let {
     channel,
@@ -136,12 +137,8 @@
   });
 
   function handleDialogKeydown(e) {
-    if (e.key === 'Escape') {
-      e.preventDefault();
-      e.stopPropagation();
-      onCancel?.();
-      return;
-    }
+    // Escape is owned by the `topLayer` action (onClose); only the Tab trap
+    // lives here.
     if (e.key !== 'Tab') return;
     if (!dialogEl) return;
     const focusables = /** @type {HTMLElement[]} */ (
@@ -210,16 +207,17 @@
 </script>
 
 <!--
-  Overlay + dialog content. Sibling structure (no portal) so tests
-  mount + observe with @testing-library/svelte queries without portal
-  escape hatches.
+  Overlay overhaul, Phase 2: native <dialog> via use:topLayer (showModal,
+  ::backdrop, focus-trap, inert) - no portal, no position:fixed, no
+  z-index. The action capability-guards for jsdom; the component keeps its
+  own focus management + Tab trap + overlay-click. Escape -> action onClose.
 -->
-<div
+<dialog
   class="invite-overlay"
   data-testid="invite-dialog-overlay"
+  use:topLayer={{ modal: true, trapInitialFocus: false, restoreFocus: false, onClose: onCancel }}
   onclick={handleOverlayClick}
   onkeydown={handleDialogKeydown}
-  role="presentation"
 >
   <div
     bind:this={dialogEl}
@@ -351,18 +349,22 @@
       </button>
     </div>
   </div>
-</div>
+</dialog>
 
 <style>
   .invite-overlay {
-    position: fixed;
-    inset: 0;
-    z-index: 210;
+    margin: auto;
+    padding: 0;
+    border: none;
+    background: transparent;
+    max-width: 100vw;
+    max-height: 100vh;
+    overflow: visible;
+  }
+
+  .invite-overlay::backdrop {
     background: rgba(0, 0, 0, 0.6);
     backdrop-filter: blur(4px);
-    display: flex;
-    align-items: center;
-    justify-content: center;
     animation: overlayIn 0.18s ease both;
   }
 
diff --git a/web/src/components/KeyboardShortcutsHelp.svelte b/web/src/components/KeyboardShortcutsHelp.svelte
index 9072ccd..7702a01 100644
--- a/web/src/components/KeyboardShortcutsHelp.svelte
+++ b/web/src/components/KeyboardShortcutsHelp.svelte
@@ -16,6 +16,7 @@
 -->
 <script>
   import { X, Keyboard } from 'lucide-svelte';
+  import { topLayer } from '../lib/top-layer.svelte.js';
 
   let {
     open = $bindable(false),
@@ -69,31 +70,26 @@
   }
 
   function handleBackdropClick(event) {
-    // Only fire when the click lands on the backdrop itself (not on the
-    // panel content). React-style ``event.target === event.currentTarget``.
+    // Native <dialog> backdrop click (target === currentTarget); content
+    // clicks land on inner nodes.
     if (event.target === event.currentTarget) {
       close();
     }
   }
-
-  function handleKeydown(event) {
-    // Escape close is owned by App.svelte's global ``Escape`` binding (the
-    // registry's universal-close path). The local stopPropagation here
-    // would otherwise eat keydowns the parent listener needs.
-    if (event.key === 'Escape') {
-      event.stopPropagation();
-      close();
-    }
-  }
 </script>
 
 {#if open}
-  <!-- svelte-ignore a11y_no_static_element_interactions -->
-  <div
+  <!--
+    Overlay overhaul, Phase 2: native <dialog> via use:topLayer (showModal,
+    ::backdrop, inert) - no position:fixed, no z-index. Escape is owned by
+    the action (onClose -> close); the component keeps initial-focus +
+    restore management and the backdrop-click handler.
+  -->
+  <dialog
     class="kbd-help-backdrop"
     data-testid="kbd-help-backdrop"
+    use:topLayer={{ modal: true, trapInitialFocus: false, restoreFocus: false, onClose: close }}
     onclick={handleBackdropClick}
-    onkeydown={handleKeydown}
   >
     <div
       bind:this={dialogEl}
@@ -140,19 +136,22 @@
         </ul>
       {/if}
     </div>
-  </div>
+  </dialog>
 {/if}
 
 <style>
   .kbd-help-backdrop {
-    position: fixed;
-    inset: 0;
+    margin: auto;
+    padding: 0;
+    border: none;
+    background: transparent;
+    max-width: 100vw;
+    max-height: 100vh;
+    overflow: visible;
+  }
+
+  .kbd-help-backdrop::backdrop {
     background: rgba(0, 0, 0, 0.55);
-    display: flex;
-    align-items: center;
-    justify-content: center;
-    z-index: 9000;
-    padding: 24px;
     backdrop-filter: blur(2px);
   }
 
diff --git a/web/src/components/LeaveChannelDialog.svelte b/web/src/components/LeaveChannelDialog.svelte
index 4d42831..6b439df 100644
--- a/web/src/components/LeaveChannelDialog.svelte
+++ b/web/src/components/LeaveChannelDialog.svelte
@@ -23,6 +23,8 @@
   @prop {Function} onCancel - Called when the user dismisses the dialog.
 -->
 <script>
+  import { topLayer } from '../lib/top-layer.svelte.js';
+
   let {
     channel,
     messageCount = 0,
@@ -78,15 +80,12 @@
    * Implemented at the dialog root via onkeydown so we don't need to
    * attach per-button handlers and stay robust if a third focusable is
    * added later (it falls back to default Tab order between them).
+   * Escape is owned by the `topLayer` action (it intercepts Escape on the
+   * dialog node, calls onClose, and stops propagation so only the topmost
+   * overlay closes); we only implement the Tab trap here.
    * @param {KeyboardEvent} e
    */
   function handleDialogKeydown(e) {
-    if (e.key === 'Escape') {
-      e.preventDefault();
-      e.stopPropagation();
-      onCancel?.();
-      return;
-    }
     if (e.key !== 'Tab') return;
     if (!dialogEl) return;
     const focusables = /** @type {HTMLElement[]} */ (
@@ -126,8 +125,11 @@
     }
   }
 
-  function handleOverlayClick() {
-    onCancel?.();
+  function handleOverlayClick(e) {
+    // Native <dialog> backdrop: a click on the ::backdrop fires on the
+    // dialog element itself (target === currentTarget). Content clicks land
+    // on inner nodes (and are stopped by handleContentClick).
+    if (e.target === e.currentTarget) onCancel?.();
   }
 
   function handleContentClick(e) {
@@ -138,16 +140,19 @@
 </script>
 
 <!--
-  Overlay is a sibling of dialog; clicking it cancels. We render plain DOM
-  rather than bits-ui Dialog.Portal so tests can mount and observe focus
-  state without a portal escape hatch.
+  Overlay overhaul, Phase 2: the host is a native <dialog> driven by
+  showModal() (via use:topLayer), so it lives in the browser top layer with
+  a free ::backdrop, focus-trap, and inert background - no portal, no
+  position:fixed, no z-index. The action capability-guards for jsdom (the
+  show/hide calls are skipped), so the component keeps its own focus
+  management + Escape/overlay-click handlers for unit-test coverage.
 -->
-<div
+<dialog
   class="leave-overlay"
   data-testid="leave-channel-overlay"
+  use:topLayer={{ modal: true, trapInitialFocus: false, restoreFocus: false, onClose: onCancel }}
   onclick={handleOverlayClick}
   onkeydown={handleDialogKeydown}
-  role="presentation"
 >
   <div
     bind:this={dialogEl}
@@ -202,18 +207,22 @@
       >Leave channel</button>
     </div>
   </div>
-</div>
+</dialog>
 
 <style>
   .leave-overlay {
-    position: fixed;
-    inset: 0;
-    z-index: 200;
+    margin: auto;
+    padding: 0;
+    border: none;
+    background: transparent;
+    max-width: 100vw;
+    max-height: 100vh;
+    overflow: visible;
+  }
+
+  .leave-overlay::backdrop {
     background: rgba(0, 0, 0, 0.6);
     backdrop-filter: blur(4px);
-    display: flex;
-    align-items: center;
-    justify-content: center;
     animation: overlayIn 0.2s ease both;
   }
 
diff --git a/web/src/components/TypeNameConfirmDialog.svelte b/web/src/components/TypeNameConfirmDialog.svelte
index 5f7343d..6e03379 100644
--- a/web/src/components/TypeNameConfirmDialog.svelte
+++ b/web/src/components/TypeNameConfirmDialog.svelte
@@ -35,6 +35,8 @@
   @prop {Function} onCancel - Called on Cancel, Escape, or outside-click.
 -->
 <script>
+  import { topLayer } from '../lib/top-layer.svelte.js';
+
   let {
     resourceName,
     requireTypedName,
@@ -98,15 +100,11 @@
    * Confirm) when Confirm is enabled; two when Confirm is disabled. We
    * compute the focusable set live each Tab press so disabled changes
    * don't strand focus.
+   * Escape is owned by the `topLayer` action (onClose); we only implement
+   * the Tab trap here.
    * @param {KeyboardEvent} e
    */
   function handleDialogKeydown(e) {
-    if (e.key === 'Escape') {
-      e.preventDefault();
-      e.stopPropagation();
-      onCancel?.();
-      return;
-    }
     if (e.key !== 'Tab') return;
     if (!dialogEl) return;
     const focusables = /** @type {HTMLElement[]} */ (
@@ -162,8 +160,10 @@
     if (canConfirm) onConfirm?.();
   }
 
-  function handleOverlayClick() {
-    onCancel?.();
+  function handleOverlayClick(e) {
+    // Native <dialog> backdrop click (target === currentTarget). Content
+    // clicks land on inner nodes and are stopped by handleContentClick.
+    if (e.target === e.currentTarget) onCancel?.();
   }
 
   function handleContentClick(e) {
@@ -174,16 +174,18 @@
 </script>
 
 <!--
-  Overlay is a sibling of dialog; clicking it cancels. Plain DOM (no
-  portal) so tests can mount and observe focus state without a portal
-  escape hatch.
+  Overlay overhaul, Phase 2: native <dialog> via use:topLayer (showModal,
+  ::backdrop, focus-trap, inert) - no portal, no position:fixed, no
+  z-index. The action capability-guards for jsdom; the component keeps its
+  own focus management + Tab trap + overlay-click handler. Escape is owned
+  by the action (onClose).
 -->
-<div
+<dialog
   class="type-name-overlay"
   data-testid="type-name-confirm-overlay"
+  use:topLayer={{ modal: true, trapInitialFocus: false, restoreFocus: false, onClose: onCancel }}
   onclick={handleOverlayClick}
   onkeydown={handleDialogKeydown}
-  role="presentation"
 >
   <div
     bind:this={dialogEl}
@@ -250,18 +252,22 @@
       >{confirmLabel}</button>
     </div>
   </div>
-</div>
+</dialog>
 
 <style>
   .type-name-overlay {
-    position: fixed;
-    inset: 0;
-    z-index: 200;
+    margin: auto;
+    padding: 0;
+    border: none;
+    background: transparent;
+    max-width: 100vw;
+    max-height: 100vh;
+    overflow: visible;
+  }
+
+  .type-name-overlay::backdrop {
     background: rgba(0, 0, 0, 0.6);
     backdrop-filter: blur(4px);
-    display: flex;
-    align-items: center;
-    justify-content: center;
     animation: overlayIn 0.2s ease both;
   }
 

From 2c7ed13ff7d756c9a2ce06c0749c81756fb2d8e0 Mon Sep 17 00:00:00 2001
From: Phil LaFayette <plafaydev@gmail.com>
Date: Fri, 26 Jun 2026 17:08:06 -0500
Subject: [PATCH 4/6] Overlay Phase 2: tokenize residual surfaces onto the
 --z-* scale

Extend the app.css token scale with value-preserving local rungs
(--z-raised/content/elevated) + --z-noise, and collapse every remaining
bare z-index onto var(--z-*): toasts (--z-toast), banners (--z-banner),
docked panels (--z-panel), sidebar (--z-sidebar), in-flow content, and the
App.svelte mobile-sidebar block. Migrate the App.svelte Ctrl+J quick-join
prompt to a native <dialog use:topLayer> with a native ::backdrop, dropping
its manual backdrop + z-index:9000. Toasts/banners stay non-top-layer by
design (a top-layer toast would steal focus / inert the page).
---
 web/src/App.svelte                            | 67 +++++++++----------
 web/src/app.css                               | 20 ++++--
 web/src/components/ArtifactList.svelte        |  4 +-
 web/src/components/ArtifactPanel.svelte       |  6 +-
 web/src/components/ChatView.svelte            |  2 +-
 web/src/components/ConnectionStatus.svelte    |  2 +-
 web/src/components/ConversationBrowser.svelte |  2 +-
 web/src/components/MemberList.svelte          |  2 +-
 web/src/components/MessageActions.svelte      |  2 +-
 web/src/components/MessageBubble.svelte       |  2 +-
 web/src/components/NotificationToast.svelte   |  2 +-
 web/src/components/PinnedPanel.svelte         |  2 +-
 web/src/components/RemoteUpdateBanner.svelte  |  2 +-
 web/src/components/ScrollToBottom.svelte      |  2 +-
 web/src/components/SearchPanel.svelte         |  2 +-
 web/src/components/SettingsPanel.svelte       |  2 +-
 web/src/components/Sidebar.svelte             |  2 +-
 web/src/components/ThreadPanel.svelte         |  4 +-
 web/src/components/UndoToast.svelte           |  2 +-
 web/src/components/UserProfileView.svelte     |  2 +-
 20 files changed, 70 insertions(+), 61 deletions(-)

diff --git a/web/src/App.svelte b/web/src/App.svelte
index cb83b6d..9eae2be 100644
--- a/web/src/App.svelte
+++ b/web/src/App.svelte
@@ -28,6 +28,7 @@
   import MemberContextMenu from './components/MemberContextMenu.svelte';
   import InviteParticipantDialog from './components/InviteParticipantDialog.svelte';
   import NotificationPolicyMenu from './components/NotificationPolicyMenu.svelte';
+  import { topLayer } from './lib/top-layer.svelte.js';
   import { getKeyboardRegistry } from './lib/keyboard.svelte.js';
   import * as api from './lib/api.js';
   import { applyToast } from './lib/toast-coalesce.js';
@@ -1240,23 +1241,22 @@
 {/if}
 
 {#if showQuickJoin}
-  <!-- v0.4.0 Step 2.17 — Ctrl+J quick-join prompt. Minimal inline dialog
-       (single text input + submit). Escape closes via the global priority
-       cascade; submit calls store.joinChannel(value). -->
-  <!-- svelte-ignore a11y_no_static_element_interactions -->
+  <!-- v0.4.0 Step 2.17 — Ctrl+J quick-join prompt. Overlay overhaul Phase 2:
+       now a native <dialog> driven by use:topLayer (showModal), so it lives in
+       the browser top layer with a free native ::backdrop, focus-trap, and an
+       inert background - no manual backdrop element, no portal, no z-index.
+       Backdrop click (e.target === the dialog box) closes; Esc fires the
+       native `cancel` event which the action forwards to cancelQuickJoin. -->
   <!-- svelte-ignore a11y_click_events_have_key_events -->
-  <div
-    class="quick-join-backdrop"
-    data-testid="quick-join-backdrop"
+  <!-- svelte-ignore a11y_no_noninteractive_element_interactions -->
+  <dialog
+    class="quick-join-dialog"
+    aria-label="Quick join channel"
+    data-testid="quick-join-dialog"
+    use:topLayer={{ modal: true, onClose: cancelQuickJoin }}
     onclick={(e) => { if (e.target === e.currentTarget) cancelQuickJoin(); }}
   >
-    <div
-      class="quick-join-dialog"
-      role="dialog"
-      aria-modal="true"
-      aria-label="Quick join channel"
-      data-testid="quick-join-dialog"
-    >
+    <div class="quick-join-inner">
       <label class="quick-join-label" for="quick-join-input">Channel name or ID:</label>
       <!-- svelte-ignore a11y_autofocus -->
       <input
@@ -1294,7 +1294,7 @@
         >Join</button>
       </div>
     </div>
-  </div>
+  </dialog>
 {/if}
 
 <KeyboardShortcutsHelp
@@ -1481,7 +1481,7 @@
     flex-direction: column;
     min-width: 0;
     position: relative;
-    z-index: 1;
+    z-index: var(--z-raised);
     overflow: hidden;
   }
 
@@ -1515,7 +1515,7 @@
       left: 0;
       width: 0;
       height: 100%;
-      z-index: 200;
+      z-index: var(--z-sidebar);
       pointer-events: none;
     }
 
@@ -1532,7 +1532,7 @@
       height: 100%;
       width: 268px;
       min-width: 268px;
-      z-index: 202;
+      z-index: var(--z-content);
       transform: translateX(-100%);
       transition: transform 0.25s cubic-bezier(0.4, 0, 0.2, 1);
       box-shadow: none;
@@ -1548,31 +1548,30 @@
       position: absolute;
       inset: 0;
       background: rgba(0, 0, 0, 0.5);
-      z-index: 201;
+      z-index: var(--z-raised);
       animation: overlayIn 0.2s ease;
     }
   }
 
-  /* v0.4.0 Step 2.17 — Ctrl+J quick-join prompt. Matches the heavier
-   * ChannelDirectoryModal visual treatment but compressed for a single
-   * text input + two action buttons. */
-  .quick-join-backdrop {
-    position: fixed;
-    inset: 0;
-    background: rgba(0, 0, 0, 0.55);
-    display: flex;
-    align-items: center;
-    justify-content: center;
-    z-index: 9000;
-    padding: 24px;
-    backdrop-filter: blur(2px);
-  }
+  /* v0.4.0 Step 2.17 — Ctrl+J quick-join prompt. Overlay overhaul Phase 2:
+   * a native <dialog> in the browser top layer (showModal via use:topLayer).
+   * The scrim is the native ::backdrop - no manual backdrop element and no
+   * z-index. Centering is the <dialog> default (margin:auto). */
   .quick-join-dialog {
+    margin: auto;
+    padding: 0;
     background: var(--bg-elevated, var(--surface-elevated, #1f1c19));
     border: 1px solid var(--border);
     border-radius: 12px;
     box-shadow: 0 12px 48px rgba(0, 0, 0, 0.5);
-    width: min(420px, 100%);
+    width: min(420px, 92vw);
+    max-width: 92vw;
+  }
+  .quick-join-dialog::backdrop {
+    background: rgba(0, 0, 0, 0.55);
+    backdrop-filter: blur(2px);
+  }
+  .quick-join-inner {
     padding: 20px;
     display: flex;
     flex-direction: column;
diff --git a/web/src/app.css b/web/src/app.css
index 72bfc83..89f0dfb 100644
--- a/web/src/app.css
+++ b/web/src/app.css
@@ -95,16 +95,26 @@
    * / Popover API `showPopover()`) - the top layer always wins, ordered
    * by promotion time.
    *
-   * Nothing above --z-toast (60) should exist in CSS once the migration
-   * completes. Phase 1 only ADDS these tokens; the app-wide collapse of
-   * the existing z-index jumble onto this scale is Phase 2.
+   * Phase 2 collapsed the whole app onto this scale: every bare z-index
+   * is now a token. The low `--z-raised/content/elevated` rungs cover
+   * LOCAL intra-component stacking (a child above a decorative
+   * pseudo-element, layered inputs, hover accents) - they are
+   * value-preserving so no stacking order changed. Floating overlays
+   * (modals, menus, dropdowns, popovers, context menus, tooltips) carry
+   * NO z-index: they live in the browser native top layer, which always
+   * wins regardless of these tokens.
    */
   --z-base: 0;       /* in-flow content */
-  --z-sticky: 10;    /* sticky headers, date separators, scroll-to-bottom */
+  --z-raised: 1;     /* local: content above a decorative ::before/::after */
+  --z-content: 2;    /* local: layered content / inputs */
+  --z-elevated: 5;   /* local: hover actions, accents, scroll-to-bottom */
+  --z-sticky: 10;    /* sticky headers, date separators, message actions */
   --z-banner: 20;    /* connection status, remote-update banner */
   --z-sidebar: 30;   /* sidebar / docked rails */
   --z-panel: 40;     /* right-side sheets: thread/artifact/search/settings */
   --z-toast: 60;     /* notification + undo toasts (passive, NOT top layer) */
+  --z-noise: 999;    /* decorative full-screen noise; topmost PASSIVE layer
+                        (still below the native top layer, which has no index) */
 }
 
 /*
@@ -279,7 +289,7 @@ body::after {
   position: fixed;
   inset: 0;
   pointer-events: none;
-  z-index: 999;
+  z-index: var(--z-noise);
   opacity: 0.015;
   background-image: url("data:image/svg+xml,%3Csvg viewBox='0 0 256 256' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.9' numOctaves='4' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23n)'/%3E%3C/svg%3E");
   background-repeat: repeat;
diff --git a/web/src/components/ArtifactList.svelte b/web/src/components/ArtifactList.svelte
index 80d3738..bdafb1c 100644
--- a/web/src/components/ArtifactList.svelte
+++ b/web/src/components/ArtifactList.svelte
@@ -311,7 +311,7 @@
 
   .artifact-item-top {
     position: relative;
-    z-index: 1;
+    z-index: var(--z-raised);
     display: flex;
     align-items: center;
     gap: 8px;
@@ -341,7 +341,7 @@
 
   .artifact-item-bottom {
     position: relative;
-    z-index: 1;
+    z-index: var(--z-raised);
     display: flex;
     align-items: center;
     gap: 10px;
diff --git a/web/src/components/ArtifactPanel.svelte b/web/src/components/ArtifactPanel.svelte
index 3c5053d..1878c0c 100644
--- a/web/src/components/ArtifactPanel.svelte
+++ b/web/src/components/ArtifactPanel.svelte
@@ -730,7 +730,7 @@
     /* width comes from the inline style bound to `panelWidth` */
     min-width: 320px;
     max-width: 900px;
-    z-index: 104;
+    z-index: var(--z-panel);
     background: rgba(20, 20, 22, 0.96);
     backdrop-filter: blur(16px);
     border-left: 1px solid var(--border);
@@ -758,7 +758,7 @@
     width: 6px;
     height: 100%;
     cursor: ew-resize;
-    z-index: 110;
+    z-index: var(--z-panel);
     background: transparent;
     transition: background 120ms ease;
     /* Keep the hit-target easy to grab without shifting layout. */
@@ -894,7 +894,7 @@
     font-weight: 600;
     box-shadow: 0 4px 16px rgba(0, 0, 0, 0.3);
     animation: toastIn 0.18s cubic-bezier(0.16, 1, 0.3, 1) both;
-    z-index: 20;
+    z-index: var(--z-banner);
   }
 
   @keyframes toastIn {
diff --git a/web/src/components/ChatView.svelte b/web/src/components/ChatView.svelte
index 9321b0d..84f1c44 100644
--- a/web/src/components/ChatView.svelte
+++ b/web/src/components/ChatView.svelte
@@ -373,7 +373,7 @@
     flex-direction: column;
     gap: 4px;
     position: relative;
-    z-index: 1;
+    z-index: var(--z-raised);
     scroll-behavior: smooth;
     mask-image: linear-gradient(transparent, black 20px, black calc(100% - 20px), transparent);
     -webkit-mask-image: linear-gradient(transparent, black 20px, black calc(100% - 20px), transparent);
diff --git a/web/src/components/ConnectionStatus.svelte b/web/src/components/ConnectionStatus.svelte
index 76203c8..7044154 100644
--- a/web/src/components/ConnectionStatus.svelte
+++ b/web/src/components/ConnectionStatus.svelte
@@ -202,7 +202,7 @@
     font-size: 11.5px;
     font-weight: 500;
     position: relative;
-    z-index: 2;
+    z-index: var(--z-banner);
     transition: all 0.3s ease;
   }
 
diff --git a/web/src/components/ConversationBrowser.svelte b/web/src/components/ConversationBrowser.svelte
index f3dca0d..d5fe0c0 100644
--- a/web/src/components/ConversationBrowser.svelte
+++ b/web/src/components/ConversationBrowser.svelte
@@ -415,7 +415,7 @@
     right: 0;
     bottom: 0;
     width: 380px;
-    z-index: 104;
+    z-index: var(--z-panel);
     background: rgba(20, 20, 22, 0.96);
     backdrop-filter: blur(16px);
     border-left: 1px solid var(--border);
diff --git a/web/src/components/MemberList.svelte b/web/src/components/MemberList.svelte
index 5d08715..7d5662d 100644
--- a/web/src/components/MemberList.svelte
+++ b/web/src/components/MemberList.svelte
@@ -475,7 +475,7 @@
     flex-direction: column;
     overflow: hidden;
     position: relative;
-    z-index: 1;
+    z-index: var(--z-raised);
   }
 
   @media (max-width: 640px) {
diff --git a/web/src/components/MessageActions.svelte b/web/src/components/MessageActions.svelte
index b67efe8..23924f1 100644
--- a/web/src/components/MessageActions.svelte
+++ b/web/src/components/MessageActions.svelte
@@ -38,7 +38,7 @@
     border-radius: 8px;
     padding: 2px;
     box-shadow: 0 4px 16px rgba(0,0,0,0.4), 0 0 0 1px rgba(255,255,255,0.03);
-    z-index: 10;
+    z-index: var(--z-sticky);
   }
 
   :global(.msg-row.human) .msg-actions { right: auto; left: 10px; }
diff --git a/web/src/components/MessageBubble.svelte b/web/src/components/MessageBubble.svelte
index 6cdceec..7764505 100644
--- a/web/src/components/MessageBubble.svelte
+++ b/web/src/components/MessageBubble.svelte
@@ -865,7 +865,7 @@
     transition: opacity var(--transition-fast);
     white-space: nowrap;
     pointer-events: none;
-    z-index: 5;
+    z-index: var(--z-elevated);
   }
 
   /* Human bubbles align right, but the tooltip stays centered above the
diff --git a/web/src/components/NotificationToast.svelte b/web/src/components/NotificationToast.svelte
index 6bc8508..4a9c53d 100644
--- a/web/src/components/NotificationToast.svelte
+++ b/web/src/components/NotificationToast.svelte
@@ -117,7 +117,7 @@
     position: fixed;
     top: 16px;
     right: 16px;
-    z-index: 100;
+    z-index: var(--z-toast);
     display: flex;
     align-items: flex-start;
     gap: 12px;
diff --git a/web/src/components/PinnedPanel.svelte b/web/src/components/PinnedPanel.svelte
index ee2c4db..7e0139a 100644
--- a/web/src/components/PinnedPanel.svelte
+++ b/web/src/components/PinnedPanel.svelte
@@ -47,7 +47,7 @@
     position: absolute;
     top: 88px;
     right: 16px;
-    z-index: 105;
+    z-index: var(--z-panel);
     width: 340px;
     background: rgba(37, 37, 40, 0.92);
     backdrop-filter: blur(20px) saturate(1.2);
diff --git a/web/src/components/RemoteUpdateBanner.svelte b/web/src/components/RemoteUpdateBanner.svelte
index 66d9e56..c8fcc4d 100644
--- a/web/src/components/RemoteUpdateBanner.svelte
+++ b/web/src/components/RemoteUpdateBanner.svelte
@@ -142,7 +142,7 @@
     border-left: 3px solid var(--ember-500);
     border-bottom: 1px solid var(--border);
     animation: banner-slide-in 200ms ease-out both;
-    z-index: 15;
+    z-index: var(--z-banner);
   }
 
   .remote-update-banner:focus {
diff --git a/web/src/components/ScrollToBottom.svelte b/web/src/components/ScrollToBottom.svelte
index c03746d..08e44de 100644
--- a/web/src/components/ScrollToBottom.svelte
+++ b/web/src/components/ScrollToBottom.svelte
@@ -25,7 +25,7 @@
     bottom: 90px;
     left: 50%;
     transform: translateX(-50%);
-    z-index: 5;
+    z-index: var(--z-elevated);
     width: 38px;
     height: 38px;
     border-radius: 50%;
diff --git a/web/src/components/SearchPanel.svelte b/web/src/components/SearchPanel.svelte
index 1f58eea..9c4317e 100644
--- a/web/src/components/SearchPanel.svelte
+++ b/web/src/components/SearchPanel.svelte
@@ -157,7 +157,7 @@
     right: 0;
     bottom: 0;
     width: 380px;
-    z-index: 50;
+    z-index: var(--z-panel);
     background: rgba(20, 20, 22, 0.96);
     backdrop-filter: blur(20px);
     border-left: 1px solid var(--border);
diff --git a/web/src/components/SettingsPanel.svelte b/web/src/components/SettingsPanel.svelte
index c47f6c7..c12ed29 100644
--- a/web/src/components/SettingsPanel.svelte
+++ b/web/src/components/SettingsPanel.svelte
@@ -384,7 +384,7 @@
     right: 0;
     bottom: 0;
     width: 380px;
-    z-index: 50;
+    z-index: var(--z-panel);
     background: rgba(20, 20, 22, 0.96);
     backdrop-filter: blur(20px);
     border-left: 1px solid var(--border);
diff --git a/web/src/components/Sidebar.svelte b/web/src/components/Sidebar.svelte
index cb950e0..8b35950 100644
--- a/web/src/components/Sidebar.svelte
+++ b/web/src/components/Sidebar.svelte
@@ -469,7 +469,7 @@
 </aside>
 
 <style>
-  .sidebar-left { width: var(--sidebar-w); min-width: var(--sidebar-w); background: var(--bg-sidebar); backdrop-filter: blur(20px); border-right: 1px solid var(--border); display: flex; flex-direction: column; overflow: hidden; position: relative; z-index: 1; }
+  .sidebar-left { width: var(--sidebar-w); min-width: var(--sidebar-w); background: var(--bg-sidebar); backdrop-filter: blur(20px); border-right: 1px solid var(--border); display: flex; flex-direction: column; overflow: hidden; position: relative; z-index: var(--z-sidebar); }
   .sidebar-left::after { content: ''; position: absolute; top: 0; right: 0; bottom: 0; width: 1px; background: linear-gradient(180deg, rgba(245,158,11,0.06), transparent 30%, transparent 70%, rgba(245,158,11,0.04)); pointer-events: none; }
   .sidebar-brand { padding: 22px 18px 16px; display: flex; align-items: center; gap: 11px; }
   .sidebar-brand h1 { font-size: 17px; font-weight: 800; letter-spacing: -0.4px; background: linear-gradient(135deg, var(--ember-400), var(--ember-300), var(--gold)); -webkit-background-clip: text; -webkit-text-fill-color: transparent; background-clip: text; }
diff --git a/web/src/components/ThreadPanel.svelte b/web/src/components/ThreadPanel.svelte
index 19f76fb..d285caf 100644
--- a/web/src/components/ThreadPanel.svelte
+++ b/web/src/components/ThreadPanel.svelte
@@ -289,7 +289,7 @@
     /* width comes from the inline style bound to `panelWidth` (v0.4.3 drag-resize) */
     min-width: 280px;
     max-width: 720px;
-    z-index: 45;
+    z-index: var(--z-panel);
     background: rgba(17, 17, 19, 0.97);
     backdrop-filter: blur(24px) saturate(1.3);
     border-left: 1px solid var(--border);
@@ -317,7 +317,7 @@
     width: 6px;
     height: 100%;
     cursor: ew-resize;
-    z-index: 110;
+    z-index: var(--z-panel);
     background: transparent;
     transition: background 120ms ease;
     /* Keep the hit-target easy to grab without shifting layout. */
diff --git a/web/src/components/UndoToast.svelte b/web/src/components/UndoToast.svelte
index d165d06..3ad0c36 100644
--- a/web/src/components/UndoToast.svelte
+++ b/web/src/components/UndoToast.svelte
@@ -160,7 +160,7 @@
     position: fixed;
     bottom: 16px;
     right: 16px;
-    z-index: 100;
+    z-index: var(--z-toast);
     display: flex;
     align-items: center;
     gap: 12px;
diff --git a/web/src/components/UserProfileView.svelte b/web/src/components/UserProfileView.svelte
index 6e65304..926e0b1 100644
--- a/web/src/components/UserProfileView.svelte
+++ b/web/src/components/UserProfileView.svelte
@@ -87,7 +87,7 @@
     right: 0;
     bottom: 0;
     width: 380px;
-    z-index: 50;
+    z-index: var(--z-panel);
     background: rgba(20, 20, 22, 0.96);
     backdrop-filter: blur(20px);
     border-left: 1px solid var(--border);

From c529204dee1e26422a79acdec93aa07e2c4d4e42 Mon Sep 17 00:00:00 2001
From: Phil LaFayette <plafaydev@gmail.com>
Date: Fri, 26 Jun 2026 17:08:13 -0500
Subject: [PATCH 5/6] Overlay Phase 2: flip the Tier-1 guard to STRICT

Shrink the ALLOWED set to its irreducible core: the passive
toasts/banners (must NOT be top layer, design F.5) and the three bits-ui
components (ContextMenu/ChannelModal/ConfirmDialog, design F.1). Every
other overlay/panel/in-flow file plus App.svelte and app.css now passes
both rules on merit (uses the primitive, carries only var(--z-*) tokens).
Update the comments + the self-doc test to assert the strict core.
---
 web/tests/overlay-top-layer-guard.spec.js | 104 +++++++++-------------
 1 file changed, 40 insertions(+), 64 deletions(-)

diff --git a/web/tests/overlay-top-layer-guard.spec.js b/web/tests/overlay-top-layer-guard.spec.js
index 7f26f2f..df4c032 100644
--- a/web/tests/overlay-top-layer-guard.spec.js
+++ b/web/tests/overlay-top-layer-guard.spec.js
@@ -20,21 +20,26 @@
 //      with the file - this is the rule that would have caught a "9999
 //      left behind" or a new ad-hoc "73".
 //
-// ── PHASE 1 SEEDING (read this before editing ALLOWED) ───────────────────
-// The rules are ACTIVE, but ALLOWED is seeded to TODAY's reality so the
-// pre-migration tree stays green: it lists every currently-unmigrated
-// overlay, the passive toasts/banners, the docked panels, the bits-ui
-// components, and app.css (whose legacy z-index values are tokenised in
-// Phase 2). Files in ALLOWED are skipped by BOTH rules.
+// ── STRICT MODE (Phase 2 complete) ───────────────────────────────────────
+// Every floating overlay has been migrated to the primitive and every
+// residual surface tokenised onto the --z-* scale, so ALLOWED is now shrunk
+// to its irreducible core. Files in ALLOWED are skipped by BOTH rules; the
+// ONLY remaining entries are:
 //
-// StatusEditor.svelte is INTENTIONALLY NOT in ALLOWED: it was migrated to
-// <Popover>/use:topLayer in this PR, so it must pass the rules by actually
-// using the primitive and carrying no bare z-index. The explicit
-// assertions at the bottom pin that.
+//   * The PASSIVE notification surfaces (toasts + banners). These MUST stay
+//     out of the native top layer - a top-layer toast would steal focus /
+//     inert the page, wrong for a passive notification - so they keep a
+//     `position: fixed` + `var(--z-toast)`/`var(--z-banner)` token. Because
+//     Rule 1 flags `position:fixed` paired with any z-index, they are
+//     exempted here by design (design §F.5).
+//   * The three bits-ui components (ContextMenu / ChannelModal /
+//     ConfirmDialog). bits-ui portals them to <body> with its own tested
+//     focus-trap; design §F.1 keeps them as-is and exempts them.
 //
-// PHASE 2 shrinks ALLOWED toward EMPTY: as each overlay migrates to the
-// primitive (and each residual surface moves onto the --z-* tokens),
-// delete its entry here. When ALLOWED is empty the guard is fully strict.
+// EVERYTHING else - all migrated overlays, all docked panels, every in-flow
+// component, App.svelte and app.css - now passes BOTH rules ON MERIT (uses
+// the primitive and carries only `var(--z-*)` tokens). Adding anything new
+// here should be a deliberate, documented exception, not a convenience.
 
 import { describe, it, expect } from 'vitest';
 import { readFileSync, readdirSync } from 'node:fs';
@@ -47,59 +52,20 @@ const COMPONENTS_DIR = resolve(SRC, 'components');
 const APP_SVELTE = resolve(SRC, 'App.svelte');
 const APP_CSS = resolve(SRC, 'app.css');
 
-// ── Phase 1 ALLOWED seed (see header). Basenames. ───────────────────────
-// Every entry is a pre-existing violator kept green until Phase 2 migrates
-// it. The bits-ui components (ContextMenu / ChannelModal / ConfirmDialog /
-// LeaveChannelDialog) are also here: design §F.1 keeps them on bits-ui;
-// they portal to <body> so the bug class does not apply.
+// ── STRICT ALLOWED set (basenames). See header for the rationale. ───────
+// Only the passive toasts/banners and the three bits-ui components remain.
 const ALLOWED = new Set([
-  // residual passive surfaces (stay non-top-layer; move to --z-* in Phase 2)
+  // Passive notification surfaces - intentionally NOT top layer (design §F.5).
   'NotificationToast.svelte',
   'UndoToast.svelte',
   'RemoteUpdateBanner.svelte',
   'ConnectionStatus.svelte',
-  // docked panels (stacking-context creators; tokenised in Phase 2)
-  'Sidebar.svelte',
-  'SettingsPanel.svelte',
-  'SearchPanel.svelte',
-  'ArtifactPanel.svelte',
-  'ThreadPanel.svelte',
-  'PinnedPanel.svelte',
-  'ConversationBrowser.svelte',
-  'UserProfileView.svelte',
-  'ArtifactList.svelte',
-  'MemberList.svelte',
-  'MessageBubble.svelte',
-  'MessageActions.svelte',
-  'MessageInput.svelte',
-  'ChatView.svelte',
-  'ScrollToBottom.svelte',
-  // bits-ui components (design §F.1: KEEP, exempt)
+  // bits-ui components - portal to <body> with their own focus-trap (design §F.1).
   'ContextMenu.svelte',
   'ChannelModal.svelte',
   'ConfirmDialog.svelte',
-  'LeaveChannelDialog.svelte',
-  // unmigrated floating overlays (Phase 2 targets)
-  'InviteParticipantDialog.svelte',
-  'ProfileCard.svelte',
-  'NotificationPolicyMenu.svelte',
-  'ForwardPicker.svelte',
-  'KeyboardShortcutsHelp.svelte',
-  'ReactionBar.svelte',
-  'ChannelContextMenu.svelte',
-  'ArtifactDetailHeader.svelte',
-  'ReadReceipt.svelte',
-  'EmojiPicker.svelte',
-  'ChannelDirectoryModal.svelte',
-  'TypeNameConfirmDialog.svelte',
-  'MentionDropdown.svelte',
-  'MemberContextMenu.svelte',
-  'ReactionDetailsPanel.svelte',
-  // root + global stylesheet (App quick-join / mobile-sidebar block; legacy
-  // app.css z-index values) - tokenised in Phase 2.
-  'App.svelte',
-  'app.css',
-  // NOTE: StatusEditor.svelte is deliberately ABSENT - it must pass on merit.
+  // NOTE: every other overlay/panel/in-flow file (and App.svelte / app.css) is
+  // deliberately ABSENT - each must pass BOTH rules on merit.
 ]);
 
 // Approved primitive / escape references that satisfy Rule 1.
@@ -236,11 +202,21 @@ describe('overlay top-layer guard - Tier 1 source scan (design §E)', () => {
     }
   });
 
-  // ── Guard self-documentation: Phase 2 shrinks ALLOWED toward empty ──────
-  it('ALLOWED is a finite seed that Phase 2 will shrink (documented)', () => {
-    // Sanity: the seed is non-empty today (Phase 1) and StatusEditor proves
-    // the rules are live. This assertion exists so a future reader sees the
-    // intent; Phase 2 deletes entries until the set is empty.
-    expect(ALLOWED.size).toBeGreaterThan(0);
+  // ── Guard self-documentation: STRICT mode irreducible core ──────────────
+  it('ALLOWED is shrunk to its strict-mode core (toasts/banners + bits-ui)', () => {
+    // Phase 2 reduced ALLOWED to exactly the passive notification surfaces
+    // (design §F.5) plus the three bits-ui components (design §F.1). If this
+    // grows, a real overlay is probably dodging the primitive - scrutinise it.
+    expect([...ALLOWED].sort()).toEqual(
+      [
+        'ChannelModal.svelte',
+        'ConfirmDialog.svelte',
+        'ConnectionStatus.svelte',
+        'ContextMenu.svelte',
+        'NotificationToast.svelte',
+        'RemoteUpdateBanner.svelte',
+        'UndoToast.svelte',
+      ].sort(),
+    );
   });
 });

From 60081c4a52d16537ba82885e7828d875c6bf236a Mon Sep 17 00:00:00 2001
From: Phil LaFayette <plafaydev@gmail.com>
Date: Fri, 26 Jun 2026 17:16:07 -0500
Subject: [PATCH 6/6] Overlay Phase 2: extend e2e for migrated overlays; fix
 source-pins

Scenario 14 gains on-top + native-pseudo-class assertions for the new
trap pairs: MentionDropdown over the message list (:popover-open),
ChannelContextMenu over an open backdrop-filter panel (:popover-open), and
the quick-join native :modal dialog (inert background + Esc dismiss), all
via expectLocatorOnTop. Rewrite the 04/05 source-pins that asserted the
removed z-index:9999 + @attach portal() to assert use:topLayer instead, and
update the ProfileCard dismiss test to a real outside-click (its backdrop
element is gone).
---
 .../scenarios/04-member-context-menu.spec.ts  | 19 ++--
 .../scenarios/05-invite-participant.spec.ts   | 15 +--
 web/e2e/scenarios/11-profile-card.spec.ts     |  8 +-
 .../scenarios/14-overlay-top-layer.spec.ts    | 99 +++++++++++++++++++
 4 files changed, 122 insertions(+), 19 deletions(-)

diff --git a/web/e2e/scenarios/04-member-context-menu.spec.ts b/web/e2e/scenarios/04-member-context-menu.spec.ts
index 1a86924..0681f25 100644
--- a/web/e2e/scenarios/04-member-context-menu.spec.ts
+++ b/web/e2e/scenarios/04-member-context-menu.spec.ts
@@ -430,17 +430,16 @@ test.describe('Scenario 04 v0.4.4 enhancements: W-8 + W-12 coverage', () => {
     assertNoConsoleErrors(consoleErrors);
   });
 
-  test('source-level pin: MemberContextMenu portals to <body> (W-8)', () => {
-    // P-1 + W-8 source side: the v0.4.4 fix relocates the menu DOM under
-    // <body> via Svelte 5 `{@attach portal()}`. If the attachment is
-    // removed, the menu falls back to its native location (inside the
-    // backdrop-filter stacking context) and Phil's Bug 1 returns.
+  test('source-level pin: MemberContextMenu uses the top-layer primitive (W-8)', () => {
+    // Overlay overhaul Phase 2 supersedes the v0.4.4 portal+z9999 fix: the
+    // menu now promotes into the browser native top layer via use:topLayer
+    // (Popover API), which escapes the backdrop-filter stacking contexts with
+    // NO portal and NO z-index. If this regresses to a portal or a hardcoded
+    // index, Phil's Bug 1 risk returns - so pin the new primitive instead.
     const src = readFileSync(MEMBER_CTX_PATH, 'utf-8');
-    // Pin the attach directive + the portal import.
-    expect(src).toMatch(/\{@attach\s+portal\(\)\}/);
-    expect(src).toMatch(/from\s+['"][^'"]*portal/);
-    // Pin the z-index bump (post-v0.4.4 = 9999, pre-v0.4.4 = 250).
-    expect(src).toMatch(/z-index:\s*9999/);
+    expect(src).toMatch(/use:topLayer/);
+    expect(src).not.toMatch(/\{@attach\s+portal\(\)\}/);
+    expect(src).not.toMatch(/z-index:\s*\d/);
   });
 
   test('source-level pin: portal helper exists at lib/portal.js (W-8)', () => {
diff --git a/web/e2e/scenarios/05-invite-participant.spec.ts b/web/e2e/scenarios/05-invite-participant.spec.ts
index 35b0db5..afdfbda 100644
--- a/web/e2e/scenarios/05-invite-participant.spec.ts
+++ b/web/e2e/scenarios/05-invite-participant.spec.ts
@@ -538,8 +538,8 @@ test.describe('Scenario 05 v0.4.4 enhancements: W-8 top-layer coverage', () => {
     await row.click({ button: 'right' });
     const menu = appPage.locator('[data-testid="channel-ctx-menu"]');
     await expect(menu).toBeVisible();
-    // W-8: hit-test the menu center to confirm it is on top. v0.4.4 fix
-    // portals + bumps z-index to 9999.
+    // W-8: hit-test the menu center to confirm it is on top. Phase 2 puts it
+    // in the browser native top layer via use:topLayer (no portal/z-index).
     await expectLocatorOnTop(appPage, menu);
     await appPage.keyboard.press('Escape');
     assertNoConsoleErrors(consoleErrors);
@@ -554,10 +554,13 @@ test.describe('Scenario 05 v0.4.4 enhancements: W-8 top-layer coverage', () => {
     assertNoConsoleErrors(consoleErrors);
   });
 
-  test('source-level pin: ChannelContextMenu portals + z-index 9999 (W-8)', () => {
+  test('source-level pin: ChannelContextMenu uses the top-layer primitive (W-8)', () => {
     const src = readFileSync(CHANNEL_CTX_MENU_PATH, 'utf-8');
-    // The v0.4.4 fix applied portal to both the main menu AND the submenu.
-    expect(src).toMatch(/\{@attach\s+portal\(\)\}/);
-    expect(src).toMatch(/z-index:\s*9999/);
+    // Phase 2: the menu AND its submenu each promote into the native top
+    // layer via use:topLayer (design §F.8) - no portal, no hardcoded z-index.
+    const matches = src.match(/use:topLayer/g) ?? [];
+    expect(matches.length).toBeGreaterThanOrEqual(2);
+    expect(src).not.toMatch(/\{@attach\s+portal\(\)\}/);
+    expect(src).not.toMatch(/z-index:\s*\d/);
   });
 });
diff --git a/web/e2e/scenarios/11-profile-card.spec.ts b/web/e2e/scenarios/11-profile-card.spec.ts
index bb18a06..3d6f15d 100644
--- a/web/e2e/scenarios/11-profile-card.spec.ts
+++ b/web/e2e/scenarios/11-profile-card.spec.ts
@@ -36,10 +36,12 @@ test.describe('Scenario 11: profile card', () => {
     assertNoConsoleErrors(consoleErrors);
   });
 
-  test('clicking the backdrop dismisses the card', async ({ appPage, consoleErrors }) => {
+  test('clicking outside dismisses the card', async ({ appPage, consoleErrors }) => {
     await openOwnProfile(appPage);
-    // Click the backdrop corner (away from the centered card) to fire onClose.
-    await appPage.locator('[data-testid="profile-card-close"]').click({ position: { x: 5, y: 5 } });
+    // Overlay overhaul Phase 2: the card is a top-layer popover with no
+    // backdrop element; a click well outside it fires the component's
+    // window-level outside-click handler -> onClose.
+    await appPage.mouse.click(5, 5);
     await expect(appPage.locator('[data-testid="profile-card"]')).not.toBeVisible();
     assertNoConsoleErrors(consoleErrors);
   });
diff --git a/web/e2e/scenarios/14-overlay-top-layer.spec.ts b/web/e2e/scenarios/14-overlay-top-layer.spec.ts
index c02e489..6b390bc 100644
--- a/web/e2e/scenarios/14-overlay-top-layer.spec.ts
+++ b/web/e2e/scenarios/14-overlay-top-layer.spec.ts
@@ -130,3 +130,102 @@ test.describe('Scenario 14: StatusEditor in the native top layer', () => {
     assertNoConsoleErrors(consoleErrors);
   });
 });
+
+// ── Phase 2: the newly-migrated overlays over deliberately-occluding
+// surfaces (design §E Tier-2 / §F worst-case trap pairs). Each asserts the
+// real "painted on top" hit-test PLUS the native top-layer pseudo-class
+// (:popover-open for popovers, :modal for the dialog) that only Chromium can
+// evaluate.
+async function openGeneral(appPage: import('@playwright/test').Page) {
+  await appPage.waitForSelector('[data-testid="sidebar-sections"]');
+  await appPage.locator('[data-testid="sidebar-channel-row-general"]').click();
+  await appPage.waitForSelector('[data-testid="chat-view"]');
+}
+
+test.describe('Scenario 14: anchored popovers + native modal in the top layer', () => {
+  test('MentionDropdown paints ON TOP over the message list AND is :popover-open', async ({
+    appPage,
+    consoleErrors,
+  }) => {
+    await openGeneral(appPage);
+    const input = appPage.locator('[data-testid="message-input"]');
+    await input.click();
+    // Typing "@" at a word boundary opens the mention autocomplete over the
+    // message list (the composer's stacking/overflow context used to clip it).
+    await input.pressSequentially('@');
+
+    const dropdown = appPage.locator('[data-testid="mention-dropdown"]');
+    await expect(dropdown).toBeVisible();
+    await expectLocatorOnTop(appPage, dropdown);
+    const isPopoverOpen = await dropdown.evaluate((el) =>
+      el.matches(':popover-open'),
+    );
+    expect(isPopoverOpen, 'mention dropdown must match :popover-open').toBe(true);
+
+    // Keyboard focus is NOT captured by the dropdown - it stays in the
+    // textarea (the dropdown is presentational).
+    const focusTestId = await appPage.evaluate(
+      () => document.activeElement?.getAttribute('data-testid') ?? null,
+    );
+    expect(focusTestId).toBe('message-input');
+
+    // Removing the trigger char closes it.
+    await input.press('Backspace');
+    await expect(dropdown).not.toBeVisible({ timeout: 5000 });
+    assertNoConsoleErrors(consoleErrors);
+  });
+
+  test('ChannelContextMenu paints ON TOP over an open backdrop-filter panel AND is :popover-open', async ({
+    appPage,
+    consoleErrors,
+  }) => {
+    // Open the artifact panel (backdrop-filter -> its own stacking context),
+    // the exact trap that used to paint the menu behind the panel.
+    await openArtifactPanel(appPage);
+    await appPage
+      .locator('[data-testid="sidebar-channel-row-general"]')
+      .click({ button: 'right' });
+
+    const menu = appPage.locator('[data-testid="channel-ctx-menu"]');
+    await expect(menu).toBeVisible();
+    await expectLocatorOnTop(appPage, menu);
+    const isPopoverOpen = await menu.evaluate((el) =>
+      el.matches(':popover-open'),
+    );
+    expect(isPopoverOpen, 'channel context menu must match :popover-open').toBe(
+      true,
+    );
+
+    await appPage.keyboard.press('Escape');
+    await expect(menu).not.toBeVisible({ timeout: 5000 });
+    assertNoConsoleErrors(consoleErrors);
+  });
+
+  test('quick-join is a native :modal dialog (inert background) and Esc-dismisses', async ({
+    appPage,
+    consoleErrors,
+  }) => {
+    await openGeneral(appPage);
+    await appPage.keyboard.press('Control+j');
+
+    const dialog = appPage.locator('[data-testid="quick-join-dialog"]');
+    await expect(dialog).toBeVisible();
+    await expectLocatorOnTop(appPage, dialog);
+    const isModal = await dialog.evaluate((el) => el.matches(':modal'));
+    expect(isModal, 'quick-join must be a native :modal <dialog>').toBe(true);
+
+    // Inert background: a sidebar channel row sits behind the modal scrim and
+    // is NOT the topmost element at its own centre (the ::backdrop is).
+    const bgRow = appPage.locator('[data-testid="sidebar-channel-row-dev-chat"]');
+    const bgInert = await bgRow.evaluate((el) => {
+      const r = el.getBoundingClientRect();
+      const top = document.elementFromPoint(r.x + r.width / 2, r.y + r.height / 2);
+      return top === null || !el.contains(top);
+    });
+    expect(bgInert, 'background row must be inert behind the modal').toBe(true);
+
+    await appPage.keyboard.press('Escape');
+    await expect(dialog).not.toBeVisible({ timeout: 5000 });
+    assertNoConsoleErrors(consoleErrors);
+  });
+});