@cat-factory/app 0.315.6 → 0.315.8

package/README.md

@@ -388,7 +388,9 @@ A phone's notch and home indicator cover whatever sits at the screen edge, and o
 - **`FULL_BLEED_TAKEOVER_CLASS`** for a takeover that fills the screen (`AgentStepDetail`, the model configuration takeover, the observability, reports, operator dashboard and Kaizen panels, the artifact lightbox). It pads by the inset alone, so a screen without one keeps the edge-to-edge layout.
 - **`WINDOWED_OVERLAY_CLASS`** for a window on a backdrop (`ResultWindowShell`). Its gutter is 1rem or the inset, whichever is larger.
 
-`scripts/check-frontend-safe-area.mjs` (CI) refuses any other `fixed` surface that spans a whole side of the viewport, in `.vue`, `.ts` and `.css`. A surface with no edge content (a scrim, a drawing layer) or one that pads its own edges (the sidebar drawer, the inspector's bottom sheet) says why with a `safe-area-ok:` comment, on the line or the one above it, or above the element's opening tag.
+Each class list belongs to ONE shell, and a surface renders inside that shell instead of binding the class itself: a takeover inside [`common/TakeoverShell.vue`](./app/components/common/TakeoverShell.vue), a window inside [`panels/ResultWindowShell.vue`](./app/components/panels/ResultWindowShell.vue). The shell binds the padding AND the modal behaviour (`useModalBehavior`: a focus trap, focus return, a body-scroll lock, and a ticket on the shared overlay stack), so focus stays inside and Escape closes only the top overlay. A takeover gates the shell with its own `v-if` inside its own `Teleport` and `Transition`, passes a `label` (the dialog's accessible name), and handles the shell's `close` event; it never adds an Escape listener of its own. A Nuxt UI menu, select, popover or modal opened inside a shell holds its own ticket on the same stack while it is open ([`utils/foreignLayers.ts`](./app/utils/foreignLayers.ts), wired by a client plugin), so Escape and Tab are its keys until it closes. No site pushes a ticket by hand. Why this is not `UModal fullscreen`, and the rest of the overlay consolidation: [`docs/initiatives/overlay-shells.md`](https://github.com/kibertoad/cat-factory/blob/main/docs/initiatives/overlay-shells.md).
+
+`scripts/check-frontend-safe-area.mjs` (CI) refuses any other `fixed` surface that spans a whole side of the viewport, in `.vue`, `.ts` and `.css`. A surface with no edge content (a scrim, a drawing layer) or one that pads its own edges (the sidebar drawer, the inspector's bottom sheet) says why with a `safe-area-ok:` comment, on the line or the one above it, or above the element's opening tag. The same guard refuses either class list named outside its owning shell, with no waiver.
 
 ### Modals open at a named width
 

package/app/components/common/ConfirmDialog.vue

@@ -2,39 +2,16 @@
 // The single, app-wide confirmation dialog. Mounted once in `pages/index.vue` and driven
 // entirely by the `useConfirm()` singleton, so any caller can `await confirm({...})` without
 // rendering its own modal. UModal already provides the focus trap, Escape-to-close and
-// backdrop, so this component adds none of that — it only resolves the pending promise and,
-// crucially, resolves `false` whenever the modal closes without an explicit choice.
-import { computed, onUnmounted, watch } from 'vue'
-import { sharedOverlayStack, type OverlayStackTicket } from '@modular-vue/core'
+// backdrop, so this component adds none of that. It only resolves the pending promise, and
+// resolves `false` whenever the modal closes without an explicit choice. Its place on
+// the shared overlay stack, which makes a takeover or window under it leave Escape to it, comes
+// from `utils/foreignLayers.ts`, as for every Nuxt UI layer.
+import { computed } from 'vue'
 import AppModal from '~/components/common/AppModal.vue'
 
 const { t } = useI18n()
 const { open, current, accept, cancel, dismissed } = useConfirm()
 
-// Register on the app's ONE overlay stack for as long as the dialog is up.
-//
-// The stack is what `useModalBehavior` (`ResultWindowShell`, the lightbox, every modular overlay)
-// asks before it handles Escape, and this dialog is a Nuxt UI modal, so without a registration it
-// is invisible to that question. A confirm opened FROM a result window then lost the race for its
-// own Escape key: the shell's capture-phase listener still believed it was topmost, so it
-// preventDefault-ed and re-entered its close request, which supersedes the confirm the user was
-// trying to cancel. Pushing a ticket makes the shell stand down while this is on top, which is
-// exactly the ordering the stack exists to state.
-let ticket: OverlayStackTicket | null = null
-function release(): void {
-  ticket?.release()
-  ticket = null
-}
-watch(
-  open,
-  (isOpen) => {
-    if (isOpen) ticket ??= sharedOverlayStack.push()
-    else release()
-  },
-  { immediate: true },
-)
-onUnmounted(release)
-
 const model = computed({
   get: () => open.value,
   set: (v: boolean) => {

package/app/components/common/TakeoverShell.vue

@@ -0,0 +1,97 @@
+<script setup lang="ts">
+// The one root of every full-bleed takeover: the step reader (`AgentStepDetail`), the model
+// configuration takeover, the observability, reports, operator dashboard and Kaizen panels, and the
+// artifact lightbox. It owns the root element and the modal BEHAVIOUR; each takeover keeps its own
+// layout, header and backdrop inside it.
+//
+// The behaviour is the upstream `useModalBehavior` (`@modular-vue/core`), the same composable
+// `ResultWindowShell` uses: a focus trap, focus return, a body-scroll lock, and a ticket on the
+// shared overlay STACK, so Escape closes only the top overlay. Before this shell, six of the seven
+// takeovers hand-rolled a window Escape listener instead. Tab then walked out to the board behind
+// them, and one Escape closed every overlay that listened, so a result window or the observability
+// panel opened over the step reader took the reader down with it.
+//
+// Why not `UModal fullscreen` (the shape `GuidedReviewModal` uses): a Reka modal makes the body
+// inert while it is up (`pointer-events: none` on `<body>`, a `focusin` trap, and a dismiss on any
+// pointer or focus outside its content). The windows opened ON TOP of a takeover
+// (`ResultWindowShell`, the lightbox, a modular overlay) are not Reka layers, so they would open
+// unclickable and lose focus to the takeover under them. The shared stack is what both sides
+// agree on: every open Nuxt UI menu, select, popover and modal holds a ticket on it
+// (`utils/foreignLayers.ts`), so one opened inside a takeover is the top overlay and keeps its own
+// Escape.
+//
+// Every takeover paints at the SAME z-index (`z-50`, as `ResultWindowShell` does) and is teleported
+// to `<body>` when it opens, so DOM order is open order: the overlay stack's top ticket is also the
+// top layer. A per-site z-index let a later-opened `z-50` takeover take focus and Escape while
+// painting under an earlier `z-[60]` one.
+//
+// The takeover is OPEN while this shell is mounted: each site gates it with its own `v-if` inside
+// its own `Teleport` and `Transition`, so a fade owned by a parent mount (`pages/index.vue` for the
+// step reader) still plays in both directions.
+import { useMounted } from '@vueuse/core'
+import { useModalBehavior } from '@modular-vue/core'
+import { FULL_BLEED_TAKEOVER_CLASS } from '~/utils/safeArea'
+
+const props = defineProps<{
+  /** The accessible name of the dialog. */
+  label: string
+  /**
+   * What the takeover shows now, for a takeover that swaps its content without closing (the step
+   * reader moving to another step). A change moves focus back to the top of the dialog.
+   */
+  contentKey?: string | number | null
+}>()
+
+const emit = defineEmits<{ close: [] }>()
+
+// The behaviour activates on MOUNT, not in setup. Most takeovers are async views, and on their first
+// open Nuxt's Suspense defers the mount, so focus moved during setup would find no element yet and
+// stay on the board.
+const mounted = useMounted()
+
+// Initial focus goes to the dialog root, not to its first control: a takeover is a whole screen of
+// content, so the reader starts at its top and the first Tab reaches the first control.
+const { dialogRef, isTop } = useModalBehavior({
+  active: mounted,
+  onClose: () => emit('close'),
+  initialFocus: () => dialogRef.value,
+  contentKey: () => props.contentKey,
+})
+
+// The trap wraps Tab only when focus is outside the dialog or on its first or last control, and the
+// root is none of those, so the first Shift+Tab from the root would leave for the board behind
+// (the browser moves to the last tabbable element before the root in DOM order). Wrap it here.
+// Hidden controls (`display: none`, such as the reader's outline below `md`) cannot take focus, so
+// they are skipped.
+const FOCUSABLE =
+  'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])'
+
+function wrapShiftTabFromRoot(event: KeyboardEvent): void {
+  const root = dialogRef.value
+  if (event.key !== 'Tab' || !event.shiftKey || !root || event.target !== root) return
+  const controls = [...root.querySelectorAll<HTMLElement>(FOCUSABLE)]
+  const last = controls.findLast((el) => el.checkVisibility())
+  if (!last) return
+  event.preventDefault()
+  last.focus()
+}
+
+// A takeover with its own keys (the lightbox's arrows and zoom) reads this, so its keys stay inert
+// while another overlay is on top of it.
+defineExpose({ isTop })
+</script>
+
+<template>
+  <div
+    ref="dialogRef"
+    tabindex="-1"
+    role="dialog"
+    aria-modal="true"
+    :aria-label="label"
+    class="z-50 focus:outline-none"
+    :class="FULL_BLEED_TAKEOVER_CLASS"
+    @keydown="wrapShiftTabFromRoot"
+  >
+    <slot />
+  </div>
+</template>

package/app/components/focus/BlockFocusView.vue

@@ -1,5 +1,7 @@
 <script setup lang="ts">
-import { onKeyStroke } from '@vueuse/core'
+import { onBeforeUnmount, onMounted } from 'vue'
+import { useEventListener } from '@vueuse/core'
+import { sharedOverlayStack, type OverlayStackTicket } from '@modular-vue/core'
 import type { Block } from '~/types/domain'
 import { blockTypeMeta, STATUS_META } from '~/utils/catalog'
 import { pipelineAllowedForManualStart } from '~/utils/pipeline'
@@ -79,9 +81,28 @@ function close() {
   ui.focus(null)
 }
 
-onKeyStroke('Escape', () => {
-  if (ui.focusBlockId) close()
+// The focus view is one more layer on the shared overlay stack: it holds a ticket while mounted and
+// takes Escape only when that ticket is the top one. A takeover, window, Nuxt UI menu or modal
+// opened from here is pushed after it, so it is the top overlay and keeps its own Escape. The
+// listener is in the CAPTURE phase and registered at setup, so it runs before the listener of any
+// overlay opened later and reads the stack as it was when the key was pressed, before that
+// overlay's close can release its ticket.
+let ticket: OverlayStackTicket | null = null
+onMounted(() => {
+  ticket = sharedOverlayStack.push()
 })
+onBeforeUnmount(() => {
+  ticket?.release()
+  ticket = null
+})
+useEventListener(
+  window,
+  'keydown',
+  (e: KeyboardEvent) => {
+    if (e.key === 'Escape' && ticket?.isTop() && ui.focusBlockId) close()
+  },
+  { capture: true },
+)
 
 function openDecisionFor(decisionId: string) {
   if (instance.value) ui.openDecision(instance.value.id, decisionId)

package/app/components/kaizen/KaizenPanel.vue

@@ -1,11 +1,10 @@
 <script setup lang="ts">
 import { computed, watch } from 'vue'
-import { onKeyStroke } from '@vueuse/core'
 import type { TableColumn } from '@nuxt/ui'
 import type { KaizenGrading } from '~/types/domain'
 import { agentKindMeta } from '~/utils/catalog'
 import EmptyState from '~/components/common/EmptyState.vue'
-import { FULL_BLEED_TAKEOVER_CLASS } from '~/utils/safeArea'
+import TakeoverShell from '~/components/common/TakeoverShell.vue'
 
 // The Kaizen screen: a full-panel overlay listing the workspace's grading history and
 // its verified-combo library. Opened via `ui.openKaizen()` from the sidebar. Read-only —
@@ -27,9 +26,6 @@ watch(
 function close() {
   ui.closeKaizen()
 }
-onKeyStroke('Escape', () => {
-  if (open.value) close()
-})
 
 function meta(kind: string) {
   return agentKindMeta(kind)
@@ -66,12 +62,11 @@ const historyColumns = computed<TableColumn<KaizenGrading>[]>(() => [
 <template>
   <Teleport to="body">
     <Transition name="kz-fade">
-      <div
+      <TakeoverShell
         v-if="open"
-        class="z-[60] flex-col bg-app-950/96 backdrop-blur-sm"
-        :class="FULL_BLEED_TAKEOVER_CLASS"
-        role="dialog"
-        aria-modal="true"
+        :label="t('kaizen.title')"
+        class="flex-col bg-app-950/96 backdrop-blur-sm"
+        @close="close"
       >
         <header class="flex items-center gap-3 border-b border-default px-6 py-4">
           <div
@@ -241,7 +236,7 @@ const historyColumns = computed<TableColumn<KaizenGrading>[]>(() => [
             </UTable>
           </section>
         </div>
-      </div>
+      </TakeoverShell>
     </Transition>
   </Teleport>
 </template>

package/app/components/media/ArtifactLightbox.vue

@@ -7,11 +7,10 @@
 // Zoom is pure CSS `transform` (GPU, no canvas), so even large PNGs stay smooth. Keyboard:
 // Esc close · ←/→ prev/next · +/- zoom · 0 reset · double-click toggle fit↔2×.
 import { computed, ref, watch } from 'vue'
-import { useModalBehavior } from '@modular-vue/core'
 import type { ArtifactBlobs } from '~/composables/useArtifactBlobs'
 import IconButton from '~/components/common/IconButton.vue'
 import Spinner from '~/components/common/Spinner.vue'
-import { FULL_BLEED_TAKEOVER_CLASS } from '~/utils/safeArea'
+import TakeoverShell from '~/components/common/TakeoverShell.vue'
 
 interface LightboxItem {
   artifactId: string
@@ -39,19 +38,15 @@ const scale = ref(1)
 const tx = ref(0)
 const ty = ref(0)
 
-// Modal behaviour via the shared overlay stack (`@modular-vue/core`, the slice-5 release):
-// focus-trap + return, body-scroll lock, and — because it pushes onto the shared stack while
-// open — it becomes the TOP overlay over an owning review window (`ResultWindowShell`), so
-// Escape closes the lightbox first and the owner's trap goes inert until it closes. This is
-// the reconciliation that replaces the old `active: open && !lightboxOpen` guard the windows
-// used to fight over Tab.
+// Modal behaviour comes from `TakeoverShell` (the shared overlay stack): focus-trap + return,
+// body-scroll lock, and, because it pushes onto the shared stack while open, it becomes the TOP
+// overlay over an owning review window (`ResultWindowShell`), so Escape closes the lightbox first
+// and the owner's trap goes inert until it closes.
 function close() {
   emit('update:open', false)
 }
-const { dialogRef, isTop } = useModalBehavior({
-  active: () => props.open,
-  onClose: close,
-})
+const shell = ref<InstanceType<typeof TakeoverShell> | null>(null)
+const isTop = computed(() => shell.value?.isTop ?? false)
 
 const current = computed(() => props.items[props.index] ?? null)
 const total = computed(() => props.items.length)
@@ -159,20 +154,17 @@ onBeforeUnmount(() => window.removeEventListener('keydown', onKey, true))
 
 <template>
   <Teleport to="body">
-    <div
+    <TakeoverShell
       v-if="open"
-      ref="dialogRef"
-      tabindex="-1"
-      class="z-[60] flex-col bg-app-950/95 backdrop-blur-sm focus:outline-none"
-      :class="FULL_BLEED_TAKEOVER_CLASS"
-      role="dialog"
-      aria-modal="true"
+      ref="shell"
+      class="flex-col bg-app-950/95 backdrop-blur-sm"
       data-testid="artifact-lightbox"
-      :aria-label="
+      :label="
         current
           ? t('media.lightbox.ariaLabel', { label: current.label })
           : t('media.lightbox.ariaLabelFallback')
       "
+      @close="close"
     >
       <!-- Toolbar -->
       <div class="flex items-center gap-3 border-b border-default/60 px-4 py-2.5">
@@ -307,6 +299,6 @@ onBeforeUnmount(() => window.removeEventListener('keydown', onKey, true))
           @click="go(1)"
         />
       </div>
-    </div>
+    </TakeoverShell>
   </Teleport>
 </template>

package/app/components/observability/StepModelActivity.vue

@@ -39,6 +39,7 @@ function openObservability() {
         color="neutral"
         variant="ghost"
         v-if="instanceId"
+        data-testid="step-view-all-calls"
         class="p-0 text-2xs text-app-info-400 hover:bg-transparent hover:text-app-info-300"
         @click="openObservability"
       >

package/app/components/panels/AgentStepDetail.vue

@@ -1,6 +1,5 @@
 <script setup lang="ts">
 import { ref, computed, watch, onMounted } from 'vue'
-import { onKeyStroke } from '@vueuse/core'
 import type { IterationCapChoice } from '~/types/execution'
 import { agentKindMeta } from '~/utils/catalog'
 import StepRestartControl from '~/components/panels/StepRestartControl.vue'
@@ -32,7 +31,7 @@ import RunDetailLoadState from '~/components/panels/RunDetailLoadState.vue'
 import SectionLabel from '~/components/common/SectionLabel.vue'
 import IconButton from '~/components/common/IconButton.vue'
 import EmptyState from '~/components/common/EmptyState.vue'
-import { FULL_BLEED_TAKEOVER_CLASS } from '~/utils/safeArea'
+import TakeoverShell from '~/components/common/TakeoverShell.vue'
 
 // Detail overlay for a single pipeline step. Opened by clicking an agent in the
 // inspector list (TaskExecution) or the focus-view pipeline (PipelineProgress) via
@@ -372,10 +371,6 @@ watch(
   },
 )
 
-onKeyStroke('Escape', () => {
-  if (open.value) close()
-})
-
 const { copy } = useCopyToClipboard()
 async function copyOutput() {
   if (step.value?.output) await copy(step.value.output)
@@ -391,14 +386,15 @@ async function copyOutput() {
   <!-- `data-agent-kind` names WHICH step this window is scoped to, as the kind rather than as
        the heading beside it: the heading is a translated display label, so it is the wrong
        thing to read for anything that needs to know which agent's step is open. -->
-  <div
+  <!-- `content-key` moves focus back to the top when the reader swaps to another step. -->
+  <TakeoverShell
     v-if="open && step && agent"
+    :label="agent.label"
+    :content-key="ctx && `${ctx.instanceId}:${ctx.stepIndex}`"
     data-testid="step-detail"
     :data-agent-kind="step?.agentKind"
-    class="z-50 bg-app-950/96 backdrop-blur-sm"
-    :class="FULL_BLEED_TAKEOVER_CLASS"
-    role="dialog"
-    aria-modal="true"
+    class="bg-app-950/96 backdrop-blur-sm"
+    @close="close"
   >
     <!-- ToC sidebar (only meaningful when there are prose headings) -->
     <aside
@@ -1085,7 +1081,7 @@ async function copyOutput() {
         </p>
       </div>
     </aside>
-  </div>
+  </TakeoverShell>
 </template>
 
 <style scoped>

package/app/components/panels/ObservabilityPanel.vue

@@ -1,6 +1,5 @@
 <script setup lang="ts">
 import { computed, nextTick, reactive, ref, watch } from 'vue'
-import { onKeyStroke } from '@vueuse/core'
 import type { TableColumn } from '@nuxt/ui'
 import { isLlmWarningFinishReason } from '@cat-factory/contracts'
 import type {
@@ -33,7 +32,7 @@ import ToolCallList from '~/components/observability/ToolCallList.vue'
 import SectionLabel from '~/components/common/SectionLabel.vue'
 import IconButton from '~/components/common/IconButton.vue'
 import EmptyState from '~/components/common/EmptyState.vue'
-import { FULL_BLEED_TAKEOVER_CLASS } from '~/utils/safeArea'
+import TakeoverShell from '~/components/common/TakeoverShell.vue'
 
 /** No run selected: the same empty, NOT-truncated trajectory the store answers with. */
 const EMPTY_TRAJECTORY: RunToolCallTrajectory = Object.freeze({
@@ -526,9 +525,6 @@ function headroomOf(m: LlmCallMetric): number | null {
 function close() {
   ui.closeObservability()
 }
-onKeyStroke('Escape', () => {
-  if (open.value) close()
-})
 function exportJson() {
   if (executionId.value) void observability.downloadExport(executionId.value)
 }
@@ -537,12 +533,12 @@ function exportJson() {
 <template>
   <Teleport to="body">
     <Transition name="obs-fade">
-      <div
+      <TakeoverShell
         v-if="open"
-        class="z-[60] flex-col bg-app-950/96 backdrop-blur-sm"
-        :class="FULL_BLEED_TAKEOVER_CLASS"
-        role="dialog"
-        aria-modal="true"
+        :label="t('observability.modelActivity')"
+        class="flex-col bg-app-950/96 backdrop-blur-sm"
+        data-testid="observability-panel"
+        @close="close"
       >
         <header class="flex flex-wrap items-center gap-3 border-b border-default px-6 py-4">
           <div
@@ -1287,7 +1283,7 @@ function exportJson() {
             </div>
           </div>
         </div>
-      </div>
+      </TakeoverShell>
     </Transition>
   </Teleport>
 </template>

package/app/components/panels/OperatorDashboardPanel.vue

@@ -1,6 +1,5 @@
 <script setup lang="ts">
 import { computed, watch } from 'vue'
-import { onKeyStroke } from '@vueuse/core'
 import type { TableColumn } from '@nuxt/ui'
 import type { PlatformObservabilityWindow } from '~/types/execution'
 import { formatMs } from '~/utils/observability'
@@ -8,7 +7,7 @@ import { FAILURE_KIND_KEYS, isAgentFailureKind } from '~/utils/failureKinds'
 import SectionLabel from '~/components/common/SectionLabel.vue'
 import IconButton from '~/components/common/IconButton.vue'
 import EmptyState from '~/components/common/EmptyState.vue'
-import { FULL_BLEED_TAKEOVER_CLASS } from '~/utils/safeArea'
+import TakeoverShell from '~/components/common/TakeoverShell.vue'
 
 // Deployment-level (platform-operator) observability dashboard: the aggregate health of the
 // active account's runs — outcome totals + success rate, a time-bucketed outcome trend, the
@@ -105,9 +104,6 @@ function refresh() {
 function close() {
   ui.closeOperatorDashboard()
 }
-onKeyStroke('Escape', () => {
-  if (open.value) close()
-})
 
 // Load (and refresh) whenever the dashboard opens.
 watch(
@@ -122,13 +118,12 @@ watch(
 <template>
   <Teleport to="body">
     <Transition name="obs-fade">
-      <div
+      <TakeoverShell
         v-if="open"
-        class="z-[60] flex-col bg-app-950/96 backdrop-blur-sm"
-        :class="FULL_BLEED_TAKEOVER_CLASS"
-        role="dialog"
-        aria-modal="true"
+        :label="t('platformObservability.title')"
+        class="flex-col bg-app-950/96 backdrop-blur-sm"
         data-testid="operator-dashboard"
+        @close="close"
       >
         <header class="flex flex-wrap items-center gap-3 border-b border-default px-6 py-4">
           <div
@@ -553,7 +548,7 @@ watch(
             </div>
           </div>
         </div>
-      </div>
+      </TakeoverShell>
     </Transition>
   </Teleport>
 </template>

package/app/components/panels/ReportsPanel.vue

@@ -1,6 +1,5 @@
 <script setup lang="ts">
 import { computed, ref, watch } from 'vue'
-import { onKeyStroke } from '@vueuse/core'
 import { lastCompleteRollupDay } from '@cat-factory/contracts'
 import type {
   ReportActivityDimension,
@@ -22,7 +21,7 @@ import ReportsSpendBreakdown from '~/components/panels/ReportsSpendBreakdown.vue
 import SectionLabel from '~/components/common/SectionLabel.vue'
 import IconButton from '~/components/common/IconButton.vue'
 import EmptyState from '~/components/common/EmptyState.vue'
-import { FULL_BLEED_TAKEOVER_CLASS } from '~/utils/safeArea'
+import TakeoverShell from '~/components/common/TakeoverShell.vue'
 
 // Reports: cross-cutting usage analytics for the active account — where the spend and the
 // work actually go. Spend per model and agent kind, spend + run activity per workspace /
@@ -179,9 +178,6 @@ function refresh() {
 function close() {
   ui.closeReports()
 }
-onKeyStroke('Escape', () => {
-  if (open.value) close()
-})
 
 // Load (and refresh) whenever the panel opens.
 watch(
@@ -196,13 +192,12 @@ watch(
 <template>
   <Teleport to="body">
     <Transition name="reports-fade">
-      <div
+      <TakeoverShell
         v-if="open"
-        class="z-[60] flex-col bg-app-950/96 backdrop-blur-sm"
-        :class="FULL_BLEED_TAKEOVER_CLASS"
-        role="dialog"
-        aria-modal="true"
+        :label="t('reports.title')"
+        class="flex-col bg-app-950/96 backdrop-blur-sm"
         data-testid="reports-panel"
+        @close="close"
       >
         <header class="flex flex-wrap items-center gap-3 border-b border-default px-6 py-4">
           <div
@@ -575,7 +570,7 @@ watch(
             </section>
           </div>
         </div>
-      </div>
+      </TakeoverShell>
     </Transition>
   </Teleport>
 </template>

package/app/components/settings/ModelConfigurationPanel.vue

@@ -11,7 +11,6 @@
 // preference. The list view shows each preset; the editor view creates/edits one with a
 // base-model picker plus a filterable per-agent override list.
 import { computed, ref, watch } from 'vue'
-import { onKeyStroke } from '@vueuse/core'
 import type { ModelFlavor } from '@cat-factory/contracts'
 import type { AgentKind } from '~/types/domain'
 import type { ModelPreset } from '~/types/model-presets'
@@ -25,7 +24,7 @@ import { showOverrideField } from '~/utils/uiMode'
 import SectionLabel from '~/components/common/SectionLabel.vue'
 import IconButton from '~/components/common/IconButton.vue'
 import EmptyState from '~/components/common/EmptyState.vue'
-import { FULL_BLEED_TAKEOVER_CLASS } from '~/utils/safeArea'
+import TakeoverShell from '~/components/common/TakeoverShell.vue'
 
 const { t } = useI18n()
 const ui = useUiStore()
@@ -119,12 +118,11 @@ watch(
   { immediate: true },
 )
 
-onKeyStroke('Escape', () => {
-  if (!open.value) return
-  // Esc backs out of the editor first, then closes the panel.
+// Esc backs out of the editor first, then closes the panel.
+function backOut() {
   if (editor.value) editor.value = null
   else open.value = false
-})
+}
 
 /** The selectable catalog models, as `{ id, label, suffix }` for a dropdown. */
 const selectableModels = computed(() => {
@@ -309,13 +307,13 @@ async function save() {
 <template>
   <Teleport to="body">
     <Transition name="reader-fade">
-      <div
+      <TakeoverShell
         v-if="open"
+        :label="t('settings.modelConfiguration.title')"
+        :content-key="editor ? 'editor' : 'list'"
+        class="flex-col bg-app-950/96 backdrop-blur-sm"
         data-testid="model-configuration-panel"
-        class="z-50 flex-col bg-app-950/96 backdrop-blur-sm"
-        :class="FULL_BLEED_TAKEOVER_CLASS"
-        role="dialog"
-        aria-modal="true"
+        @close="backOut"
       >
         <header class="flex items-center gap-3 border-b border-default px-6 py-4">
           <div class="flex h-9 w-9 shrink-0 items-center justify-center rounded-lg bg-primary/15">
@@ -444,6 +442,7 @@ async function save() {
                         variant="ghost"
                         color="error"
                         icon="i-lucide-trash-2"
+                        data-testid="model-preset-delete"
                         :disabled="p.isDefault"
                         :loading="busy"
                         :label="
@@ -518,6 +517,7 @@ async function save() {
                       variant="subtle"
                       trailing-icon="i-lucide-chevron-down"
                       class="w-full justify-between"
+                      data-testid="model-preset-base-model"
                     >
                       <span class="truncate">{{ modelLabel(editor.baseModelId) }}</span>
                     </UButton>
@@ -618,7 +618,7 @@ async function save() {
             </template>
           </div>
         </div>
-      </div>
+      </TakeoverShell>
     </Transition>
   </Teleport>
 </template>

package/app/plugins/foreign-layers.client.ts

@@ -0,0 +1,8 @@
+import { sharedOverlayStack } from '@modular-vue/core'
+import { trackForeignLayers } from '~/utils/foreignLayers'
+
+// Put every open Nuxt UI menu, select, popover and modal on the shared overlay stack, so the
+// takeover or window under it leaves Escape and Tab to it. Why: `utils/foreignLayers.ts`.
+export default defineNuxtPlugin(() => {
+  trackForeignLayers(document.body, sharedOverlayStack)
+})

package/app/utils/foreignLayers.spec.ts

@@ -0,0 +1,100 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { createOverlayStack, type OverlayStack } from '@modular-vue/core'
+import { trackForeignLayers } from '~/utils/foreignLayers'
+
+/** A Reka-shaped layer as Nuxt UI portals it: a wrapper on `<body>` around the layer element. */
+function openLayer(root: HTMLElement, role: string | null): HTMLElement {
+  const wrapper = document.createElement('div')
+  const layer = document.createElement('div')
+  layer.setAttribute('data-dismissable-layer', '')
+  layer.dataset.state = 'open'
+  if (role) layer.setAttribute('role', role)
+  wrapper.append(layer)
+  root.append(wrapper)
+  return layer
+}
+
+/** MutationObserver callbacks run as a microtask after the DOM change. */
+const settle = () => new Promise((resolve) => setTimeout(resolve, 0))
+
+describe('trackForeignLayers', () => {
+  let root: HTMLElement
+  let stack: OverlayStack
+  let stop: () => void
+
+  beforeEach(() => {
+    root = document.createElement('div')
+    document.body.append(root)
+    stack = createOverlayStack()
+    stop = trackForeignLayers(root, stack)
+  })
+
+  afterEach(() => {
+    stop()
+    root.remove()
+  })
+
+  it('puts an open menu above the overlay under it, and gives the top back when it closes', async () => {
+    const takeover = stack.push()
+    const menu = openLayer(root, 'menu')
+    await settle()
+    expect(takeover.isTop()).toBe(false)
+
+    menu.parentElement!.remove()
+    await settle()
+    expect(takeover.isTop()).toBe(true)
+    expect(stack.size).toBe(1)
+  })
+
+  it('gives the top back when a layer starts its exit animation, before it leaves the DOM', async () => {
+    const takeover = stack.push()
+    const menu = openLayer(root, 'menu')
+    await settle()
+
+    menu.dataset.state = 'closed'
+    await settle()
+    expect(takeover.isTop()).toBe(true)
+  })
+
+  it('takes a ticket for each focus-taking role, and none for a tooltip', async () => {
+    for (const role of ['menu', 'listbox', 'dialog', 'alertdialog']) openLayer(root, role)
+    openLayer(root, null)
+    await settle()
+    expect(stack.size).toBe(4)
+  })
+
+  it('keeps open order, so a menu opened over a modal is the top layer', async () => {
+    const takeover = stack.push()
+    const modal = openLayer(root, 'dialog')
+    await settle()
+    const window = stack.push()
+    expect(window.isTop()).toBe(true)
+
+    // A menu opened inside the window goes above it, and closing the modal under both changes
+    // nothing for the window.
+    const menu = openLayer(root, 'menu')
+    await settle()
+    expect(window.isTop()).toBe(false)
+    modal.parentElement!.remove()
+    menu.parentElement!.remove()
+    await settle()
+    expect(window.isTop()).toBe(true)
+    window.release()
+    expect(takeover.isTop()).toBe(true)
+  })
+
+  it('counts a layer that was already open when tracking started', () => {
+    stop()
+    openLayer(root, 'dialog')
+    stop = trackForeignLayers(root, stack)
+    expect(stack.size).toBe(1)
+  })
+
+  it('releases every ticket when tracking stops', async () => {
+    openLayer(root, 'menu')
+    openLayer(root, 'dialog')
+    await settle()
+    stop()
+    expect(stack.size).toBe(0)
+  })
+})

package/app/utils/foreignLayers.ts

@@ -0,0 +1,71 @@
+// Nuxt UI layers on the shared overlay stack.
+//
+// Two layer stacks run in this app. `useModalBehavior` (`TakeoverShell`, `ResultWindowShell`, the
+// modular overlays) keeps `sharedOverlayStack`; Reka, under every Nuxt UI menu, select, popover
+// and modal, keeps its own. Each one only knows its own layers, so a dropdown opened inside a
+// takeover lost Escape: the shell handles the key first, in the capture phase, and calls
+// `preventDefault()`, and Reka then leaves a prevented Escape alone. The takeover closed and the
+// dropdown stayed.
+//
+// The fix is ONE stack. While a Reka layer is open it holds a ticket, pushed in open order, so
+// it is the top overlay and `useModalBehavior` stands down: no Escape, no Tab trap. Reka then
+// handles its own keys. Only the stack's own API is used here (`push`, `release`); what is
+// Reka-specific is the selector.
+
+import type { OverlayStack, OverlayStackTicket } from '@modular-vue/core'
+
+/**
+ * An open Reka layer that takes focus and owns its keys. Reka marks every layer with
+ * `data-dismissable-layer`, and the role is on the same element: `menu` (dropdown menu), `listbox`
+ * (select), `dialog` (popover, modal), `alertdialog`. A tooltip is a layer too, but it has no
+ * role, so it never takes a ticket: focus stays on its trigger, and a ticket would switch off the
+ * Tab trap under it. `data-state="closed"` is a layer playing its exit animation.
+ */
+export const FOREIGN_LAYER_SELECTOR =
+  '[data-dismissable-layer]:is([role="menu"],[role="listbox"],[role="dialog"],[role="alertdialog"]):not([data-state="closed"])'
+
+const ANY_LAYER = '[data-dismissable-layer]'
+
+/**
+ * Hold one `stack` ticket for each open layer under `root`, for as long as it is open. Returns the
+ * function that stops tracking and releases every ticket.
+ *
+ * What is observed is kept narrow, because `root` is `<body>` and the board re-renders under it
+ * constantly. Reka teleports each layer to `<body>`, so an opening or a closing is a change to
+ * `root`'s DIRECT children, which a non-subtree `childList` observer sees without ever being
+ * told about a board patch. A layer's own exit animation is its `data-state` flipping to
+ * `closed`, which the attribute observer sees; it is filtered to that one attribute and then to
+ * records whose target is a layer. Only those records trigger the one `sync` query.
+ */
+export function trackForeignLayers(root: HTMLElement, stack: OverlayStack): () => void {
+  const tickets = new Map<Element, OverlayStackTicket>()
+
+  function sync(): void {
+    const open = new Set(root.querySelectorAll(FOREIGN_LAYER_SELECTOR))
+    for (const [layer, ticket] of tickets) {
+      if (open.has(layer)) continue
+      ticket.release()
+      tickets.delete(layer)
+    }
+    // Document order is open order: Reka appends each layer's portal to the end of `<body>`.
+    for (const layer of open) {
+      if (!tickets.has(layer)) tickets.set(layer, stack.push())
+    }
+  }
+
+  const portals = new MutationObserver(sync)
+  portals.observe(root, { childList: true })
+
+  const layerState = new MutationObserver((records) => {
+    if (records.some((r) => r.target instanceof Element && r.target.matches(ANY_LAYER))) sync()
+  })
+  layerState.observe(root, { subtree: true, attributes: true, attributeFilter: ['data-state'] })
+  sync()
+
+  return () => {
+    portals.disconnect()
+    layerState.disconnect()
+    for (const ticket of tickets.values()) ticket.release()
+    tickets.clear()
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/app",
-  "version": "0.315.6",
+  "version": "0.315.8",
   "description": "Reusable Nuxt layer for the Agent Architecture Board SPA (components, stores, composables, pages). Consume it from a thin deployment app via `extends: ['@cat-factory/app']` and point it at your backend with NUXT_PUBLIC_API_BASE. See deploy/frontend for an example.",
   "repository": {
     "type": "git",
@@ -18,7 +18,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@cat-factory/contracts": "0.368.0",
+    "@cat-factory/contracts": "0.369.0",
     "@modular-frontend/core": "0.6.0",
     "@modular-vue/core": "^1.5.0",
     "@modular-vue/journeys": "^1.4.0",