fix(web): ignore keyboard events with a missing key

Chrome reports TypeError when shortcut listeners call .length or
.toLowerCase on KeyboardEvent.key that some browsers/extensions leave
unset. Treat a missing key as empty so those listeners no-op.

Co-authored-by: Tyler Dane <tyler-dane@users.noreply.github.com>

Author: cursoragent

packages/web/src/__tests__/utils/keyboard.test.util.ts

@@ -26,3 +26,18 @@ export function pressKey(
     }),
   );
 }
+
+/** Some browsers fire KeyboardEvents with `key` unset. */
+export function dispatchMissingKey(
+  type: "keydown" | "keyup",
+  target: Element | Node | Window | Document = document,
+) {
+  const event = new KeyboardEvent(type, {
+    bubbles: true,
+    cancelable: true,
+    composed: true,
+  });
+  Object.defineProperty(event, "key", { get: () => undefined });
+  target.dispatchEvent(event);
+  return event;
+}

packages/web/src/components/OnboardingChecklist/useChecklistDetection.ts

@@ -5,6 +5,7 @@ import { isEditableKeyboardTarget } from "@web/common/utils/form/form.util";
 import { checklistActions } from "@web/components/OnboardingChecklist/checklist.store";
 import { useDraftStore } from "@web/events/stores/draft.store";
 import { useEdgeFocusStore } from "@web/grid/shortcuts/edge-focus.store";
+import { keyboardKey } from "@web/shortcuts/is-bare-letter-key";
 import { useEventJumpStore } from "@web/shortcuts/shift-hint/event-jump.store";
 
 const ARROW_KEYS = new Set(["ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight"]);
@@ -42,7 +43,7 @@ export function useChecklistDetection(enabled: boolean) {
       if (
         (event.metaKey || event.ctrlKey) &&
         !event.shiftKey &&
-        event.key.toLowerCase() === "z"
+        keyboardKey(event).toLowerCase() === "z"
       ) {
         checklistActions.completeItem("undo");
         return;

packages/web/src/components/ShortcutShowcase/ShortcutShowcase.tsx

@@ -48,7 +48,10 @@ import {
 } from "@web/components/ShortcutShowcase/showcase.store";
 import { ShortcutKeys } from "@web/components/Shortcuts/ShortcutKeys";
 import { useAppLockReason } from "@web/shortcuts/app-lock";
-import { isBareLetterKey } from "@web/shortcuts/is-bare-letter-key";
+import {
+  isBareLetterKey,
+  keyboardKey,
+} from "@web/shortcuts/is-bare-letter-key";
 import { KEYMAP } from "@web/shortcuts/keymap";
 import { ShortcutTipParts } from "@web/shortcuts/tips/ShortcutTipParts";
 import { ARM_WINDOW_MS } from "@web/shortcuts/useEditSequenceShortcut";
@@ -272,7 +275,7 @@ const ShowcaseTakeover: FC = () => {
       ) {
         event.preventDefault();
         const hints = Object.values(practiceRef.current.jumpChips);
-        const typed = jumpBufferRef.current + event.key.toLowerCase();
+        const typed = jumpBufferRef.current + keyboardKey(event).toLowerCase();
         if (hints.includes(typed)) {
           jumpBufferRef.current = "";
           apply((state) => jumpToChipHint(state, typed));
@@ -306,7 +309,10 @@ const ShowcaseTakeover: FC = () => {
         return;
       }
 
-      if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === "z") {
+      if (
+        (event.metaKey || event.ctrlKey) &&
+        keyboardKey(event).toLowerCase() === "z"
+      ) {
         event.preventDefault();
         const before = practiceRef.current;
         if (event.shiftKey) {

packages/web/src/components/WelcomeModal/WelcomeModal.tsx

@@ -13,6 +13,7 @@ import { useAuthModal } from "@web/components/AuthModal/hooks/useAuthModal";
 import { OverlayPanel } from "@web/components/OverlayPanel/OverlayPanel";
 import { shortcutShowcaseActions } from "@web/components/ShortcutShowcase/showcase.store";
 import { ShortcutHint } from "@web/components/Shortcuts/ShortcutHint";
+import { keyboardKey } from "@web/shortcuts/is-bare-letter-key";
 import { PixelPirate } from "./PixelPirate";
 import { WelcomeGuideBody } from "./WelcomeGuideBody";
 import { hasSeenWelcome, markWelcomeSeen } from "./welcome.modal.util";
@@ -66,7 +67,7 @@ export function WelcomeModal() {
 
   const handleShortcutKey = (e: React.KeyboardEvent) => {
     if (e.metaKey || e.ctrlKey || e.altKey) return;
-    const key = e.key.toLowerCase();
+    const key = keyboardKey(e).toLowerCase();
     if (key === "u") {
       e.preventDefault();
       handOffToAuth("sign_up");

packages/web/src/shortcuts/is-bare-letter-key.test.ts

@@ -0,0 +1,51 @@
+import {
+  isBareLetterKey,
+  keyboardKey,
+  normalizedKeyboardKey,
+} from "@web/shortcuts/is-bare-letter-key";
+import { describe, expect, it } from "bun:test";
+
+const eventWithKey = (key: unknown): KeyboardEvent => {
+  const event = new KeyboardEvent("keydown", {
+    bubbles: true,
+    cancelable: true,
+  });
+  Object.defineProperty(event, "key", { get: () => key });
+  return event;
+};
+
+describe("keyboardKey", () => {
+  it("returns the key when it is a string", () => {
+    expect(keyboardKey(eventWithKey("e"))).toBe("e");
+  });
+
+  it("returns empty string when key is missing", () => {
+    expect(keyboardKey(eventWithKey(undefined))).toBe("");
+    expect(keyboardKey(eventWithKey(null))).toBe("");
+  });
+});
+
+describe("normalizedKeyboardKey", () => {
+  it("lowercases single-character keys", () => {
+    expect(normalizedKeyboardKey(eventWithKey("E"))).toBe("e");
+  });
+
+  it("leaves named keys unchanged", () => {
+    expect(normalizedKeyboardKey(eventWithKey("Escape"))).toBe("Escape");
+  });
+
+  it("does not throw when key is missing", () => {
+    expect(normalizedKeyboardKey(eventWithKey(undefined))).toBe("");
+  });
+});
+
+describe("isBareLetterKey", () => {
+  it("matches an unmodified letter", () => {
+    expect(isBareLetterKey(eventWithKey("s"), "s")).toBe(true);
+    expect(isBareLetterKey(eventWithKey("S"), "s")).toBe(true);
+  });
+
+  it("returns false instead of throwing when key is missing", () => {
+    expect(isBareLetterKey(eventWithKey(undefined), "s")).toBe(false);
+  });
+});

packages/web/src/shortcuts/is-bare-letter-key.ts

@@ -1,8 +1,29 @@
+/**
+ * Some browsers, extensions, and IME/autofill paths fire KeyboardEvents with
+ * `key` unset. Calling `.length` / `.toLowerCase()` on that value is a
+ * TypeError and is what production error tracking reports as
+ * "Cannot read properties of undefined (reading 'length'|'toLowerCase')".
+ */
+export const keyboardKey = (event: Pick<KeyboardEvent, "key">): string =>
+  typeof event.key === "string" ? event.key : "";
+
+/** Lowercase a single-character key; leave named keys (Escape, ArrowUp) as-is. */
+export const normalizedKeyboardKey = (
+  event: Pick<KeyboardEvent, "key">,
+): string => {
+  const key = keyboardKey(event);
+  return key.length === 1 ? key.toLowerCase() : key;
+};
+
 /** True for an unmodified single-letter key matching `letter` (case-insensitive). */
-export const isBareLetterKey = (event: KeyboardEvent, letter: string) =>
-  event.key.length === 1 &&
-  event.key.toLowerCase() === letter &&
-  !event.metaKey &&
-  !event.ctrlKey &&
-  !event.altKey &&
-  !event.shiftKey;
+export const isBareLetterKey = (event: KeyboardEvent, letter: string) => {
+  const key = keyboardKey(event);
+  return (
+    key.length === 1 &&
+    key.toLowerCase() === letter &&
+    !event.metaKey &&
+    !event.ctrlKey &&
+    !event.altKey &&
+    !event.shiftKey
+  );
+};

packages/web/src/shortcuts/keyboard-only/useKeyboardOnlyMode.test.tsx

@@ -1,4 +1,5 @@
 import { act, renderHook } from "@testing-library/react";
+import { dispatchMissingKey } from "@web/__tests__/utils/keyboard.test.util";
 import { clearAppLockReasons, setAppLockReason } from "@web/shortcuts/app-lock";
 import {
   initialKeyboardOnlyState,
@@ -198,4 +199,15 @@ describe("useKeyboardOnlyMode", () => {
     expect(useKeyboardOnlyStore.getState().isActive).toBe(true);
     expect(useEventJumpStore.getState().isActive).toBe(false);
   });
+
+  it("ignores KeyboardEvents with no key instead of throwing", () => {
+    renderHook(() => useKeyboardOnlyMode());
+
+    expect(() => {
+      dispatchMissingKey("keydown");
+      dispatchMissingKey("keyup");
+    }).not.toThrow();
+
+    expect(useKeyboardOnlyStore.getState().isActive).toBe(false);
+  });
 });

packages/web/src/shortcuts/shift-hint/useShiftHoldEventHints.test.tsx

@@ -1,5 +1,6 @@
 import { act, cleanup, renderHook } from "@testing-library/react";
 import { EventIdSchema } from "@core/types/domain-primitives";
+import { dispatchMissingKey } from "@web/__tests__/utils/keyboard.test.util";
 import { type GridEvent } from "@web/common/types/web.event.types";
 import { clearAppLockReasons, setAppLockReason } from "@web/shortcuts/app-lock";
 import {
@@ -262,4 +263,16 @@ describe("useShiftHoldEventHints", () => {
     expect(useEventJumpStore.getState().isActive).toBe(false);
     expect(result.current.hints).toEqual([]);
   });
+
+  it("ignores KeyboardEvents with no key instead of throwing", () => {
+    const { result } = mountHints();
+
+    expect(() => {
+      dispatchMissingKey("keydown");
+      dispatchMissingKey("keyup");
+    }).not.toThrow();
+
+    expect(useEventJumpStore.getState().isActive).toBe(false);
+    expect(result.current.hints).toEqual([]);
+  });
 });

packages/web/src/shortcuts/shift-hint/useShiftHoldEventHints.ts

@@ -5,7 +5,11 @@ import { type GridEvent } from "@web/common/types/web.event.types";
 import { isEditableKeyboardTarget } from "@web/common/utils/form/form.util";
 import { isAppLocked } from "@web/shortcuts/app-lock";
 import { isHigherEscapeOwner } from "@web/shortcuts/escape-ownership";
-import { isBareLetterKey } from "@web/shortcuts/is-bare-letter-key";
+import {
+  isBareLetterKey,
+  keyboardKey,
+  normalizedKeyboardKey,
+} from "@web/shortcuts/is-bare-letter-key";
 import { KEYMAP } from "@web/shortcuts/keymap";
 import {
   assignDayJumpKeys,
@@ -280,7 +284,7 @@ export function useShiftHoldEventHints({
       }
 
       // Arrows keep mode on so letter-then-arrows can move focus.
-      if (event.key.startsWith("Arrow")) {
+      if (keyboardKey(event).startsWith("Arrow")) {
         clearAmbiguousCommitTimer();
         stripDigitBuffer();
         return;
@@ -290,7 +294,7 @@ export function useShiftHoldEventHints({
         return;
       }
 
-      const key = event.key.length === 1 ? event.key.toLowerCase() : event.key;
+      const key = normalizedKeyboardKey(event);
       if (key.length !== 1) return;
 
       // Swallow j/k and other unmatched printable shortcuts while jump is on.
@@ -359,7 +363,7 @@ export function useShiftHoldEventHints({
     };
 
     const onKeyUp = (event: KeyboardEvent) => {
-      const key = event.key.length === 1 ? event.key.toLowerCase() : event.key;
+      const key = normalizedKeyboardKey(event);
       if (!suppressKeyUpRef.current.has(key)) return;
       suppressKeyUpRef.current.delete(key);
       event.preventDefault();

packages/web/src/shortcuts/tips/useShortcutTipTrigger.ts

@@ -4,6 +4,7 @@ import {
   selectIsEventFormOpen,
   useDraftStore,
 } from "@web/events/stores/draft.store";
+import { keyboardKey } from "@web/shortcuts/is-bare-letter-key";
 import {
   selectActiveShortcutTipId,
   shortcutTipsActions,
@@ -45,13 +46,13 @@ export function useShortcutTipTrigger() {
         activeTipId === "edit-sequence" &&
         !event.shiftKey &&
         !event.altKey &&
-        event.key.toLowerCase() === "e"
+        keyboardKey(event).toLowerCase() === "e"
       ) {
         shortcutTipsActions.actedOn("edit-sequence");
       } else if (
         activeTipId === "nudge" &&
         event.shiftKey &&
-        event.key.startsWith("Arrow")
+        keyboardKey(event).startsWith("Arrow")
       ) {
         shortcutTipsActions.actedOn("nudge");
       } else if (activeTipId === "target-event" && event.key === "Shift") {