feat(core): add Electron runtime, services, and app composition

src/renderer/modals/session-help.ts

@@ -0,0 +1,759 @@
+import type { Keybinding } from '../../types';
+import type { ShortcutsConfig } from '../../types';
+import { SPECIAL_COMMANDS } from '../../config/definitions';
+import type { ModalStateReader, RendererContext } from '../context';
+
+type SessionHelpBindingInfo = {
+  bindingKey: 'KeyH' | 'KeyK';
+  fallbackUsed: boolean;
+  fallbackUnavailable: boolean;
+};
+
+type SessionHelpItem = {
+  shortcut: string;
+  action: string;
+  color?: string;
+};
+
+type SessionHelpSection = {
+  title: string;
+  rows: SessionHelpItem[];
+};
+type RuntimeShortcutConfig = Omit<Required<ShortcutsConfig>, 'multiCopyTimeoutMs'>;
+
+const HEX_COLOR_RE = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
+
+// Fallbacks mirror the session overlay's default subtitle/word color scheme.
+const FALLBACK_COLORS = {
+  knownWordColor: '#a6da95',
+  nPlusOneColor: '#c6a0f6',
+  jlptN1Color: '#ed8796',
+  jlptN2Color: '#f5a97f',
+  jlptN3Color: '#f9e2af',
+  jlptN4Color: '#a6e3a1',
+  jlptN5Color: '#8aadf4',
+};
+
+const KEY_NAME_MAP: Record<string, string> = {
+  Space: 'Space',
+  ArrowUp: '↑',
+  ArrowDown: '↓',
+  ArrowLeft: '←',
+  ArrowRight: '→',
+  Escape: 'Esc',
+  Tab: 'Tab',
+  Enter: 'Enter',
+  CommandOrControl: 'Cmd/Ctrl',
+  Ctrl: 'Ctrl',
+  Control: 'Ctrl',
+  Command: 'Cmd',
+  Cmd: 'Cmd',
+  Shift: 'Shift',
+  Alt: 'Alt',
+  Super: 'Meta',
+  Meta: 'Meta',
+  Backspace: 'Backspace',
+};
+
+function normalizeColor(value: unknown, fallback: string): string {
+  if (typeof value !== 'string') return fallback;
+  const next = value.trim();
+  return HEX_COLOR_RE.test(next) ? next : fallback;
+}
+
+function normalizeKeyToken(token: string): string {
+  if (KEY_NAME_MAP[token]) return KEY_NAME_MAP[token];
+  if (token.startsWith('Key')) return token.slice(3);
+  if (token.startsWith('Digit')) return token.slice(5);
+  if (token.startsWith('Numpad')) return token.slice(6);
+  return token;
+}
+
+function formatKeybinding(rawBinding: string): string {
+  const parts = rawBinding.split('+');
+  const key = parts.pop();
+  if (!key) return rawBinding;
+  const normalized = [...parts, normalizeKeyToken(key)];
+  return normalized.join(' + ');
+}
+
+const OVERLAY_SHORTCUTS: Array<{
+  key: keyof RuntimeShortcutConfig;
+  label: string;
+}> = [
+  { key: 'copySubtitle', label: 'Copy subtitle' },
+  { key: 'copySubtitleMultiple', label: 'Copy subtitle (multi)' },
+  {
+    key: 'updateLastCardFromClipboard',
+    label: 'Update last card from clipboard',
+  },
+  { key: 'triggerFieldGrouping', label: 'Trigger field grouping' },
+  { key: 'triggerSubsync', label: 'Open subtitle sync controls' },
+  { key: 'mineSentence', label: 'Mine sentence' },
+  { key: 'mineSentenceMultiple', label: 'Mine sentence (multi)' },
+  { key: 'toggleSecondarySub', label: 'Toggle secondary subtitle mode' },
+  { key: 'markAudioCard', label: 'Mark audio card' },
+  { key: 'openRuntimeOptions', label: 'Open runtime options' },
+  { key: 'openJimaku', label: 'Open jimaku' },
+  { key: 'toggleVisibleOverlayGlobal', label: 'Show/hide visible overlay' },
+  { key: 'toggleInvisibleOverlayGlobal', label: 'Show/hide invisible overlay' },
+];
+
+function buildOverlayShortcutSections(shortcuts: RuntimeShortcutConfig): SessionHelpSection[] {
+  const rows: SessionHelpItem[] = [];
+
+  for (const shortcut of OVERLAY_SHORTCUTS) {
+    const keybind = shortcuts[shortcut.key];
+    if (typeof keybind !== 'string') continue;
+    if (keybind.trim().length === 0) continue;
+
+    rows.push({
+      shortcut: formatKeybinding(keybind),
+      action: shortcut.label,
+    });
+  }
+
+  if (rows.length === 0) return [];
+  return [{ title: 'Overlay shortcuts', rows }];
+}
+
+function describeCommand(command: (string | number)[]): string {
+  const first = command[0];
+  if (typeof first !== 'string') return 'Unknown action';
+
+  if (first === 'cycle' && command[1] === 'pause') return 'Toggle playback';
+  if (first === 'seek' && typeof command[1] === 'number') {
+    return `Seek ${command[1] > 0 ? '+' : ''}${command[1]} second(s)`;
+  }
+  if (first === 'sub-seek' && typeof command[1] === 'number') {
+    return `Shift subtitle by ${command[1]} ms`;
+  }
+  if (first === SPECIAL_COMMANDS.SUBSYNC_TRIGGER) return 'Open subtitle sync controls';
+  if (first === SPECIAL_COMMANDS.RUNTIME_OPTIONS_OPEN) return 'Open runtime options';
+  if (first === SPECIAL_COMMANDS.REPLAY_SUBTITLE) return 'Replay current subtitle';
+  if (first === SPECIAL_COMMANDS.PLAY_NEXT_SUBTITLE) return 'Play next subtitle';
+  if (first.startsWith(SPECIAL_COMMANDS.RUNTIME_OPTION_CYCLE_PREFIX)) {
+    const [, rawId, rawDirection] = first.split(':');
+    return `Cycle runtime option ${rawId || 'option'} ${rawDirection === 'prev' ? 'previous' : 'next'}`;
+  }
+
+  return `MPV command: ${command.map((entry) => String(entry)).join(' ')}`;
+}
+
+function sectionForCommand(command: (string | number)[]): string {
+  const first = command[0];
+  if (typeof first !== 'string') return 'Other shortcuts';
+
+  if (
+    first === 'cycle' ||
+    first === 'seek' ||
+    first === 'sub-seek' ||
+    first === SPECIAL_COMMANDS.REPLAY_SUBTITLE ||
+    first === SPECIAL_COMMANDS.PLAY_NEXT_SUBTITLE
+  ) {
+    return 'Playback and navigation';
+  }
+
+  if (first === 'show-text' || first === 'show-progress' || first.startsWith('osd')) {
+    return 'Visual feedback';
+  }
+
+  if (first === SPECIAL_COMMANDS.SUBSYNC_TRIGGER) {
+    return 'Subtitle sync';
+  }
+
+  if (
+    first === SPECIAL_COMMANDS.RUNTIME_OPTIONS_OPEN ||
+    first.startsWith(SPECIAL_COMMANDS.RUNTIME_OPTION_CYCLE_PREFIX)
+  ) {
+    return 'Runtime settings';
+  }
+
+  if (first === 'quit') return 'System actions';
+  return 'Other shortcuts';
+}
+
+function buildBindingSections(keybindings: Keybinding[]): SessionHelpSection[] {
+  const grouped = new Map<string, SessionHelpItem[]>();
+
+  for (const binding of keybindings) {
+    const section = sectionForCommand(binding.command ?? []);
+    const row: SessionHelpItem = {
+      shortcut: formatKeybinding(binding.key),
+      action: describeCommand(binding.command ?? []),
+    };
+    grouped.set(section, [...(grouped.get(section) ?? []), row]);
+  }
+
+  const sectionOrder = [
+    'Playback and navigation',
+    'Visual feedback',
+    'Subtitle sync',
+    'Runtime settings',
+    'System actions',
+    'Other shortcuts',
+  ];
+  const sectionEntries = Array.from(grouped.entries()).sort((a, b) => {
+    const aIdx = sectionOrder.indexOf(a[0]);
+    const bIdx = sectionOrder.indexOf(b[0]);
+    if (aIdx === -1 && bIdx === -1) return a[0].localeCompare(b[0]);
+    if (aIdx === -1) return 1;
+    if (bIdx === -1) return -1;
+    return aIdx - bIdx;
+  });
+
+  return sectionEntries.map(([title, rows]) => ({ title, rows }));
+}
+
+function buildColorSection(style: {
+  knownWordColor?: unknown;
+  nPlusOneColor?: unknown;
+  jlptColors?: {
+    N1?: unknown;
+    N2?: unknown;
+    N3?: unknown;
+    N4?: unknown;
+    N5?: unknown;
+  };
+}): SessionHelpSection {
+  return {
+    title: 'Color legend',
+    rows: [
+      {
+        shortcut: 'Known words',
+        action: normalizeColor(style.knownWordColor, FALLBACK_COLORS.knownWordColor),
+        color: normalizeColor(style.knownWordColor, FALLBACK_COLORS.knownWordColor),
+      },
+      {
+        shortcut: 'N+1 words',
+        action: normalizeColor(style.nPlusOneColor, FALLBACK_COLORS.nPlusOneColor),
+        color: normalizeColor(style.nPlusOneColor, FALLBACK_COLORS.nPlusOneColor),
+      },
+      {
+        shortcut: 'JLPT N1',
+        action: normalizeColor(style.jlptColors?.N1, FALLBACK_COLORS.jlptN1Color),
+        color: normalizeColor(style.jlptColors?.N1, FALLBACK_COLORS.jlptN1Color),
+      },
+      {
+        shortcut: 'JLPT N2',
+        action: normalizeColor(style.jlptColors?.N2, FALLBACK_COLORS.jlptN2Color),
+        color: normalizeColor(style.jlptColors?.N2, FALLBACK_COLORS.jlptN2Color),
+      },
+      {
+        shortcut: 'JLPT N3',
+        action: normalizeColor(style.jlptColors?.N3, FALLBACK_COLORS.jlptN3Color),
+        color: normalizeColor(style.jlptColors?.N3, FALLBACK_COLORS.jlptN3Color),
+      },
+      {
+        shortcut: 'JLPT N4',
+        action: normalizeColor(style.jlptColors?.N4, FALLBACK_COLORS.jlptN4Color),
+        color: normalizeColor(style.jlptColors?.N4, FALLBACK_COLORS.jlptN4Color),
+      },
+      {
+        shortcut: 'JLPT N5',
+        action: normalizeColor(style.jlptColors?.N5, FALLBACK_COLORS.jlptN5Color),
+        color: normalizeColor(style.jlptColors?.N5, FALLBACK_COLORS.jlptN5Color),
+      },
+    ],
+  };
+}
+
+function filterSections(sections: SessionHelpSection[], query: string): SessionHelpSection[] {
+  const normalize = (value: string): string =>
+    value
+      .toLowerCase()
+      .replace(/commandorcontrol/gu, 'ctrl')
+      .replace(/cmd\/ctrl/gu, 'ctrl')
+      .replace(/[\s+\-_/]/gu, '');
+  const normalized = normalize(query);
+  if (!normalized) return sections;
+
+  return sections
+    .map((section) => {
+      if (normalize(section.title).includes(normalized)) {
+        return section;
+      }
+
+      const rows = section.rows.filter(
+        (row) =>
+          normalize(row.shortcut).includes(normalized) ||
+          normalize(row.action).includes(normalized),
+      );
+      if (rows.length === 0) return null;
+      return { ...section, rows };
+    })
+    .filter((section): section is SessionHelpSection => section !== null)
+    .filter((section) => section.rows.length > 0);
+}
+
+function formatBindingHint(info: SessionHelpBindingInfo): string {
+  if (info.bindingKey === 'KeyK' && info.fallbackUsed) {
+    return info.fallbackUnavailable ? 'Y-K (fallback and conflict noted)' : 'Y-K (fallback)';
+  }
+  return 'Y-H';
+}
+
+function createShortcutRow(row: SessionHelpItem, globalIndex: number): HTMLButtonElement {
+  const button = document.createElement('button');
+  button.type = 'button';
+  button.className = 'session-help-item';
+  button.tabIndex = -1;
+  button.dataset.sessionHelpIndex = String(globalIndex);
+
+  const left = document.createElement('div');
+  left.className = 'session-help-item-left';
+  const shortcut = document.createElement('span');
+  shortcut.className = 'session-help-key';
+  shortcut.textContent = row.shortcut;
+  left.appendChild(shortcut);
+
+  const right = document.createElement('div');
+  right.className = 'session-help-item-right';
+  const action = document.createElement('span');
+  action.className = 'session-help-action';
+  action.textContent = row.action;
+  right.appendChild(action);
+
+  if (row.color) {
+    const dot = document.createElement('span');
+    dot.className = 'session-help-color-dot';
+    dot.style.backgroundColor = row.color;
+    right.insertBefore(dot, action);
+  }
+
+  button.appendChild(left);
+  button.appendChild(right);
+  return button;
+}
+
+const SECTION_ICON: Record<string, string> = {
+  'MPV shortcuts': '⚙',
+  'Playback and navigation': '▶',
+  'Visual feedback': '◉',
+  'Subtitle sync': '⟲',
+  'Runtime settings': '⚙',
+  'System actions': '◆',
+  'Other shortcuts': '…',
+  'Overlay shortcuts (configurable)': '✦',
+  'Overlay shortcuts': '✦',
+  'Color legend': '◈',
+};
+
+function createSectionNode(
+  section: SessionHelpSection,
+  sectionIndex: number,
+  globalIndexMap: number[],
+): HTMLElement {
+  const sectionNode = document.createElement('section');
+  sectionNode.className = 'session-help-section';
+
+  const title = document.createElement('h3');
+  title.className = 'session-help-section-title';
+  const icon = SECTION_ICON[section.title] ?? '•';
+  title.textContent = `${icon} ${section.title}`;
+  sectionNode.appendChild(title);
+
+  const list = document.createElement('div');
+  list.className = 'session-help-item-list';
+
+  section.rows.forEach((row, rowIndex) => {
+    const globalIndex = (globalIndexMap[sectionIndex] ?? 0) + rowIndex;
+    const button = createShortcutRow(row, globalIndex);
+    list.appendChild(button);
+  });
+
+  sectionNode.appendChild(list);
+  return sectionNode;
+}
+
+export function createSessionHelpModal(
+  ctx: RendererContext,
+  options: {
+    modalStateReader: Pick<ModalStateReader, 'isAnyModalOpen'>;
+    syncSettingsModalSubtitleSuppression: () => void;
+  },
+) {
+  let priorFocus: Element | null = null;
+  let openBinding: SessionHelpBindingInfo = {
+    bindingKey: 'KeyH',
+    fallbackUsed: false,
+    fallbackUnavailable: false,
+  };
+  let helpFilterValue = '';
+  let helpSections: SessionHelpSection[] = [];
+  let focusGuard: ((event: FocusEvent) => void) | null = null;
+  let windowFocusGuard: (() => void) | null = null;
+  let modalPointerFocusGuard: ((event: Event) => void) | null = null;
+  let isRecoveringModalFocus = false;
+  let lastFocusRecoveryAt = 0;
+
+  function getItems(): HTMLButtonElement[] {
+    return Array.from(
+      ctx.dom.sessionHelpContent.querySelectorAll('.session-help-item'),
+    ) as HTMLButtonElement[];
+  }
+
+  function setSelected(index: number): void {
+    const items = getItems();
+    if (items.length === 0) return;
+
+    const wrappedIndex = index % items.length;
+    const next = wrappedIndex < 0 ? wrappedIndex + items.length : wrappedIndex;
+    ctx.state.sessionHelpSelectedIndex = next;
+
+    items.forEach((item, idx) => {
+      item.classList.toggle('active', idx === next);
+      item.tabIndex = idx === next ? 0 : -1;
+    });
+    const activeItem = items[next];
+    if (!activeItem) return;
+    activeItem.focus({ preventScroll: true });
+    activeItem.scrollIntoView({
+      block: 'nearest',
+      inline: 'nearest',
+    });
+  }
+
+  function isSessionHelpModalFocusTarget(target: EventTarget | null): boolean {
+    return target instanceof Element && ctx.dom.sessionHelpModal.contains(target);
+  }
+
+  function focusFallbackTarget(): boolean {
+    void window.electronAPI.focusMainWindow();
+    const items = getItems();
+    const firstItem = items.find((item) => item.offsetParent !== null);
+    if (firstItem) {
+      firstItem.focus({ preventScroll: true });
+      return document.activeElement === firstItem;
+    }
+
+    if (ctx.dom.sessionHelpClose instanceof HTMLElement) {
+      ctx.dom.sessionHelpClose.focus({ preventScroll: true });
+      return document.activeElement === ctx.dom.sessionHelpClose;
+    }
+
+    window.focus();
+    return false;
+  }
+
+  function enforceModalFocus(): void {
+    if (!ctx.state.sessionHelpModalOpen) return;
+    if (!isSessionHelpModalFocusTarget(document.activeElement)) {
+      if (isRecoveringModalFocus) return;
+
+      const now = Date.now();
+      if (now - lastFocusRecoveryAt < 120) return;
+
+      isRecoveringModalFocus = true;
+      lastFocusRecoveryAt = now;
+      focusFallbackTarget();
+
+      window.setTimeout(() => {
+        isRecoveringModalFocus = false;
+      }, 120);
+    }
+  }
+
+  function isFilterInputFocused(): boolean {
+    return document.activeElement === ctx.dom.sessionHelpFilter;
+  }
+
+  function focusFilterInput(): void {
+    ctx.dom.sessionHelpFilter.focus({ preventScroll: true });
+    ctx.dom.sessionHelpFilter.select();
+  }
+
+  function applyFilterAndRender(): void {
+    const sections = filterSections(helpSections, helpFilterValue);
+    const indexOffsets: number[] = [];
+    let running = 0;
+    for (const section of sections) {
+      indexOffsets.push(running);
+      running += section.rows.length;
+    }
+
+    ctx.dom.sessionHelpContent.innerHTML = '';
+    sections.forEach((section, sectionIndex) => {
+      const sectionNode = createSectionNode(section, sectionIndex, indexOffsets);
+      ctx.dom.sessionHelpContent.appendChild(sectionNode);
+    });
+
+    if (getItems().length === 0) {
+      ctx.dom.sessionHelpContent.classList.add('session-help-content-no-results');
+      ctx.dom.sessionHelpContent.textContent = helpFilterValue
+        ? 'No matching shortcuts found.'
+        : 'No active session shortcuts found.';
+      ctx.state.sessionHelpSelectedIndex = 0;
+      return;
+    }
+
+    ctx.dom.sessionHelpContent.classList.remove('session-help-content-no-results');
+
+    if (isFilterInputFocused()) return;
+
+    setSelected(0);
+  }
+
+  function requestOverlayFocus(): void {
+    void window.electronAPI.focusMainWindow();
+  }
+
+  function addPointerFocusListener(): void {
+    if (modalPointerFocusGuard) return;
+
+    modalPointerFocusGuard = () => {
+      requestOverlayFocus();
+      enforceModalFocus();
+    };
+    ctx.dom.sessionHelpModal.addEventListener('pointerdown', modalPointerFocusGuard);
+    ctx.dom.sessionHelpModal.addEventListener('click', modalPointerFocusGuard);
+  }
+
+  function removePointerFocusListener(): void {
+    if (!modalPointerFocusGuard) return;
+    ctx.dom.sessionHelpModal.removeEventListener('pointerdown', modalPointerFocusGuard);
+    ctx.dom.sessionHelpModal.removeEventListener('click', modalPointerFocusGuard);
+    modalPointerFocusGuard = null;
+  }
+
+  function startFocusRecoveryGuards(): void {
+    if (windowFocusGuard) return;
+
+    windowFocusGuard = () => {
+      requestOverlayFocus();
+      enforceModalFocus();
+    };
+    window.addEventListener('blur', windowFocusGuard);
+    window.addEventListener('focus', windowFocusGuard);
+  }
+
+  function stopFocusRecoveryGuards(): void {
+    if (!windowFocusGuard) return;
+    window.removeEventListener('blur', windowFocusGuard);
+    window.removeEventListener('focus', windowFocusGuard);
+    windowFocusGuard = null;
+  }
+
+  function showRenderError(message: string): void {
+    helpSections = [];
+    helpFilterValue = '';
+    ctx.dom.sessionHelpFilter.value = '';
+    ctx.dom.sessionHelpContent.classList.add('session-help-content-no-results');
+    ctx.dom.sessionHelpContent.textContent = message;
+    ctx.state.sessionHelpSelectedIndex = 0;
+  }
+
+  async function render(): Promise<boolean> {
+    try {
+      const [keybindings, styleConfig, shortcuts] = await Promise.all([
+        window.electronAPI.getKeybindings(),
+        window.electronAPI.getSubtitleStyle(),
+        window.electronAPI.getConfiguredShortcuts(),
+      ]);
+
+      const bindingSections = buildBindingSections(keybindings);
+      if (bindingSections.length > 0) {
+        const playback = bindingSections.find(
+          (section) => section.title === 'Playback and navigation',
+        );
+        if (playback) {
+          playback.title = 'MPV shortcuts';
+        }
+      }
+
+      const shortcutSections = buildOverlayShortcutSections(shortcuts);
+      if (shortcutSections.length > 0) {
+        shortcutSections[0]!.title = 'Overlay shortcuts (configurable)';
+      }
+      const colorSection = buildColorSection(styleConfig ?? {});
+      helpSections = [...bindingSections, ...shortcutSections, colorSection];
+      applyFilterAndRender();
+      return true;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Unable to load session help data.';
+      showRenderError(`Session help failed to load: ${message}`);
+      return false;
+    }
+  }
+
+  async function openSessionHelpModal(opening: SessionHelpBindingInfo): Promise<void> {
+    openBinding = opening;
+    priorFocus = document.activeElement;
+
+    const dataLoaded = await render();
+
+    ctx.dom.sessionHelpShortcut.textContent = `Session help opened with ${formatBindingHint(openBinding)}`;
+    if (openBinding.fallbackUnavailable) {
+      ctx.dom.sessionHelpWarning.textContent =
+        'Both Y-H and Y-K are bound; Y-K remains the fallback for this session.';
+    } else if (openBinding.fallbackUsed) {
+      ctx.dom.sessionHelpWarning.textContent = 'Y-H is already bound; using Y-K as fallback.';
+    } else {
+      ctx.dom.sessionHelpWarning.textContent = '';
+    }
+    if (dataLoaded) {
+      ctx.dom.sessionHelpStatus.textContent =
+        'Use Arrow keys, J/K/H/L, mouse, click, or / then type to filter. Esc closes.';
+    } else {
+      ctx.dom.sessionHelpStatus.textContent =
+        'Session help data is unavailable right now. Press Esc to close.';
+      ctx.dom.sessionHelpWarning.textContent =
+        'Unable to load latest shortcut settings from the runtime.';
+    }
+
+    ctx.state.sessionHelpModalOpen = true;
+    options.syncSettingsModalSubtitleSuppression();
+    ctx.dom.overlay.classList.add('interactive');
+    ctx.dom.sessionHelpModal.classList.remove('hidden');
+    ctx.dom.sessionHelpModal.setAttribute('aria-hidden', 'false');
+    ctx.dom.sessionHelpModal.setAttribute('tabindex', '-1');
+    ctx.dom.sessionHelpFilter.value = '';
+    helpFilterValue = '';
+    if (ctx.platform.shouldToggleMouseIgnore) {
+      window.electronAPI.setIgnoreMouseEvents(false);
+    }
+
+    if (focusGuard === null) {
+      focusGuard = (event: FocusEvent) => {
+        if (!ctx.state.sessionHelpModalOpen) return;
+        if (!isSessionHelpModalFocusTarget(event.target)) {
+          event.preventDefault();
+          enforceModalFocus();
+        }
+      };
+      document.addEventListener('focusin', focusGuard);
+    }
+
+    addPointerFocusListener();
+    startFocusRecoveryGuards();
+    requestOverlayFocus();
+    window.focus();
+    enforceModalFocus();
+  }
+
+  function closeSessionHelpModal(): void {
+    if (!ctx.state.sessionHelpModalOpen) return;
+
+    ctx.state.sessionHelpModalOpen = false;
+    options.syncSettingsModalSubtitleSuppression();
+    ctx.dom.sessionHelpModal.classList.add('hidden');
+    ctx.dom.sessionHelpModal.setAttribute('aria-hidden', 'true');
+    if (!ctx.state.isOverSubtitle && !options.modalStateReader.isAnyModalOpen()) {
+      ctx.dom.overlay.classList.remove('interactive');
+    }
+
+    if (focusGuard) {
+      document.removeEventListener('focusin', focusGuard);
+      focusGuard = null;
+    }
+    removePointerFocusListener();
+    stopFocusRecoveryGuards();
+
+    if (priorFocus instanceof HTMLElement && priorFocus.isConnected) {
+      priorFocus.focus({ preventScroll: true });
+      return;
+    }
+
+    if (ctx.dom.overlay instanceof HTMLElement) {
+      // Overlay remains `tabindex="-1"` to allow programmatic focus for fallback.
+      ctx.dom.overlay.focus({ preventScroll: true });
+    }
+    if (ctx.platform.shouldToggleMouseIgnore) {
+      if (!ctx.state.isOverSubtitle && !options.modalStateReader.isAnyModalOpen()) {
+        window.electronAPI.setIgnoreMouseEvents(true, { forward: true });
+      } else {
+        window.electronAPI.setIgnoreMouseEvents(false);
+      }
+    }
+    ctx.dom.sessionHelpFilter.value = '';
+    helpFilterValue = '';
+    window.focus();
+  }
+
+  function handleSessionHelpKeydown(e: KeyboardEvent): boolean {
+    if (!ctx.state.sessionHelpModalOpen) return false;
+
+    if (isFilterInputFocused()) {
+      if (e.key === 'Escape') {
+        e.preventDefault();
+        if (!helpFilterValue) {
+          closeSessionHelpModal();
+          return true;
+        }
+
+        helpFilterValue = '';
+        ctx.dom.sessionHelpFilter.value = '';
+        applyFilterAndRender();
+        focusFallbackTarget();
+        return true;
+      }
+      return false;
+    }
+
+    if (e.key === 'Escape') {
+      e.preventDefault();
+      closeSessionHelpModal();
+      return true;
+    }
+
+    const items = getItems();
+    if (items.length === 0) return true;
+
+    if (e.key === '/' && !e.ctrlKey && !e.metaKey && !e.altKey && !e.shiftKey) {
+      e.preventDefault();
+      focusFilterInput();
+      return true;
+    }
+
+    const key = e.key.toLowerCase();
+
+    if (key === 'arrowdown' || key === 'j' || key === 'l') {
+      e.preventDefault();
+      setSelected(ctx.state.sessionHelpSelectedIndex + 1);
+      return true;
+    }
+
+    if (key === 'arrowup' || key === 'k' || key === 'h') {
+      e.preventDefault();
+      setSelected(ctx.state.sessionHelpSelectedIndex - 1);
+      return true;
+    }
+
+    return true;
+  }
+
+  function wireDomEvents(): void {
+    ctx.dom.sessionHelpFilter.addEventListener('input', () => {
+      helpFilterValue = ctx.dom.sessionHelpFilter.value;
+      applyFilterAndRender();
+    });
+
+    ctx.dom.sessionHelpFilter.addEventListener('keydown', (event: KeyboardEvent) => {
+      if (event.key === 'Enter') {
+        event.preventDefault();
+        focusFallbackTarget();
+      }
+    });
+
+    ctx.dom.sessionHelpContent.addEventListener('click', (event: MouseEvent) => {
+      const target = event.target;
+      if (!(target instanceof Element)) return;
+      const row = target.closest('.session-help-item') as HTMLElement | null;
+      if (!row) return;
+      const index = Number.parseInt(row.dataset.sessionHelpIndex ?? '', 10);
+      if (!Number.isFinite(index)) return;
+      setSelected(index);
+    });
+
+    ctx.dom.sessionHelpClose.addEventListener('click', () => {
+      closeSessionHelpModal();
+    });
+  }
+
+  return {
+    closeSessionHelpModal,
+    handleSessionHelpKeydown,
+    openSessionHelpModal,
+    wireDomEvents,
+  };
+}