refactor(ui): a shared modal shell with Esc, focus trap and focus return (#1923)

[dolho]

Related to #1923

Draft — deliberately partial. AC #1 (the primitive) is done and tested. AC #2 (all six adopt it) is 2 of 6. The rest are enumerated below with exact bounds. See Why partial.

Premise re-checked before starting

The issue is from 2026-07-31. Before claiming it I verified it is still true on dev:

claim	status
No shared modal shell primitive	true — components/base/ had Badge, Button, Card, Input, Select, Textarea, Toggle; no modal
Six modals lack Esc	true — zero Escape references across all six (the @keydown hits are Enter-to-submit)
No focus trap	true
views/Agents.vue:143 bulk-tag popovers	❌ stale — that file was deleted by ent#260 (Agents page folded into the Dashboard list view)

What landed

utils/focusTrap.js — every decision as a pure function over plain data, with 25 tests.
components/base/BaseModal.vue — the wiring: overlay, Esc, click-outside, focus trap, initial focus, focus return, scroll lock, role="dialog"/aria-modal.
Migrated: SystemViewEditor.vue, NavBar.vue (build-info modal).

Why the rules are a separate module

This repo's vitest runs environment: 'node' with no jsdom/happy-dom and no @vue/test-utils — I checked rather than assumed. A focus trap written inside an SFC would therefore be a rule no unit test could reach, and source-text assertions would prove only that it had been typed — the exact weak-coverage pattern the merge-train playbook names as its most common ejection.

So the rules live where they can be tested, and the SFC is the dispatcher (the ent#392 precedent this codebase already uses).

What that still leaves uncovered, stated plainly: the wiring — that the listener is attached, that focus() is actually called, that focus returns to the trigger. That needs a browser. e2e/ exists and is the right home; this PR does not add one.

Three decisions worth review

• Initial focus goes to the safe action, and destructiveness is declared (data-destructive), not guessed from label text — guessing would be wrong in every language but English. A dialog opening with Delete focused turns a reflexive Enter into data loss.
• Backdrop dismissal is identity against the overlay node, not a rectangle test. A rectangle test mis-fires for a <select> popup or date picker rendered at the document root and closes the modal under the user.
• A modified Escape does not dismiss (Ctrl/Cmd/Alt/Shift) — that is a browser or OS gesture.
• Teleport to="body" is load-bearing: several of these modals sit inside panels that establish a stacking context, where a z-50 overlay nested in one renders behind its siblings.

Why partial

Each remaining migration is an 80–230 line open/close tag surgery in a file I have not read end to end. Doing four of those blind in one pass is how a subtle markup break ships — the build catches structural errors but not a panel whose footprint quietly changed. Bounds computed by indent matching, ready for a reviewed pass:

file	overlay	close
GitConflictModal.vue	:2	:116
GitConflictModal.vue (parallel-history)	:120	:195
GitPanel.vue (initialize)	:35	:171
GitPanel.vue (PAT)	:366	:451
SchedulesPanel.vue (create/edit)	:50	:284
TasksPanel.vue (execution log)	:406	shape differs — needs reading

The migration is mechanical: replace the outer v-if overlay div with <BaseModal :model-value="…" panel-class="…" @close="…">, replace the panel div with a bare <div>, close with </BaseModal>. Both completed migrations show it.

Also outstanding from the ACs: the keyboard-reachability items (SystemViewsSidebar.vue nested <button>, InfoPanel.vue clickable <div>s, NavBar.vue user dropdown) — untouched here.

Verification

check	result
New rule tests	25 passed
Full frontend suite	2870 / 2870
npm run build	clean
Raw-color ratchet	green — zero raw palette classes in BaseModal
Loading-gate ratchet	green
portalLoadingTreatment (scanline allowlist)	green
Step 10 hygiene	staged by path; gitlinks clean; no markers

🤖 Generated with Claude Code

https://claude.ai/code/session_01Q19uRCksdn4DiRAJ55rfpZ