feat(focus): optional keydown isolation for FocusTrap

[marcstraube]

Context

Apps that put an interactive overlay (modal/dialog) over a shortcut-driven UI
need the overlay to stop background keyboard shortcuts from firing while it
is open — e.g. Delete/Ctrl+Z should act on the dialog's inputs, not on the
app behind it. Today consumers do this by hand with a keydown guard
(ev.stopPropagation()) on the overlay, alongside an otherwise standard
FocusTrap.create(...) setup.

This came up as the only genuinely reusable, generic piece of behavior when a
consumer (Rasterwerk) deduplicated two modal shells. The rest of a "modal"
(backdrop/dialog DOM, ARIA structure, body mount, app-owned CSS) is deliberately
out of scope for this library — see Non-goals. Keydown isolation, however,
is a clean focus-management primitive that fits FocusTrap.

Proposal

Add an opt-in isolateKeydown option to FocusTrapOptions
(src/focus/FocusTrap.ts). When enabled, the trap's existing keydown handling
also calls stopPropagation() so keydown events do not bubble past the trapped
container to app-level shortcut handlers. Escape/Tab handling is unchanged.

const trap = FocusTrap.create(dialog, {
  initialFocus,
  returnFocus: true,
  escapeDeactivates: true,
  onEscapeDeactivate: close,
  isolateKeydown: true, // NEW — keep app shortcuts from firing behind the trap
});

Design notes

• Opt-in, default false — must not change behavior for existing consumers.
• Reuse the trap's existing keydown listener (around FocusTrap.ts:119); do
  not add a second listener.
• stopPropagation() only — not preventDefault() (typing/Tab/Esc inside
  the dialog must still work normally).
• Keep it modern/zero-dep/a11y-correct, consistent with the module.

Acceptance criteria

• isolateKeydown?: boolean on FocusTrapOptions, documented (TSDoc).
• When true, a keydown inside the trapped container does not reach a
  listener bound higher up (e.g. document); when false/unset, it does
  (regression guard for current behavior).
• Escape deactivation, Tab cycling, initialFocus, returnFocus
  unaffected in both modes.
• Tests cover both modes; 100% branch coverage on the new option.

Non-goals

• No modal-shell wrapper / createModal, no backdrop or dialog DOM creation, no
  ARIA structure factory, no styling/CSS class hooks. The library provides the
  focus/keydown behavior; the app owns the modal DOM and its styles.

[marcstraube]

Adding two points from the duplicate #165 so nothing is lost:

Capture-phase / ordering caveat vs ShortcutManager.onEscape(). stopPropagation() alone does not stop other listeners bound on the same node (e.g. document). A bubble-phase ShortcutManager.on(...) on document is blocked by a capture-phase stopPropagation() from the trap, but a capture-phase listener on the same document (which is exactly how onEscape binds) still fires. So the "stopPropagation() only" design must address this: either use stopImmediatePropagation and/or define registration order, and cover it in tests.

Suggested extra acceptance criterion:

• Isolation reliably blocks a capture-phase document listener (e.g. ShortcutManager.onEscape) regardless of registration order.

Companion: pairs with the keyboard app-shortcut surface (#164, shipped via #168) — ignoreEditableTargets covers "don't fire while typing", this covers "don't fire behind an open modal".

[marcstraube]

Pick-up note (next session). This is the next planned issue, the companion to the just-shipped keyboard app-shortcut surface (#164 → #168): ignoreEditableTargets covers "don't fire while typing", this covers "don't fire behind an open modal".

Suggested flow (mirrors how #164 was done):

1. Read current src/focus/FocusTrap.ts first — the line refs in this issue (~119/198) and the capture-phase assumptions may have shifted; confirm where the keydown listener binds and in which phase before designing.
2. Mind the capture-ordering caveat noted above: stopPropagation() alone won't block a capture-phase listener on the same document node (how ShortcutManager.onEscape binds) — decide stopImmediatePropagation and/or registration order, and test it.
3. Present an API design for approval before implementing; then tests with 100% branch coverage on the new option; run /agy-review + /security-review on the diff.
4. PR: put Closes #156 as a clean line in the PR body (squash merge reads the PR body, not the branch commit). Keep dompurify/markdown-it deps state from chore(deps): override dompurify and markdown-it to patched versions #167 in mind (rebase on current master).

Scope stays exactly as specified here — opt-in isolateKeydown, stopPropagation not preventDefault, default false, reuse the existing listener. Non-goals unchanged.