A Live KeyboardEvent Inspector — Settling the `event.key` vs `event.code` Question for JS Shortcuts

| ❌ Boolean flags only | | event.code + isComposing + getModifierState() | ✅ Layout-stable | ✅ Fully safe | ✅ 8+ modifiers |

Sweet Spot: Decouple physical key detection (event.code) from logical input (event.key), gate execution with isComposing/legacy keyCode === 229, and resolve full modifier states via getModifierState(). This combination guarantees layout-agnostic shortcuts, IME-safe execution, and complete modifier visibility.

Core Solution

The architecture separates DOM-bound visualization from DOM-free business logic, enabling live debugging and deterministic unit testing.

1. Physical vs Logical Key Semantics

event.key reflects the character produced by the OS layout and modifier state, while event.code maps to the physical key position. Shortcuts must use event.code for layout stability.

2. IME Composition Guard

Modern browsers expose event.isComposing, while Chromium retains the legacy keyCode === 229 marker. A dual-check ensures cross-browser safety:

function onKeyDown(e) {
  if (e.isComposing) return;            // skip during IME composition
  if (e.ctrlKey && e.code === "KeyS") {
    e.preventDefault();
    save();
  }
}

export function isImeComposition(event) {
  if (event.isComposing) return true;        // modern, per spec
  if (event.keyCode === 229) return true;    // legacy, still in Chrome
  return false;
}

3. Complete Modifier State Resolution

Boolean flags miss lock states and AltGraph. getModifierState() provides a unified interface for all modifiers:

const modifiers = ["Shift", "Control", "Alt", "Meta", "AltGraph",
                   "CapsLock", "NumLock", "ScrollLock"];
for (const name of modifiers) {
  console.log(name, event.getModifierState(name));
}

4. Key Location Differentiation

event.location distinguishes physically duplicated keys:

• 0: STANDARD
• 1: LEFT
• 2: RIGHT
• 3: NUMPAD

This enables precise remapping for accessibility or gaming, complementing event.code differences (e.g., ShiftLeft vs ShiftRight).

5. Canonical Binding String Serialization

Shortcut libraries require deterministic string representation. The generator prioritizes code for alphanumerics (layout-stable) and key for navigation/function keys, with fixed modifier ordering:

export function bindingString(event) {
  const mods = [];
  if (event.ctrlKey) mods.push("Ctrl");
  if (event.altKey) mods.push("Alt");
  if (event.shiftKey) mods.push("Shift");
  if (event.metaKey) mods.push("Meta");

  let key;
  if (event.code && /^Key[A-Z]$/.test(event.code)) {
    key = event.code;             // "KeyS"
  } else if (event.code && /^Digit\d$/.test(event.code)) {
    key = event.code;             // "Digit1"
  } else {
    key = event.key;              // "ArrowLeft" / "Escape"
  }
  return [...mods, key].filter(Boolean).join("+");
}

6. DOM-Free Testing Strategy

Core logic is extracted into pure functions accepting event-like literals, enabling node --test execution without browser APIs:

test("isImeComposition catches both modern and legacy markers", () => {
  assert.equal(isImeComposition(ev()), false);
  assert.equal(isImeComposition(ev({ isComposing: true })), true);
  // Legacy: Chrome still emits keyCode=229 during IME on keydown.
  assert.equal(isImeComposition(ev({ keyCode: 229 })), true);
  // A real Enter at IME confirm has keyCode=13 — NOT IME.
  assert.equal(isImeComposition(ev({ key: "Enter", keyCode: 13 })), false);
});

Pitfall Guide

1. Relying on keyCode or which: Deprecated numeric codes vary by OS, layout, and modifier state, creating fragile, unmaintainable magic numbers that break across environments.
2. Ignoring IME Composition Gates: Failing to check isComposing or keyCode === 229 causes shortcuts to fire during text composition, disrupting input workflows for CJK and other IME users.
3. Using Only Boolean Modifier Flags: shiftKey/ctrlKey/altKey/metaKey omit CapsLock, NumLock, ScrollLock, and AltGraph, leading to incomplete or missed shortcut detection.
4. Mixing event.key and event.code Arbitrarily: Using key for physical shortcuts breaks Dvorak/AZERTY layouts; using code for text input breaks character semantics. Each serves a distinct purpose.
5. Inconsistent Binding String Serialization: Variable modifier ordering or mixed key/code usage breaks lookup tables, preventing reliable shortcut matching and user remapping.
6. DOM-Bound Logic Without Unit Tests: Tying event handling directly to browser APIs prevents automated testing, making regression detection and CI/CD integration impossible.

Deliverables

• Blueprint: Live KeyboardEvent Inspector Architecture & Event Mapping Guide — covers DOM visualization layer, DOM-free helper module design, and cross-browser event normalization strategy.
• Checklist: Shortcut Implementation Validation Checklist — layout stability verification, IME composition gating, modifier state coverage, binding string serialization, and unit test requirements.
• Configuration Templates: DOM-free event handler boilerplate, getModifierState() resolution matrix, and canonical binding string generator ready for integration with Mousetrap/Tinykeys or custom routing systems.