@rapidmx/web-client 0.15.1 → 0.17.0

package/apps/shared/keyboard/ShortcutProvider.tsx

@@ -1,62 +1,62 @@
-///////////////////////////////////////////////////////////////////////////////
-// Copyright (C) 2026 Jean-Philippe Steinmetz
-// SPDX-License-Identifier: MPL-2.0
-///////////////////////////////////////////////////////////////////////////////
-import React, { PropsWithChildren, createContext, useContext, useEffect, useMemo, useState, useSyncExternalStore } from "react";
-import { dispatchKeyEvent } from "./dispatch.js";
-import { KeyEnvironment, SERVER_ENVIRONMENT, currentEnvironment } from "./platform.js";
-import { Registration, ShortcutRegistry } from "./registry.js";
-
-interface ShortcutContextValue {
-    registry: ShortcutRegistry;
-    env: KeyEnvironment;
-}
-
-const ShortcutContext = createContext<ShortcutContextValue | null>(null);
-
-/**
- * The web client's one keyboard layer. Mounted once, by `AppChrome` (the frame that stays mounted as the router swaps pages), so shortcuts
- * work in every view - mail, calendar, contacts, tasks, settings - and a page change only changes which handlers are registered.
- *
- * One `keydown` listener on `document` (bubbling, so what a widget handles itself and `preventDefault()`s is left alone) hands each key to
- * `dispatchKeyEvent()`. Views claim keys with `useShortcut()`. Outside a provider - an admin page, a component rendered on its own - that
- * hook does nothing.
- *
- * The platform (macOS, the desktop client) is read after mount, never during render, so the server render and hydration agree.
- */
-export function ShortcutProvider({ children }: PropsWithChildren) {
-    const registry = useMemo(() => new ShortcutRegistry(), []);
-    const [env, setEnv] = useState<KeyEnvironment>(SERVER_ENVIRONMENT);
-    useEffect(() => {
-        setEnv(currentEnvironment());
-    }, []);
-    useEffect(() => {
-        function handleKeyDown(event: KeyboardEvent) {
-            dispatchKeyEvent(registry, event, currentEnvironment(), document);
-        }
-        document.addEventListener("keydown", handleKeyDown);
-        return () => document.removeEventListener("keydown", handleKeyDown);
-    }, [registry]);
-    const value = useMemo(() => ({ registry, env }), [registry, env]);
-    return <ShortcutContext.Provider value={value}>{children}</ShortcutContext.Provider>;
-}
-
-/** The registry, or `null` outside a `ShortcutProvider`. */
-export function useShortcutRegistry(): ShortcutRegistry | null {
-    return useContext(ShortcutContext)?.registry ?? null;
-}
-
-/** The platform as the keyboard layer sees it - `SERVER_ENVIRONMENT` until the client has mounted, and outside a provider. */
-export function useKeyEnvironment(): KeyEnvironment {
-    return useContext(ShortcutContext)?.env ?? SERVER_ENVIRONMENT;
-}
-
-const NO_REGISTRATIONS: readonly Registration[] = [];
-const getNoRegistrations = () => NO_REGISTRATIONS;
-const NEVER = () => () => undefined;
-
-/** Everything registered right now, updating as views mount and unmount - what the help dialog lists. Empty outside a provider. */
-export function useRegisteredShortcuts(): readonly Registration[] {
-    const registry = useShortcutRegistry();
-    return useSyncExternalStore(registry?.subscribe ?? NEVER, registry?.getSnapshot ?? getNoRegistrations, getNoRegistrations);
-}
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React, { PropsWithChildren, createContext, useContext, useEffect, useMemo, useState, useSyncExternalStore } from "react";
+import { dispatchKeyEvent } from "./dispatch.js";
+import { KeyEnvironment, SERVER_ENVIRONMENT, currentEnvironment } from "./platform.js";
+import { Registration, ShortcutRegistry } from "./registry.js";
+
+interface ShortcutContextValue {
+    registry: ShortcutRegistry;
+    env: KeyEnvironment;
+}
+
+const ShortcutContext = createContext<ShortcutContextValue | null>(null);
+
+/**
+ * The web client's one keyboard layer. Mounted once, by `AppChrome` (the frame that stays mounted as the router swaps pages), so shortcuts
+ * work in every view - mail, calendar, contacts, tasks, settings - and a page change only changes which handlers are registered.
+ *
+ * One `keydown` listener on `document` (bubbling, so what a widget handles itself and `preventDefault()`s is left alone) hands each key to
+ * `dispatchKeyEvent()`. Views claim keys with `useShortcut()`. Outside a provider - an admin page, a component rendered on its own - that
+ * hook does nothing.
+ *
+ * The platform (macOS, the desktop client) is read after mount, never during render, so the server render and hydration agree.
+ */
+export function ShortcutProvider({ children }: PropsWithChildren) {
+    const registry = useMemo(() => new ShortcutRegistry(), []);
+    const [env, setEnv] = useState<KeyEnvironment>(SERVER_ENVIRONMENT);
+    useEffect(() => {
+        setEnv(currentEnvironment());
+    }, []);
+    useEffect(() => {
+        function handleKeyDown(event: KeyboardEvent) {
+            dispatchKeyEvent(registry, event, currentEnvironment(), document);
+        }
+        document.addEventListener("keydown", handleKeyDown);
+        return () => document.removeEventListener("keydown", handleKeyDown);
+    }, [registry]);
+    const value = useMemo(() => ({ registry, env }), [registry, env]);
+    return <ShortcutContext.Provider value={value}>{children}</ShortcutContext.Provider>;
+}
+
+/** The registry, or `null` outside a `ShortcutProvider`. */
+export function useShortcutRegistry(): ShortcutRegistry | null {
+    return useContext(ShortcutContext)?.registry ?? null;
+}
+
+/** The platform as the keyboard layer sees it - `SERVER_ENVIRONMENT` until the client has mounted, and outside a provider. */
+export function useKeyEnvironment(): KeyEnvironment {
+    return useContext(ShortcutContext)?.env ?? SERVER_ENVIRONMENT;
+}
+
+const NO_REGISTRATIONS: readonly Registration[] = [];
+const getNoRegistrations = () => NO_REGISTRATIONS;
+const NEVER = () => () => undefined;
+
+/** Everything registered right now, updating as views mount and unmount - what the help dialog lists. Empty outside a provider. */
+export function useRegisteredShortcuts(): readonly Registration[] {
+    const registry = useShortcutRegistry();
+    return useSyncExternalStore(registry?.subscribe ?? NEVER, registry?.getSnapshot ?? getNoRegistrations, getNoRegistrations);
+}

package/apps/shared/keyboard/ShortcutsDialog.tsx

@@ -1,84 +1,84 @@
-///////////////////////////////////////////////////////////////////////////////
-// Copyright (C) 2026 Jean-Philippe Steinmetz
-// SPDX-License-Identifier: MPL-2.0
-///////////////////////////////////////////////////////////////////////////////
-import React from "react";
-import Modal from "@rapidmx/react-shared/components/overlays/Modal.js";
-import { formatSpec, specsFor } from "./format.js";
-import { HELP_SCOPES, SCOPE_LABELS, SHORTCUTS, ShortcutDef, shortcutRank } from "./keymap.js";
-import { useKeyEnvironment, useRegisteredShortcuts } from "./ShortcutProvider.js";
-import { useShortcut } from "./useShortcut.js";
-
-export interface ShortcutsDialogProps {
-    open: boolean;
-    onClose: () => void;
-}
-
-function Keys({ shortcut }: { shortcut: ShortcutDef }) {
-    const env = useKeyEnvironment();
-    return (
-        <span className="flex flex-wrap justify-end gap-x-1.5 gap-y-1 shrink-0">
-            {specsFor(shortcut, env).map((spec, index) => (
-                <React.Fragment key={spec}>
-                    {index > 0 && <span className="text-xs text-text-muted self-center">or</span>}
-                    <kbd className="px-1.5 py-0.5 rounded-sm border border-border bg-surface-alt text-xs font-sans font-semibold whitespace-nowrap">
-                        {formatSpec(spec, env)}
-                    </kbd>
-                </React.Fragment>
-            ))}
-        </span>
-    );
-}
-
-/**
- * The keyboard shortcuts help dialog: what can be done from the keyboard *here*. It lists what is registered right now (see
- * `useRegisteredShortcuts()`), so it shows the global shortcuts and those of the view that is on screen - and the compose window's while one
- * is open - in groups, with the platform's own key names (Ctrl or Cmd, Alt or Option), and in the desktop client also the keys only it has.
- * A shortcut a view cannot do at the moment (no message selected) is not registered, and so not listed.
- *
- * Built on `Modal`: focus moves into the dialog and stays there, Escape closes it, and it has an accessible name. `?` and Ctrl+/ close it too.
- */
-export default function ShortcutsDialog({ open, onClose }: ShortcutsDialogProps) {
-    // Mounted only while open: the body subscribes to the registry, which every view's shortcuts change as it mounts - not something the
-    // whole app should re-render for while the dialog is closed.
-    return open ? <ShortcutsDialogBody onClose={onClose} /> : null;
-}
-
-function ShortcutsDialogBody({ onClose }: { onClose: () => void }) {
-    const registrations = useRegisteredShortcuts();
-    useShortcut(SHORTCUTS.global.help, onClose, { scope: "dialog" });
-    const groups = HELP_SCOPES.map((scope) => {
-        const listed = new Map<string, ShortcutDef>();
-        for (const registration of registrations) {
-            if (registration.scope === scope) {
-                listed.set(registration.shortcut.id, registration.shortcut);
-            }
-        }
-        return { scope, shortcuts: [...listed.values()].sort((a, b) => shortcutRank(a) - shortcutRank(b)) };
-    }).filter((group) => group.shortcuts.length > 0);
-
-    return (
-        <Modal open onClose={onClose} title="Keyboard shortcuts">
-            <div className="flex flex-col gap-5">
-                {groups.map(({ scope, shortcuts }) => (
-                    <section key={scope} aria-labelledby={`shortcuts-${scope}`}>
-                        <h3 id={`shortcuts-${scope}`} className="text-xs font-bold uppercase tracking-wide text-text-muted mb-2">
-                            {SCOPE_LABELS[scope]}
-                        </h3>
-                        <ul className="flex flex-col gap-1.5">
-                            {shortcuts.map((shortcut) => (
-                                <li key={shortcut.id} className="flex items-start justify-between gap-4 text-sm">
-                                    <span>{shortcut.label}</span>
-                                    <Keys shortcut={shortcut} />
-                                </li>
-                            ))}
-                        </ul>
-                    </section>
-                ))}
-                <p className="text-xs text-text-muted border-t border-border pt-3">
-                    Some browsers keep a few keys for themselves, so a shortcut may not work everywhere.
-                </p>
-            </div>
-        </Modal>
-    );
-}
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React from "react";
+import Modal from "@rapidmx/react-shared/components/overlays/Modal.js";
+import { formatSpec, specsFor } from "./format.js";
+import { HELP_SCOPES, SCOPE_LABELS, SHORTCUTS, ShortcutDef, shortcutRank } from "./keymap.js";
+import { useKeyEnvironment, useRegisteredShortcuts } from "./ShortcutProvider.js";
+import { useShortcut } from "./useShortcut.js";
+
+export interface ShortcutsDialogProps {
+    open: boolean;
+    onClose: () => void;
+}
+
+function Keys({ shortcut }: { shortcut: ShortcutDef }) {
+    const env = useKeyEnvironment();
+    return (
+        <span className="flex flex-wrap justify-end gap-x-1.5 gap-y-1 shrink-0">
+            {specsFor(shortcut, env).map((spec, index) => (
+                <React.Fragment key={spec}>
+                    {index > 0 && <span className="text-xs text-text-muted self-center">or</span>}
+                    <kbd className="px-1.5 py-0.5 rounded-sm border border-border bg-surface-alt text-xs font-sans font-semibold whitespace-nowrap">
+                        {formatSpec(spec, env)}
+                    </kbd>
+                </React.Fragment>
+            ))}
+        </span>
+    );
+}
+
+/**
+ * The keyboard shortcuts help dialog: what can be done from the keyboard *here*. It lists what is registered right now (see
+ * `useRegisteredShortcuts()`), so it shows the global shortcuts and those of the view that is on screen - and the compose window's while one
+ * is open - in groups, with the platform's own key names (Ctrl or Cmd, Alt or Option), and in the desktop client also the keys only it has.
+ * A shortcut a view cannot do at the moment (no message selected) is not registered, and so not listed.
+ *
+ * Built on `Modal`: focus moves into the dialog and stays there, Escape closes it, and it has an accessible name. `?` and Ctrl+/ close it too.
+ */
+export default function ShortcutsDialog({ open, onClose }: ShortcutsDialogProps) {
+    // Mounted only while open: the body subscribes to the registry, which every view's shortcuts change as it mounts - not something the
+    // whole app should re-render for while the dialog is closed.
+    return open ? <ShortcutsDialogBody onClose={onClose} /> : null;
+}
+
+function ShortcutsDialogBody({ onClose }: { onClose: () => void }) {
+    const registrations = useRegisteredShortcuts();
+    useShortcut(SHORTCUTS.global.help, onClose, { scope: "dialog" });
+    const groups = HELP_SCOPES.map((scope) => {
+        const listed = new Map<string, ShortcutDef>();
+        for (const registration of registrations) {
+            if (registration.scope === scope) {
+                listed.set(registration.shortcut.id, registration.shortcut);
+            }
+        }
+        return { scope, shortcuts: [...listed.values()].sort((a, b) => shortcutRank(a) - shortcutRank(b)) };
+    }).filter((group) => group.shortcuts.length > 0);
+
+    return (
+        <Modal open onClose={onClose} title="Keyboard shortcuts">
+            <div className="flex flex-col gap-5">
+                {groups.map(({ scope, shortcuts }) => (
+                    <section key={scope} aria-labelledby={`shortcuts-${scope}`}>
+                        <h3 id={`shortcuts-${scope}`} className="text-xs font-bold uppercase tracking-wide text-text-muted mb-2">
+                            {SCOPE_LABELS[scope]}
+                        </h3>
+                        <ul className="flex flex-col gap-1.5">
+                            {shortcuts.map((shortcut) => (
+                                <li key={shortcut.id} className="flex items-start justify-between gap-4 text-sm">
+                                    <span>{shortcut.label}</span>
+                                    <Keys shortcut={shortcut} />
+                                </li>
+                            ))}
+                        </ul>
+                    </section>
+                ))}
+                <p className="text-xs text-text-muted border-t border-border pt-3">
+                    Some browsers keep a few keys for themselves, so a shortcut may not work everywhere.
+                </p>
+            </div>
+        </Modal>
+    );
+}

package/apps/shared/keyboard/dispatch.ts

@@ -1,124 +1,124 @@
-///////////////////////////////////////////////////////////////////////////////
-// Copyright (C) 2026 Jean-Philippe Steinmetz
-// SPDX-License-Identifier: MPL-2.0
-///////////////////////////////////////////////////////////////////////////////
-import type { ShortcutScope } from "./keymap.js";
-import { matchesEvent } from "./match.js";
-import { ParsedSpec, resolveModifiers } from "./parse.js";
-import type { KeyEnvironment } from "./platform.js";
-import type { Registration, ShortcutRegistry } from "./registry.js";
-import { isActivatable, isInPopoverDialog, isInWidget, isModalOpen, isPopupOpenAt, isTextEntry, regionScopeOf } from "./targets.js";
-
-/** The keys of the four view scopes: only the mounted view has registrations, so precedence among them is moot. */
-const VIEW_SCOPES: readonly ShortcutScope[] = ["mail", "calendar", "contacts", "tasks"];
-
-/** Keys that move the caret or delete text, which a text field owns even with Ctrl or Alt held (word jumps, delete-word). */
-const EDITING_KEYS = new Set(["arrowup", "arrowdown", "arrowleft", "arrowright", "home", "end", "pageup", "pagedown", "backspace", "delete"]);
-
-/** The Copy / Cut / Paste / Select all / Undo / Redo / Find chords: never a shortcut, anywhere - they act on the page's selection, not on a view. */
-function isReservedChord(parsed: ParsedSpec, env: KeyEnvironment): boolean {
-    const modifiers = resolveModifiers(parsed, env);
-    return (modifiers.ctrl || modifiers.meta) && !modifiers.alt && !modifiers.shift && ["a", "c", "v", "x", "z", "y", "f"].includes(parsed.key);
-}
-
-/** Paste as plain text (Ctrl+Shift+V) and Redo (Ctrl+Shift+Z): text-editing chords in a field, free everywhere else (Ctrl+Shift+V is Move to). */
-function isShiftedEditingChord(parsed: ParsedSpec, env: KeyEnvironment): boolean {
-    const modifiers = resolveModifiers(parsed, env);
-    return (modifiers.ctrl || modifiers.meta) && !modifiers.alt && modifiers.shift && ["z", "v"].includes(parsed.key);
-}
-
-/**
- * Whether `parsed` may fire with the event on this target.
- *
- * A text field (input, textarea, select, contenteditable - the rich-text editor) keeps everything that types or edits: bare keys
- * (`j`, `?`, Delete), the caret keys with any modifier, and paste-as-plain-text and redo. A chord with Ctrl/Cmd/Alt works from one (that is how Ctrl+Enter sends from
- * the body), except that Option on a Mac and Ctrl+Alt (AltGr) elsewhere type characters, so those don't. Escape works from a field unless a
- * popup it owns is open (or it is in a popover dialog of its own). Outside a field, a bare key still isn't taken from a widget that reads keys itself (an open menu, a list box), and
- * Enter/Space are left to the button or link that has the focus - unless the shortcut asked for them.
- */
-function allowedOnTarget(registration: Registration, parsed: ParsedSpec, target: EventTarget | null, env: KeyEnvironment): boolean {
-    const modifiers = resolveModifiers(parsed, env);
-    const command = modifiers.ctrl || modifiers.meta || modifiers.alt;
-    if (parsed.key === "escape" && (isPopupOpenAt(target) || isInPopoverDialog(target))) {
-        return false;
-    }
-    if (isTextEntry(target)) {
-        if (parsed.key === "escape") {
-            return true;
-        }
-        if (!command || EDITING_KEYS.has(parsed.key) || isShiftedEditingChord(parsed, env)) {
-            return false;
-        }
-        return !(modifiers.alt && !modifiers.meta && (env.mac || modifiers.ctrl));
-    }
-    if (!command) {
-        if (isInWidget(target)) {
-            return false;
-        }
-        if ((parsed.key === "enter" || parsed.key === " ") && !registration.shortcut.allowOnActivatable && isActivatable(target)) {
-            return false;
-        }
-    }
-    return true;
-}
-
-/** The scopes that may act on this event, highest precedence first. */
-function activeScopes(event: KeyboardEvent, doc: Document): readonly ShortcutScope[] {
-    if (isModalOpen(doc)) {
-        return ["dialog"];
-    }
-    if (regionScopeOf(event.target) === "compose") {
-        return ["compose", "global"];
-    }
-    return [...VIEW_SCOPES, "global"];
-}
-
-/** Whether the registration applies to where the event happened (a compose window's shortcuts only inside it). */
-function inContainer(registration: Registration, event: KeyboardEvent): boolean {
-    if (!registration.container) {
-        return true;
-    }
-    return !!registration.container.current?.contains(event.target as Node | null);
-}
-
-/**
- * Handles one `keydown`: finds the registered shortcut it is, and runs its handler. Returns whether a handler ran - and only then is the
- * event's default prevented and its propagation stopped, so a key nobody claims (or a handler that declines) behaves exactly as if this layer
- * did not exist.
- *
- * Skipped outright: an event some other handler already `defaultPrevented` (a menu, the rich-text editor's own bindings), one from an IME
- * composition, a bare modifier key, and the Copy/Cut/Paste/Select all/Undo/Redo/Find chords. A held key repeats: an action that is not
- * marked `repeat` runs on the first press only, and the repeats are swallowed (so a browser doesn't reload on a held Ctrl+R) without running it.
- *
- * Which registration wins: the dialog scope alone while a modal is open; else, inside a compose window, `compose` then `global`; else
- * whichever view is mounted, then `global`. Within a scope the most recently mounted registration goes first, and one that returns
- * `false` passes the key on to the next.
- */
-export function dispatchKeyEvent(registry: ShortcutRegistry, event: KeyboardEvent, env: KeyEnvironment, doc: Document): boolean {
-    if (event.defaultPrevented || event.isComposing || event.key === "Process" || ["Control", "Shift", "Alt", "Meta"].includes(event.key)) {
-        return false;
-    }
-    const scopes = activeScopes(event, doc);
-    const candidates = registry
-        .getSnapshot()
-        .filter((registration) => scopes.includes(registration.scope) && inContainer(registration, event))
-        .sort((a, b) => scopes.indexOf(a.scope) - scopes.indexOf(b.scope) || b.order - a.order);
-    for (const registration of candidates) {
-        const specs = env.electron ? [...registration.keys, ...registration.electronKeys] : registration.keys;
-        const parsed = specs.find((spec) => matchesEvent(spec, event, env));
-        if (!parsed || isReservedChord(parsed, env) || !allowedOnTarget(registration, parsed, event.target, env)) {
-            continue;
-        }
-        if (event.repeat && !registration.shortcut.repeat) {
-            event.preventDefault();
-            event.stopPropagation();
-            return true;
-        }
-        if (registration.run(event) !== false) {
-            event.preventDefault();
-            event.stopPropagation();
-            return true;
-        }
-    }
-    return false;
-}
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import type { ShortcutScope } from "./keymap.js";
+import { matchesEvent } from "./match.js";
+import { ParsedSpec, resolveModifiers } from "./parse.js";
+import type { KeyEnvironment } from "./platform.js";
+import type { Registration, ShortcutRegistry } from "./registry.js";
+import { isActivatable, isInPopoverDialog, isInWidget, isModalOpen, isPopupOpenAt, isTextEntry, regionScopeOf } from "./targets.js";
+
+/** The keys of the four view scopes: only the mounted view has registrations, so precedence among them is moot. */
+const VIEW_SCOPES: readonly ShortcutScope[] = ["mail", "calendar", "contacts", "tasks"];
+
+/** Keys that move the caret or delete text, which a text field owns even with Ctrl or Alt held (word jumps, delete-word). */
+const EDITING_KEYS = new Set(["arrowup", "arrowdown", "arrowleft", "arrowright", "home", "end", "pageup", "pagedown", "backspace", "delete"]);
+
+/** The Copy / Cut / Paste / Select all / Undo / Redo / Find chords: never a shortcut, anywhere - they act on the page's selection, not on a view. */
+function isReservedChord(parsed: ParsedSpec, env: KeyEnvironment): boolean {
+    const modifiers = resolveModifiers(parsed, env);
+    return (modifiers.ctrl || modifiers.meta) && !modifiers.alt && !modifiers.shift && ["a", "c", "v", "x", "z", "y", "f"].includes(parsed.key);
+}
+
+/** Paste as plain text (Ctrl+Shift+V) and Redo (Ctrl+Shift+Z): text-editing chords in a field, free everywhere else (Ctrl+Shift+V is Move to). */
+function isShiftedEditingChord(parsed: ParsedSpec, env: KeyEnvironment): boolean {
+    const modifiers = resolveModifiers(parsed, env);
+    return (modifiers.ctrl || modifiers.meta) && !modifiers.alt && modifiers.shift && ["z", "v"].includes(parsed.key);
+}
+
+/**
+ * Whether `parsed` may fire with the event on this target.
+ *
+ * A text field (input, textarea, select, contenteditable - the rich-text editor) keeps everything that types or edits: bare keys
+ * (`j`, `?`, Delete), the caret keys with any modifier, and paste-as-plain-text and redo. A chord with Ctrl/Cmd/Alt works from one (that is how Ctrl+Enter sends from
+ * the body), except that Option on a Mac and Ctrl+Alt (AltGr) elsewhere type characters, so those don't. Escape works from a field unless a
+ * popup it owns is open (or it is in a popover dialog of its own). Outside a field, a bare key still isn't taken from a widget that reads keys itself (an open menu, a list box), and
+ * Enter/Space are left to the button or link that has the focus - unless the shortcut asked for them.
+ */
+function allowedOnTarget(registration: Registration, parsed: ParsedSpec, target: EventTarget | null, env: KeyEnvironment): boolean {
+    const modifiers = resolveModifiers(parsed, env);
+    const command = modifiers.ctrl || modifiers.meta || modifiers.alt;
+    if (parsed.key === "escape" && (isPopupOpenAt(target) || isInPopoverDialog(target))) {
+        return false;
+    }
+    if (isTextEntry(target)) {
+        if (parsed.key === "escape") {
+            return true;
+        }
+        if (!command || EDITING_KEYS.has(parsed.key) || isShiftedEditingChord(parsed, env)) {
+            return false;
+        }
+        return !(modifiers.alt && !modifiers.meta && (env.mac || modifiers.ctrl));
+    }
+    if (!command) {
+        if (isInWidget(target)) {
+            return false;
+        }
+        if ((parsed.key === "enter" || parsed.key === " ") && !registration.shortcut.allowOnActivatable && isActivatable(target)) {
+            return false;
+        }
+    }
+    return true;
+}
+
+/** The scopes that may act on this event, highest precedence first. */
+function activeScopes(event: KeyboardEvent, doc: Document): readonly ShortcutScope[] {
+    if (isModalOpen(doc)) {
+        return ["dialog"];
+    }
+    if (regionScopeOf(event.target) === "compose") {
+        return ["compose", "global"];
+    }
+    return [...VIEW_SCOPES, "global"];
+}
+
+/** Whether the registration applies to where the event happened (a compose window's shortcuts only inside it). */
+function inContainer(registration: Registration, event: KeyboardEvent): boolean {
+    if (!registration.container) {
+        return true;
+    }
+    return !!registration.container.current?.contains(event.target as Node | null);
+}
+
+/**
+ * Handles one `keydown`: finds the registered shortcut it is, and runs its handler. Returns whether a handler ran - and only then is the
+ * event's default prevented and its propagation stopped, so a key nobody claims (or a handler that declines) behaves exactly as if this layer
+ * did not exist.
+ *
+ * Skipped outright: an event some other handler already `defaultPrevented` (a menu, the rich-text editor's own bindings), one from an IME
+ * composition, a bare modifier key, and the Copy/Cut/Paste/Select all/Undo/Redo/Find chords. A held key repeats: an action that is not
+ * marked `repeat` runs on the first press only, and the repeats are swallowed (so a browser doesn't reload on a held Ctrl+R) without running it.
+ *
+ * Which registration wins: the dialog scope alone while a modal is open; else, inside a compose window, `compose` then `global`; else
+ * whichever view is mounted, then `global`. Within a scope the most recently mounted registration goes first, and one that returns
+ * `false` passes the key on to the next.
+ */
+export function dispatchKeyEvent(registry: ShortcutRegistry, event: KeyboardEvent, env: KeyEnvironment, doc: Document): boolean {
+    if (event.defaultPrevented || event.isComposing || event.key === "Process" || ["Control", "Shift", "Alt", "Meta"].includes(event.key)) {
+        return false;
+    }
+    const scopes = activeScopes(event, doc);
+    const candidates = registry
+        .getSnapshot()
+        .filter((registration) => scopes.includes(registration.scope) && inContainer(registration, event))
+        .sort((a, b) => scopes.indexOf(a.scope) - scopes.indexOf(b.scope) || b.order - a.order);
+    for (const registration of candidates) {
+        const specs = env.electron ? [...registration.keys, ...registration.electronKeys] : registration.keys;
+        const parsed = specs.find((spec) => matchesEvent(spec, event, env));
+        if (!parsed || isReservedChord(parsed, env) || !allowedOnTarget(registration, parsed, event.target, env)) {
+            continue;
+        }
+        if (event.repeat && !registration.shortcut.repeat) {
+            event.preventDefault();
+            event.stopPropagation();
+            return true;
+        }
+        if (registration.run(event) !== false) {
+            event.preventDefault();
+            event.stopPropagation();
+            return true;
+        }
+    }
+    return false;
+}