@cat-factory/app 0.311.0 → 0.311.2

package/README.md

@@ -321,6 +321,15 @@ That is the whole mechanism, and it is why there is no rule here about WHICH ste
 
 The default `radius` lives on the `Cat Factory` document in `app/utils/theme/builtins.ts`. It equals `THEME_DEFAULTS.radius` and so writes no CSS, which is the point: changing the number there is the whole edit.
 
+### Full-screen overlays bind their root class
+
+A phone's notch and home indicator cover whatever sits at the screen edge, and on a screen without them nothing looks wrong. So a full-screen overlay never spells `fixed inset-0` itself. Its root binds one of the two class lists in [`utils/safeArea.ts`](./app/utils/safeArea.ts), which carry the positioning, the `100dvh` cap and the safe-area padding, and the site adds only its stacking, direction and backdrop:
+
+- **`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.
+
 ### A control is its Nuxt UI component
 
 Every CONTROL in the SPA is the Nuxt UI component for it, never the raw HTML element. A raw `<button>` beside a `UButton` is the same control rendered twice, and only one of the two follows the theme, the focus ring, the disabled state and the size scale; the SPA carried 152 of them, 24 raw `<input>`, five hand-built tables and six hand-rolled `<details>`, each with its own border, background and hover recipe.
@@ -1485,7 +1494,7 @@ the same list, plus the install-free frontend guards.
 ```bash
 # From the repo root:
 pnpm install
-pnpm dev:frontend                                    # Nuxt dev server via deploy/frontend; set NUXT_PUBLIC_API_BASE to a running Worker
+pnpm dev:frontend                                    # Nuxt dev server via deploy/frontend; set NUXT_PUBLIC_API_BASE to a running backend
 pnpm exec turbo run typecheck --filter=@cat-factory/app   # typecheck goes through Turbo
 pnpm lint                                            # oxlint + oxfmt over the whole tree
 
@@ -1495,6 +1504,10 @@ pnpm i18n:check                                      # catalog is well-formed
 pnpm i18n:parity                                     # locales are in parity
 ```
 
+To see the SPA with data while you work on it, run it against the e2e backend: it needs only a
+Postgres, fakes the LLM, the agent runner and GitHub, and can seed boards. See
+[Running the SPA against the e2e backend](https://github.com/kibertoad/cat-factory/blob/main/backend/internal/e2e/README.md#running-the-spa-against-the-e2e-backend-ui-development).
+
 > Building/deploying the static site is covered in the deployment docs: see the
 > [top-level README → Deployment](https://github.com/kibertoad/cat-factory/blob/main/README.md#deployment) and
 > [`deploy/frontend/README.md`](https://github.com/kibertoad/cat-factory/blob/main/deploy/frontend/README.md).

package/app/app.config.ts

@@ -23,25 +23,6 @@ export default defineAppConfig({
     badge: {
       defaultVariants: { color: 'primary', variant: 'solid', size: 'md' },
     },
-    // Give every overlay the same layered surface the agent-run-details reader uses: the deep
-    // `app-950` surface (below `bg-default`) so the `bg-default` panels/cards inside pop, with
-    // `border-default` chrome. All tokens are theme role tokens (`app-950` is the hand-defined
-    // flipping token for the deep shade), so overlays track dark/light. Applies to all
-    // UModal/USlideover instances so they stay consistent without per-instance `:ui` overrides.
-    modal: {
-      slots: {
-        content: 'bg-app-950 ring-default divide-default',
-        header: 'border-b border-default',
-        title: 'text-highlighted',
-      },
-    },
-    slideover: {
-      slots: {
-        content: 'bg-app-950 ring-default divide-default',
-        header: 'border-b border-default',
-        title: 'text-highlighted',
-      },
-    },
     // The toaster's scroll region is the ONE `[data-slot='viewport']` the app's own
     // CSS may target: Nuxt UI reuses that attribute for the item list of every menu
     // component too. This marker class is what `main.css` hangs the safe-area offset

package/app/assets/css/main.css

@@ -84,6 +84,16 @@ body,
   height: 100%;
 }
 
+/* No pull-to-refresh and no scroll chaining out of the app. The SPA is a full-screen canvas whose
+ * body never scrolls, so a vertical overscroll that reaches the viewport (from a modal's header,
+ * the end of a list, a gutter) has nothing to scroll and on a phone would reload the app instead,
+ * dropping whatever was open. Setting it on the root once covers every overlay, and inner scrollers
+ * still chain to the scroller around them. */
+html,
+body {
+  overscroll-behavior-y: none;
+}
+
 body {
   margin: 0;
   overflow: hidden;

package/app/components/board/DependencyConnectOverlay.vue

@@ -7,6 +7,7 @@ const { connecting } = useDependencyConnect()
 </script>
 
 <template>
+  <!-- safe-area-ok: a pointer-events-none drawing layer with no controls or text -->
   <svg
     v-if="connecting"
     class="pointer-events-none fixed inset-0 z-50 h-full w-full overflow-visible"

package/app/components/bootstrap/AdoptionReviewModal.vue

@@ -309,7 +309,7 @@ watch(open, (isOpen) => {
               </div>
 
               <div class="grid gap-2 text-xs sm:grid-cols-2">
-                <div class="rounded-sm bg-default/60 p-2">
+                <div class="rounded-sm bg-elevated/60 p-2">
                   <p class="mb-1 font-semibold text-toned">
                     {{ t('bootstrap.adoption.side.monorepo') }}
                   </p>
@@ -317,7 +317,7 @@ watch(open, (isOpen) => {
                     {{ decision.monorepoPractice ?? t('bootstrap.adoption.side.nothing') }}
                   </p>
                 </div>
-                <div class="rounded-sm bg-default/60 p-2">
+                <div class="rounded-sm bg-elevated/60 p-2">
                   <p class="mb-1 font-semibold text-toned">
                     {{ t('bootstrap.adoption.side.template') }}
                   </p>

package/app/components/common/AsyncViewError.vue

@@ -9,9 +9,10 @@ function reload() {
 </script>
 
 <template>
+  <!-- safe-area-ok: a scrim with one card centred on it, so no content reaches an edge -->
   <div
     data-testid="async-view-error"
-    class="fixed inset-0 z-50 grid place-items-center bg-app-950/80 p-6 backdrop-blur-sm"
+    class="fixed inset-0 z-50 grid place-items-center bg-elevated/75 p-6 backdrop-blur-sm"
     role="alert"
   >
     <div class="max-w-sm rounded-2xl border border-muted bg-default p-5 shadow-2xl">

package/app/components/documents/DocumentTemplatesModal.vue

@@ -136,7 +136,7 @@ async function unlink(doc: SourceDocument) {
             </p>
             <div
               v-if="template"
-              class="mt-2 flex items-center justify-between gap-2 rounded-md bg-default/70 px-3 py-2"
+              class="mt-2 flex items-center justify-between gap-2 rounded-md bg-elevated/70 px-3 py-2"
             >
               <DocumentOriginLink
                 :url="template.url"
@@ -173,7 +173,7 @@ async function unlink(doc: SourceDocument) {
               <div
                 v-for="doc in exemplars"
                 :key="`${doc.source}:${doc.externalId}`"
-                class="flex items-center justify-between gap-2 rounded-md bg-default/70 px-3 py-2"
+                class="flex items-center justify-between gap-2 rounded-md bg-elevated/70 px-3 py-2"
               >
                 <DocumentOriginLink
                   :url="doc.url"

package/app/components/kaizen/KaizenPanel.vue

@@ -4,6 +4,7 @@ import { onKeyStroke } from '@vueuse/core'
 import type { TableColumn } from '@nuxt/ui'
 import type { KaizenGrading } from '~/types/domain'
 import { agentKindMeta } from '~/utils/catalog'
+import { FULL_BLEED_TAKEOVER_CLASS } from '~/utils/safeArea'
 
 // 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 —
@@ -66,7 +67,8 @@ const historyColumns = computed<TableColumn<KaizenGrading>[]>(() => [
     <Transition name="kz-fade">
       <div
         v-if="open"
-        class="fixed inset-0 z-[60] flex flex-col bg-app-950/96 backdrop-blur-sm"
+        class="z-[60] flex-col bg-app-950/96 backdrop-blur-sm"
+        :class="FULL_BLEED_TAKEOVER_CLASS"
         role="dialog"
         aria-modal="true"
       >

package/app/components/layout/SideBar.vue

@@ -154,9 +154,10 @@ watch(
     enter-from-class="opacity-0"
     leave-to-class="opacity-0"
   >
+    <!-- safe-area-ok: a scrim with no content; the drawer below pads its own edges -->
     <div
       v-if="ui.mobileNavOpen"
-      class="fixed inset-0 z-30 bg-app-950/60 backdrop-blur-sm lg:hidden"
+      class="fixed inset-0 z-30 bg-elevated/75 backdrop-blur-sm lg:hidden"
       data-testid="sidebar-backdrop"
       role="button"
       tabindex="-1"
@@ -165,6 +166,8 @@ watch(
     />
   </Transition>
 
+  <!-- safe-area-ok: below lg, an edge drawer that pads the top, bottom and inline-start insets
+       itself. The start side is physical left in LTR and right in RTL, hence the `rtl:` override. -->
   <aside
     ref="aside"
     data-testid="sidebar"
@@ -173,7 +176,7 @@ watch(
     :aria-modal="drawerOpen ? 'true' : undefined"
     :aria-label="isCompact ? t('nav.menu') : undefined"
     :inert="isCompact && !ui.mobileNavOpen"
-    class="fixed inset-y-0 start-0 z-40 flex h-full w-64 shrink-0 flex-col gap-4 overflow-y-auto border-e border-default bg-default/95 px-3 pt-3 pb-[calc(0.75rem+env(safe-area-inset-bottom))] backdrop-blur transition-transform duration-200 focus:outline-none lg:static lg:z-auto lg:translate-x-0 lg:bg-default/80"
+    class="fixed inset-y-0 start-0 z-40 flex h-full w-64 shrink-0 flex-col gap-4 overflow-y-auto border-e border-default bg-default/95 px-3 pt-3 pb-[calc(0.75rem+env(safe-area-inset-bottom))] max-lg:ps-[calc(0.75rem+env(safe-area-inset-left))] max-lg:pt-[calc(0.75rem+env(safe-area-inset-top))] max-lg:rtl:ps-[calc(0.75rem+env(safe-area-inset-right))] backdrop-blur transition-transform duration-200 focus:outline-none lg:static lg:z-auto lg:translate-x-0 lg:bg-default/80"
     :class="[
       ui.mobileNavOpen
         ? 'translate-x-0'

package/app/components/media/ArtifactLightbox.vue

@@ -10,6 +10,7 @@ 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 { FULL_BLEED_TAKEOVER_CLASS } from '~/utils/safeArea'
 
 interface LightboxItem {
   artifactId: string
@@ -161,7 +162,8 @@ onBeforeUnmount(() => window.removeEventListener('keydown', onKey, true))
       v-if="open"
       ref="dialogRef"
       tabindex="-1"
-      class="fixed inset-0 z-[60] flex flex-col bg-app-950/95 backdrop-blur-sm focus:outline-none"
+      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"
       data-testid="artifact-lightbox"
@@ -170,7 +172,6 @@ onBeforeUnmount(() => window.removeEventListener('keydown', onKey, true))
           ? t('media.lightbox.ariaLabel', { label: current.label })
           : t('media.lightbox.ariaLabelFallback')
       "
-      @click.self="close"
     >
       <!-- Toolbar -->
       <div class="flex items-center gap-3 border-b border-default/60 px-4 py-2.5">

package/app/components/panels/AgentStepDetail.vue

@@ -31,6 +31,7 @@ import InputGateNotice from '~/components/inputGate/InputGateNotice.vue'
 import RunDetailLoadState from '~/components/panels/RunDetailLoadState.vue'
 import SectionLabel from '~/components/common/SectionLabel.vue'
 import IconButton from '~/components/common/IconButton.vue'
+import { FULL_BLEED_TAKEOVER_CLASS } from '~/utils/safeArea'
 
 // Detail overlay for a single pipeline step. Opened by clicking an agent in the
 // inspector list (TaskExecution) or the focus-view pipeline (PipelineProgress) via
@@ -393,7 +394,8 @@ async function copyOutput() {
     v-if="open && step && agent"
     data-testid="step-detail"
     :data-agent-kind="step?.agentKind"
-    class="fixed inset-0 z-50 flex max-h-[100dvh] bg-app-950/96 backdrop-blur-sm"
+    class="z-50 bg-app-950/96 backdrop-blur-sm"
+    :class="FULL_BLEED_TAKEOVER_CLASS"
     role="dialog"
     aria-modal="true"
   >
@@ -959,7 +961,7 @@ async function copyOutput() {
       <!-- edit-then-approve actions -->
       <div
         v-if="editing"
-        class="space-y-2 border-t border-default px-4 pt-3 pb-[calc(0.75rem+env(safe-area-inset-bottom))]"
+        class="space-y-2 border-t border-default px-4 pt-3 pb-[calc(0.75rem+env(safe-area-inset-bottom))] lg:pb-3"
       >
         <UButton
           size="sm"
@@ -984,7 +986,7 @@ async function copyOutput() {
 
       <div
         v-else
-        class="space-y-2 border-t border-default px-4 pt-3 pb-[calc(0.75rem+env(safe-area-inset-bottom))]"
+        class="space-y-2 border-t border-default px-4 pt-3 pb-[calc(0.75rem+env(safe-area-inset-bottom))] lg:pb-3"
       >
         <UButton
           data-testid="step-approve"

package/app/components/panels/InspectorPanel.vue

@@ -339,6 +339,7 @@ const showOriginalDescription = ref(false)
        NOT `data-block-id`: that attribute is the board's card selector, which the canvas drivers
        measure geometry through (`utils/blockRects.ts`), and a panel answering to it would offer
        the arrows a rect that is not on the canvas at all. -->
+  <!-- safe-area-ok: a bottom sheet below lg; its scroller pads the bottom and side insets -->
   <div
     v-if="block && statusMeta && typeMeta"
     data-testid="inspector-panel"
@@ -352,7 +353,7 @@ const showOriginalDescription = ref(false)
          On compact viewports the panel is a bottom sheet capped to the visible
          height (dvh excludes mobile browser chrome). -->
     <div
-      class="max-h-[80dvh] space-y-4 overflow-y-auto overscroll-contain px-4 pt-4 pb-[calc(1rem+env(safe-area-inset-bottom))] lg:max-h-[calc(100vh-7rem)]"
+      class="max-h-[80dvh] space-y-4 overflow-y-auto overscroll-contain pt-4 pr-[max(1rem,env(safe-area-inset-right))] pb-[calc(1rem+env(safe-area-inset-bottom))] pl-[max(1rem,env(safe-area-inset-left))] lg:max-h-[calc(100vh-7rem)]"
     >
       <!-- header -->
       <div class="flex items-start justify-between gap-2">

package/app/components/panels/ObservabilityPanel.vue

@@ -32,6 +32,7 @@ import RunFailureSummary from '~/components/observability/RunFailureSummary.vue'
 import ToolCallList from '~/components/observability/ToolCallList.vue'
 import SectionLabel from '~/components/common/SectionLabel.vue'
 import IconButton from '~/components/common/IconButton.vue'
+import { FULL_BLEED_TAKEOVER_CLASS } from '~/utils/safeArea'
 
 /** No run selected: the same empty, NOT-truncated trajectory the store answers with. */
 const EMPTY_TRAJECTORY: RunToolCallTrajectory = Object.freeze({
@@ -537,17 +538,18 @@ function exportJson() {
     <Transition name="obs-fade">
       <div
         v-if="open"
-        class="fixed inset-0 z-[60] flex flex-col bg-app-950/96 backdrop-blur-sm"
+        class="z-[60] flex-col bg-app-950/96 backdrop-blur-sm"
+        :class="FULL_BLEED_TAKEOVER_CLASS"
         role="dialog"
         aria-modal="true"
       >
-        <header class="flex items-center gap-3 border-b border-default px-6 py-4">
+        <header class="flex flex-wrap 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-app-info-500/15"
           >
             <UIcon name="i-lucide-activity" class="h-5 w-5 text-app-info-400" />
           </div>
-          <div class="min-w-0">
+          <div class="min-w-0 flex-1">
             <h1 class="truncate text-base font-semibold text-highlighted">
               {{ t('observability.modelActivity') }}
             </h1>
@@ -555,7 +557,11 @@ function exportJson() {
               {{ block.title }} · {{ runSubtitle }}
             </p>
           </div>
-          <div class="ms-auto flex items-center gap-1.5">
+          <!-- Below lg the controls take their own row, so the close button stays on screen.
+               The row scrolls sideways when the tabs are wider than the phone. -->
+          <div
+            class="order-last flex w-full min-w-0 items-center gap-1.5 overflow-x-auto lg:order-none lg:w-auto"
+          >
             <!-- Four VIEWS of the same run, which is what tabs mean. The trajectory is loaded
                  lazily the first time the tools view is opened, so the change is watched rather
                  than bound straight to `view`. -->
@@ -580,15 +586,16 @@ function exportJson() {
             >
               {{ t('observability.exportJson') }}
             </UButton>
-            <IconButton
-              icon="i-lucide-x"
-              color="neutral"
-              variant="ghost"
-              size="sm"
-              :label="t('observability.closeEsc')"
-              @click="close"
-            />
           </div>
+          <IconButton
+            class="lg:-ms-1.5"
+            icon="i-lucide-x"
+            color="neutral"
+            variant="ghost"
+            size="sm"
+            :label="t('observability.closeEsc')"
+            @click="close"
+          />
         </header>
 
         <div class="flex-1 overflow-auto px-6 py-6">

package/app/components/panels/OperatorDashboardPanel.vue

@@ -7,6 +7,7 @@ import { formatMs } from '~/utils/observability'
 import { FAILURE_KIND_KEYS, isAgentFailureKind } from '~/utils/failureKinds'
 import SectionLabel from '~/components/common/SectionLabel.vue'
 import IconButton from '~/components/common/IconButton.vue'
+import { FULL_BLEED_TAKEOVER_CLASS } from '~/utils/safeArea'
 
 // 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
@@ -122,24 +123,29 @@ watch(
     <Transition name="obs-fade">
       <div
         v-if="open"
-        class="fixed inset-0 z-[60] flex flex-col bg-app-950/96 backdrop-blur-sm"
+        class="z-[60] flex-col bg-app-950/96 backdrop-blur-sm"
+        :class="FULL_BLEED_TAKEOVER_CLASS"
         role="dialog"
         aria-modal="true"
         data-testid="operator-dashboard"
       >
-        <header class="flex items-center gap-3 border-b border-default px-6 py-4">
+        <header class="flex flex-wrap 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-app-info-500/15"
           >
             <UIcon name="i-lucide-gauge" class="h-5 w-5 text-app-info-400" />
           </div>
-          <div class="min-w-0">
+          <div class="min-w-0 flex-1">
             <h1 class="truncate text-base font-semibold text-highlighted">
               {{ t('platformObservability.title') }}
             </h1>
             <p v-if="accountName" class="truncate text-xs text-dimmed">{{ accountName }}</p>
           </div>
-          <div class="ms-auto flex items-center gap-1.5">
+          <!-- Below lg the window tabs take their own row, so refresh and close stay on screen.
+               The row scrolls sideways when the tabs are wider than the phone. -->
+          <div
+            class="order-last flex w-full min-w-0 items-center gap-1.5 overflow-x-auto lg:order-none lg:w-auto"
+          >
             <UTabs
               :model-value="platform.window"
               :items="WINDOWS"
@@ -154,31 +160,33 @@ watch(
                 <span :data-testid="`operator-window-${item.value}`">{{ item.label }}</span>
               </template>
             </UTabs>
-            <IconButton
-              color="neutral"
-              variant="ghost"
-              icon="i-lucide-refresh-cw"
-              :label="t('platformObservability.refresh')"
-              :ui="{
-                base: 'rounded-lg border border-default p-1.5 text-muted transition hover:text-default',
-                leadingIcon: loading ? 'h-4 w-4 animate-spin' : 'h-4 w-4',
-              }"
-              data-testid="operator-refresh"
-              @click="refresh"
-            />
-            <IconButton
-              color="neutral"
-              variant="ghost"
-              icon="i-lucide-x"
-              :label="t('platformObservability.close')"
-              :ui="{
-                base: 'rounded-lg border border-default p-1.5 text-muted transition hover:text-default',
-                leadingIcon: 'h-4 w-4',
-              }"
-              data-testid="operator-close"
-              @click="close"
-            />
           </div>
+          <IconButton
+            class="lg:-ms-1.5"
+            color="neutral"
+            variant="ghost"
+            icon="i-lucide-refresh-cw"
+            :label="t('platformObservability.refresh')"
+            :ui="{
+              base: 'rounded-lg border border-default p-1.5 text-muted transition hover:text-default',
+              leadingIcon: loading ? 'h-4 w-4 animate-spin' : 'h-4 w-4',
+            }"
+            data-testid="operator-refresh"
+            @click="refresh"
+          />
+          <IconButton
+            class="-ms-1.5"
+            color="neutral"
+            variant="ghost"
+            icon="i-lucide-x"
+            :label="t('platformObservability.close')"
+            :ui="{
+              base: 'rounded-lg border border-default p-1.5 text-muted transition hover:text-default',
+              leadingIcon: 'h-4 w-4',
+            }"
+            data-testid="operator-close"
+            @click="close"
+          />
         </header>
 
         <div class="flex-1 overflow-y-auto px-6 py-5">

package/app/components/panels/ReportsPanel.vue

@@ -21,6 +21,7 @@ import {
 import ReportsSpendBreakdown from '~/components/panels/ReportsSpendBreakdown.vue'
 import SectionLabel from '~/components/common/SectionLabel.vue'
 import IconButton from '~/components/common/IconButton.vue'
+import { FULL_BLEED_TAKEOVER_CLASS } from '~/utils/safeArea'
 
 // 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 /
@@ -196,7 +197,8 @@ watch(
     <Transition name="reports-fade">
       <div
         v-if="open"
-        class="fixed inset-0 z-[60] flex flex-col bg-app-950/96 backdrop-blur-sm"
+        class="z-[60] flex-col bg-app-950/96 backdrop-blur-sm"
+        :class="FULL_BLEED_TAKEOVER_CLASS"
         role="dialog"
         aria-modal="true"
         data-testid="reports-panel"

package/app/components/panels/ResultWindowShell.logic.ts

@@ -11,10 +11,10 @@ export type ResultWindowWidth = '3xl' | '4xl' | '5xl' | 'full'
 
 /**
  * The bucket → cap mapping. `full` is deliberately `max-w-none` rather than a bigger number:
- * the panel's `w-full` then spans the backdrop, which the variant insets by one gutter (`m-4`
- * stretched, `p-4` centered), so the window fills the screen and still reads as a window rather
- * than a repaint of the app. A `Record` over the union, so a new bucket fails to compile until
- * it is mapped.
+ * the panel's `w-full` then spans the backdrop, which insets it by one gutter
+ * (`WINDOWED_OVERLAY_CLASS`, `utils/safeArea.ts`), so the window fills the screen and still reads
+ * as a window rather than a repaint of the app. A `Record` over the union, so a new bucket fails to
+ * compile until it is mapped.
  */
 export const RESULT_WINDOW_WIDTH_CLASS: Record<ResultWindowWidth, string> = {
   '3xl': 'max-w-3xl',

package/app/components/panels/ResultWindowShell.vue

@@ -40,6 +40,7 @@ import {
   RESULT_WINDOW_WIDTH_CLASS,
   type ResultWindowWidth,
 } from '~/components/panels/ResultWindowShell.logic'
+import { WINDOWED_OVERLAY_CLASS } from '~/utils/safeArea'
 import SectionLabel from '~/components/common/SectionLabel.vue'
 
 /** A pipeline step reference — passed by step-result windows to surface the shared
@@ -255,13 +256,17 @@ const chipClass = computed(() =>
 )
 
 const backdropClass = computed(() => [
-  'fixed inset-0 z-50 flex max-h-[100dvh] justify-center bg-app-950/70 backdrop-blur-sm',
-  props.variant === 'centered' ? 'items-center p-4' : 'items-stretch',
+  WINDOWED_OVERLAY_CLASS,
+  'z-50 justify-center bg-elevated/75 backdrop-blur-sm',
+  props.variant === 'centered' ? 'items-center' : 'items-stretch',
 ])
+// The centered cap is the smaller of 90dvh and the backdrop's padded box: with a large inset (a
+// Dynamic Island in standalone mode) the gutter alone can exceed 10% of the height, and a window
+// sized to 90dvh would then push its top edge back under the status bar.
 const panelClass = computed(() => [
   'flex w-full flex-col overflow-hidden rounded-2xl border border-default bg-default shadow-2xl',
   RESULT_WINDOW_WIDTH_CLASS[props.width],
-  props.variant === 'centered' ? 'max-h-[90dvh]' : 'm-4',
+  props.variant === 'centered' && 'max-h-[min(90dvh,100%)]',
 ])
 </script>
 

package/app/components/settings/ModelConfigurationPanel.vue

@@ -24,6 +24,7 @@ import ProviderPreferenceEditor from '~/components/settings/ProviderPreferenceEd
 import { showOverrideField } from '~/utils/uiMode'
 import SectionLabel from '~/components/common/SectionLabel.vue'
 import IconButton from '~/components/common/IconButton.vue'
+import { FULL_BLEED_TAKEOVER_CLASS } from '~/utils/safeArea'
 
 const { t } = useI18n()
 const ui = useUiStore()
@@ -300,7 +301,8 @@ async function save() {
     <Transition name="reader-fade">
       <div
         v-if="open"
-        class="fixed inset-0 z-50 flex max-h-[100dvh] flex-col bg-app-950/96 backdrop-blur-sm"
+        class="z-50 flex-col bg-app-950/96 backdrop-blur-sm"
+        :class="FULL_BLEED_TAKEOVER_CLASS"
         role="dialog"
         aria-modal="true"
       >

package/app/utils/safeArea.spec.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest'
+import { FULL_BLEED_TAKEOVER_CLASS, WINDOWED_OVERLAY_CLASS } from '~/utils/safeArea'
+
+// A missing or misspelled side is silent on every screen without a notch, so the exact spellings
+// are pinned here. That every full-screen surface binds one of these is
+// `scripts/check-frontend-safe-area.mjs`'s job.
+describe('full-screen overlay root classes', () => {
+  it('gives a takeover only the inset, so it stays edge to edge without one', () => {
+    expect(FULL_BLEED_TAKEOVER_CLASS.split(' ')).toEqual([
+      'fixed',
+      'inset-0',
+      'flex',
+      'max-h-[100dvh]',
+      'pt-[env(safe-area-inset-top)]',
+      'pr-[env(safe-area-inset-right)]',
+      'pb-[env(safe-area-inset-bottom)]',
+      'pl-[env(safe-area-inset-left)]',
+    ])
+  })
+
+  it('gives a windowed backdrop 1rem or the inset, whichever is larger, on every side', () => {
+    expect(WINDOWED_OVERLAY_CLASS.split(' ')).toEqual([
+      'fixed',
+      'inset-0',
+      'flex',
+      'max-h-[100dvh]',
+      'pt-[max(1rem,env(safe-area-inset-top))]',
+      'pr-[max(1rem,env(safe-area-inset-right))]',
+      'pb-[max(1rem,env(safe-area-inset-bottom))]',
+      'pl-[max(1rem,env(safe-area-inset-left))]',
+    ])
+  })
+})

package/app/utils/safeArea.ts

@@ -0,0 +1,41 @@
+/**
+ * The root classes of the full-screen overlays, with the safe-area padding built in, so a phone's
+ * notch, rounded corners and home indicator never cover a header, a close button or an edge. The
+ * insets are physical, so the sides are too. They resolve to 0 unless the viewport meta carries
+ * `viewport-fit=cover` (`nuxt.config.ts`).
+ *
+ * A full-screen overlay binds one of these two constants on its root instead of spelling
+ * `fixed inset-0` itself, so it cannot drop the padding or the `100dvh` cap. The site adds only its
+ * stacking, direction and backdrop. `scripts/check-frontend-safe-area.mjs` refuses a full-screen
+ * `fixed` surface written anywhere else.
+ *
+ * Every class is spelled out literally: Tailwind generates only the class names it finds in the
+ * source text, so a name assembled at runtime would compile to nothing.
+ */
+
+const FULL_SCREEN = 'fixed inset-0 flex max-h-[100dvh]'
+
+/**
+ * A full-bleed takeover (`AgentStepDetail`, the model configuration takeover, the panels and the
+ * lightbox): only the inset, so on a screen without one the layout is exactly the edge-to-edge one
+ * it was designed as.
+ */
+export const FULL_BLEED_TAKEOVER_CLASS = [
+  FULL_SCREEN,
+  'pt-[env(safe-area-inset-top)]',
+  'pr-[env(safe-area-inset-right)]',
+  'pb-[env(safe-area-inset-bottom)]',
+  'pl-[env(safe-area-inset-left)]',
+].join(' ')
+
+/**
+ * A windowed overlay's backdrop (`ResultWindowShell`): 1rem, or the inset on that side when it is
+ * larger, so the window always floats clear of the screen edge and of the notch.
+ */
+export const WINDOWED_OVERLAY_CLASS = [
+  FULL_SCREEN,
+  'pt-[max(1rem,env(safe-area-inset-top))]',
+  'pr-[max(1rem,env(safe-area-inset-right))]',
+  'pb-[max(1rem,env(safe-area-inset-bottom))]',
+  'pl-[max(1rem,env(safe-area-inset-left))]',
+].join(' ')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/app",
-  "version": "0.311.0",
+  "version": "0.311.2",
   "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",
@@ -47,14 +47,14 @@
     "@toad-contracts/testing": "1.0.0",
     "happy-dom": "^20.14.5",
     "msw": "^2.15.0",
-    "nuxt": "^4.6.0",
+    "nuxt": "^4.6.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.11",
     "vue-i18n-extract": "^2.0.7",
     "vue-tsc": "^3.3.12"
   },
   "peerDependencies": {
-    "nuxt": "^4.5.2"
+    "nuxt": "^4.5.2 <4.6.0 || ^4.6.1"
   },
   "scripts": {
     "postinstall": "nuxt prepare",