hotkey-router 0.1.0 → 0.2.0

package/README.md

@@ -14,8 +14,8 @@ It is a predictable, plugin-first routing layer for keyboard shortcuts.
 * 🎯 Deterministic winner selection (priority + recency)
 * 🛑 Input-safe by default
 * 🧪 Testable via `trigger()`
-* 📦 4.9 kB minified
-* 🗜  2.2 kB minified + gzipped
+* 🚨 Optional opt-in browser/OS conflict warnings (tree-shakable)
+* 📦 ~3 kB minified + gzipped (core); ~7.5 kB with conflict warnings
 * 🚫 Zero dependencies
 
 ---
@@ -93,6 +93,99 @@ hotkeys.registerPlugin('docs', {
 })
 ```
 
+## Conflict warnings (v0.2.0+)
+
+Some combos are reserved by the browser chrome (find bar, devtools, bookmarks) or the OS (Spotlight, window management) — they never reach page-world JavaScript, no matter how early you listen or whether you call `preventDefault`. Hotkey Router ships an **opt-in** reservation table that emits a soft warning at bind time, so the silent failure becomes a noisy one.
+
+The feature is opt-in by design: the core router stays ~3 KB gzipped, and the ~5 KB reservation data is tree-shaken out entirely unless you import it.
+
+### Two ways to opt in
+
+**One-line ergonomic** — use the `auto` entry. Same default export as `hotkey-router`, with warnings pre-installed:
+
+```js
+import hotkeys from 'hotkey-router/auto'
+
+hotkeys.bind('meta+shift+f', toggleFullscreen)
+// Firefox on macOS:
+// [hotkey-router] "meta+shift+f" reserved by firefox on macOS:
+//   "Toggle fullscreen" [hard] — will not fire.
+```
+
+**Explicit install** — keep using the tiny core, install warnings yourself:
+
+```js
+import hotkeys from 'hotkey-router'
+import { installReservationWarnings } from 'hotkey-router/reservations'
+
+installReservationWarnings(hotkeys)
+hotkeys.bind('meta+shift+f', toggleFullscreen)
+```
+
+`installReservationWarnings()` returns an `uninstall` function if you ever need to detach. The warning is **never fatal** — the binding is still registered, in case you're running in a browser/platform where the conflict doesn't apply.
+
+### Severity → log level
+
+| Severity          | Log level | Meaning                                                 |
+| ----------------- | --------- | ------------------------------------------------------- |
+| `hard`            | `warn`    | Browser intercepts before page world; combo won't fire. |
+| `os`              | `warn`    | OS intercepts globally.                                 |
+| `menu-activation` | `warn`    | Alt+letter activates the browser menu bar (Win/Linux).  |
+| `find-bar-only`   | `info`    | Reserved only when the find bar is focused.             |
+| `compose`         | `info`    | macOS Option+letter types a special char in inputs.     |
+| `system-text`     | `info`    | Mac Ctrl+letter cursor controls inside text inputs.     |
+| `devtools-open`   | `info`    | Only relevant when DevTools is already open.            |
+
+### Per-bind opt-out
+
+```js
+hotkeys.bind('meta+shift+f', toggleFullscreen, null, { warnOnReserved: false })
+```
+
+To turn warnings off globally, just don't install them (use the bare `hotkey-router` entry instead of `hotkey-router/auto`).
+
+### Force a platform/browser (tests, SSR previews)
+
+```js
+installReservationWarnings(hotkeys, { platform: 'mac', browser: 'firefox' })
+```
+
+Accepted platforms: `'mac' | 'windows' | 'linux'`. Browsers: `'firefox' | 'chrome' | 'safari' | 'edge'`.
+
+### Caveats
+
+- Reservations reflect **default** keybindings. Users with custom shortcuts (Edge 95+ rebinds, Firefox add-ons, OS-level customization) may not match.
+- KDE/XFCE desktop reservations beyond GNOME are not yet catalogued — Linux coverage is conservative.
+- Layout-specific differences (Dvorak, AZERTY) change which physical key produces `event.key === 'f'`. For layout-stable bindings against the physical key, use `code:KeyX` syntax — the reservation lookup normalizes both.
+
+### Programmatic lookup
+
+If you want to query the table yourself (e.g. building a cheatsheet that flags conflicts):
+
+```js
+import { lookupReservation } from 'hotkey-router/reservations'
+
+const r = lookupReservation(
+  { meta: true, shift: true, key: 'f' },
+  { platform: 'mac', browser: 'firefox' }
+)
+// → { source: 'browser', action: 'Toggle fullscreen', severity: 'hard', ... }
+```
+
+### Extension hook (`onBind`)
+
+Reservation warnings are built on a public `onBind` hook — useful for telemetry, dev panels, or any cross-cutting concern that needs to observe every binding:
+
+```js
+const off = hotkeys.onBind(({ combo, raw, options, plugin, id }) => {
+  // combo: parsed combo { ctrl, meta, alt, shift, key, code, bareModifier }
+  // raw:   original hotkey string
+})
+// off() unsubscribes.
+```
+
+---
+
 ## Bare-modifier bindings (v0.1.0+)
 
 Some UX patterns are driven by a bare modifier rather than a chord — e.g. "hold Alt to enter select mode, release Alt to exit."
@@ -164,11 +257,12 @@ off()
   preventDefault?: boolean
   stopPropagation?: boolean
   stopImmediatePropagation?: boolean
-  repeat?: boolean        // default false on keydown
+  repeat?: boolean         // default false on keydown
   once?: boolean
   when?: (event) => boolean
   allowIn?: (event) => boolean
-  priority?: number       // default 0
+  priority?: number        // default 0
+  warnOnReserved?: boolean // only read when conflict warnings are installed
 }
 ```
 
@@ -240,6 +334,21 @@ Remove all hotkeys associated with a plugin.
 
 ---
 
+## `onBind(hook)`
+
+Subscribe to bind events. The hook receives `{ combo, raw, options, plugin, id }` after every successful `bind()`. Returns an unsubscribe function. Used internally by `installReservationWarnings`; exposed for telemetry, dev panels, and custom validation.
+
+```js
+const off = hotkeys.onBind(({ raw }) => {
+  console.debug('bound:', raw)
+})
+// off() unsubscribes.
+```
+
+Hook errors are caught and logged via `console.error` — a buggy hook can't break the bind.
+
+---
+
 ## `pause()` / `resume()`
 
 Temporarily disable or re-enable all routing.

package/data/browser-hotkeys.json

@@ -0,0 +1,349 @@
+{
+  "$comment": "Machine-readable companion to docs/browser-hotkeys.md. Each combo entry describes who claims the binding and how strongly. Intended for runtime conflict warnings in keyboard-routing libraries (e.g. hotkey-router) and dev-time validation in apps like WebRadar. Update both this file and the markdown together — the markdown is the human source of truth, this file is the machine projection.",
+  "version": {
+    "generated": "2026-05-17",
+    "schema": "1.0",
+    "sources": [
+      "https://support.mozilla.org/en-US/kb/keyboard-shortcuts-perform-firefox-tasks-quickly",
+      "https://firefox-source-docs.mozilla.org/devtools-user/keyboard_shortcuts/index.html",
+      "https://support.google.com/chrome/answer/157179",
+      "https://developer.chrome.com/docs/devtools/shortcuts",
+      "https://support.apple.com/guide/safari/keyboard-shortcuts-and-gestures-cpsh003/mac",
+      "https://developer.apple.com/documentation/safari-developer-tools/web-inspector",
+      "https://support.microsoft.com/en-us/microsoft-edge/keyboard-shortcuts-in-microsoft-edge-50d3edab-30d9-c7e4-21ce-37fe2713cfad",
+      "https://support.apple.com/en-us/102650",
+      "https://support.microsoft.com/en-us/windows/keyboard-shortcuts-in-windows-dcc61a57-8ff0-cffe-9796-cb9706c75eec",
+      "https://help.gnome.org/gnome-help/shell-keyboard-shortcuts.html"
+    ]
+  },
+  "severityLevels": {
+    "hard": "Browser or OS intercepts before page-world keydown fires. preventDefault() can't recover it.",
+    "find-bar-only": "Reserved only when the browser's find bar has focus. Fires in page world during normal browsing.",
+    "menu-activation": "Win/Linux Alt+letter activates the browser menu bar. Hard to suppress reliably.",
+    "system-text": "Only reserved while a text input has focus (terminal-style cursor controls on macOS).",
+    "compose": "macOS Option+letter types a special character in text inputs. Outside inputs, free for page world.",
+    "os": "Operating system intercepts globally, before any application sees it.",
+    "devtools-open": "Only relevant when DevTools is already open; outside DevTools it fires normally."
+  },
+  "$keyFormat": "Each combo key uses hotkey-router-compatible syntax: modifiers in canonical order (ctrl|meta|alt|shift) joined by '+', then the key (lowercased letter, or symbolic name). Per-platform tables use the platform's native modifier name — `meta` on macOS = Cmd, `meta` on Windows = Win, `ctrl` on Linux/Windows = the primary modifier.",
+  "platforms": {
+    "mac": {
+      "browsers": {
+        "firefox": {
+          "meta+a": { "action": "Select all", "severity": "hard" },
+          "meta+b": { "action": "Bookmarks sidebar", "severity": "hard" },
+          "meta+c": { "action": "Copy", "severity": "hard" },
+          "meta+d": { "action": "Bookmark this page", "severity": "hard" },
+          "meta+e": { "action": "Search from page", "severity": "hard" },
+          "meta+f": { "action": "Find in page", "severity": "hard" },
+          "meta+g": { "action": "Find next", "severity": "hard" },
+          "meta+j": { "action": "Downloads", "severity": "hard" },
+          "meta+l": { "action": "Focus address bar", "severity": "hard" },
+          "meta+n": { "action": "New window", "severity": "hard" },
+          "meta+o": { "action": "Open file", "severity": "hard" },
+          "meta+p": { "action": "Print", "severity": "hard" },
+          "meta+r": { "action": "Reload", "severity": "hard" },
+          "meta+s": { "action": "Save page", "severity": "hard" },
+          "meta+t": { "action": "New tab", "severity": "hard" },
+          "meta+u": { "action": "View source", "severity": "hard" },
+          "meta+v": { "action": "Paste", "severity": "hard" },
+          "meta+w": { "action": "Close tab", "severity": "hard" },
+          "meta+x": { "action": "Cut", "severity": "hard" },
+          "meta+y": { "action": "Redo", "severity": "hard" },
+          "meta+z": { "action": "Undo", "severity": "hard" },
+          "meta+shift+a": { "action": "Add-ons manager", "severity": "hard" },
+          "meta+shift+b": { "action": "Bookmarks toolbar", "severity": "hard" },
+          "meta+shift+c": { "action": "Inspector (element picker)", "severity": "hard" },
+          "meta+shift+d": { "action": "Bookmark all tabs", "severity": "hard" },
+          "meta+shift+e": { "action": "Network Monitor", "severity": "hard" },
+          "meta+shift+f": { "action": "Toggle fullscreen", "severity": "hard" },
+          "meta+shift+g": { "action": "Find previous", "severity": "find-bar-only" },
+          "meta+shift+j": { "action": "Browser Console", "severity": "hard" },
+          "meta+shift+n": { "action": "New private window", "severity": "hard" },
+          "meta+shift+o": { "action": "Bookmarks library", "severity": "hard" },
+          "meta+shift+p": { "action": "New private window (alt)", "severity": "hard" },
+          "meta+shift+q": { "action": "Quit (with confirm)", "severity": "hard" },
+          "meta+shift+s": { "action": "Firefox Screenshot", "severity": "hard" },
+          "meta+shift+t": { "action": "Reopen closed tab", "severity": "hard" },
+          "meta+shift+v": { "action": "Paste as plain text", "severity": "hard" },
+          "meta+shift+w": { "action": "Close window", "severity": "hard" },
+          "meta+shift+z": { "action": "Redo", "severity": "hard" },
+          "meta+alt+c": { "action": "Inspector", "severity": "hard" },
+          "meta+alt+e": { "action": "Network Monitor", "severity": "hard" },
+          "meta+alt+i": { "action": "DevTools Toolbox", "severity": "hard" },
+          "meta+alt+j": { "action": "Browser Console", "severity": "hard" },
+          "meta+alt+k": { "action": "Web Console", "severity": "hard" },
+          "meta+alt+m": { "action": "Responsive Design Mode", "severity": "hard" },
+          "meta+alt+z": { "action": "Debugger", "severity": "hard" }
+        },
+        "chrome": {
+          "meta+a": { "action": "Select all", "severity": "hard" },
+          "meta+c": { "action": "Copy", "severity": "hard" },
+          "meta+d": { "action": "Bookmark this page", "severity": "hard" },
+          "meta+e": { "action": "Search selected text", "severity": "find-bar-only" },
+          "meta+f": { "action": "Find in page", "severity": "hard" },
+          "meta+g": { "action": "Find next", "severity": "hard" },
+          "meta+l": { "action": "Focus address bar", "severity": "hard" },
+          "meta+n": { "action": "New window", "severity": "hard" },
+          "meta+o": { "action": "Open file", "severity": "hard" },
+          "meta+p": { "action": "Print", "severity": "hard" },
+          "meta+r": { "action": "Reload", "severity": "hard" },
+          "meta+s": { "action": "Save page", "severity": "hard" },
+          "meta+t": { "action": "New tab", "severity": "hard" },
+          "meta+v": { "action": "Paste", "severity": "hard" },
+          "meta+w": { "action": "Close tab", "severity": "hard" },
+          "meta+x": { "action": "Cut", "severity": "hard" },
+          "meta+y": { "action": "History page", "severity": "hard" },
+          "meta+z": { "action": "Undo", "severity": "hard" },
+          "meta+shift+b": { "action": "Bookmarks bar toggle", "severity": "hard" },
+          "meta+shift+c": { "action": "DevTools Inspector", "severity": "hard" },
+          "meta+shift+d": { "action": "Bookmark all tabs", "severity": "hard" },
+          "meta+shift+g": { "action": "Find previous", "severity": "find-bar-only" },
+          "meta+shift+j": { "action": "Downloads page", "severity": "hard" },
+          "meta+shift+m": { "action": "Switch user / guest", "severity": "hard" },
+          "meta+shift+n": { "action": "New incognito window", "severity": "hard" },
+          "meta+shift+r": { "action": "Hard reload", "severity": "hard" },
+          "meta+shift+t": { "action": "Reopen closed tab", "severity": "hard" },
+          "meta+shift+v": { "action": "Paste as plain text", "severity": "hard" },
+          "meta+shift+w": { "action": "Close window", "severity": "hard" },
+          "meta+shift+z": { "action": "Redo", "severity": "hard" },
+          "meta+alt+i": { "action": "DevTools", "severity": "hard" },
+          "meta+alt+j": { "action": "DevTools (console)", "severity": "hard" },
+          "meta+alt+u": { "action": "View source", "severity": "hard" }
+        },
+        "safari": {
+          "meta+a": { "action": "Select all", "severity": "hard" },
+          "meta+c": { "action": "Copy", "severity": "hard" },
+          "meta+d": { "action": "Add to Reading List", "severity": "hard" },
+          "meta+f": { "action": "Find in page", "severity": "hard" },
+          "meta+g": { "action": "Find next", "severity": "hard" },
+          "meta+j": { "action": "Downloads", "severity": "hard" },
+          "meta+l": { "action": "Focus Smart Search", "severity": "hard" },
+          "meta+n": { "action": "New window", "severity": "hard" },
+          "meta+p": { "action": "Print", "severity": "hard" },
+          "meta+r": { "action": "Reload", "severity": "hard" },
+          "meta+s": { "action": "Save page", "severity": "hard" },
+          "meta+t": { "action": "New tab", "severity": "hard" },
+          "meta+v": { "action": "Paste", "severity": "hard" },
+          "meta+w": { "action": "Close tab", "severity": "hard" },
+          "meta+x": { "action": "Cut", "severity": "hard" },
+          "meta+z": { "action": "Undo", "severity": "hard" },
+          "meta+shift+c": { "action": "Inspector pick element", "severity": "hard" },
+          "meta+shift+d": { "action": "Add Reading List item", "severity": "hard" },
+          "meta+shift+g": { "action": "Find previous", "severity": "find-bar-only" },
+          "meta+shift+h": { "action": "Go to homepage", "severity": "hard" },
+          "meta+shift+n": { "action": "New private window", "severity": "hard" },
+          "meta+shift+r": { "action": "Reader mode", "severity": "hard" },
+          "meta+shift+t": { "action": "Reopen last closed tab", "severity": "hard" },
+          "meta+shift+v": { "action": "Paste as plain text", "severity": "hard" },
+          "meta+shift+w": { "action": "Close window", "severity": "hard" },
+          "meta+shift+z": { "action": "Redo", "severity": "hard" },
+          "meta+alt+c": { "action": "Web Inspector pick", "severity": "hard" },
+          "meta+alt+i": { "action": "Web Inspector", "severity": "hard" }
+        }
+      },
+      "system": {
+        "meta+space": { "action": "Spotlight", "severity": "os" },
+        "meta+tab": { "action": "App switcher", "severity": "os" },
+        "meta+h": { "action": "Hide app", "severity": "os" },
+        "meta+m": { "action": "Minimize window", "severity": "os" },
+        "meta+q": { "action": "Quit app", "severity": "os" },
+        "meta+shift+3": { "action": "Screenshot full screen", "severity": "os" },
+        "meta+shift+4": { "action": "Screenshot selection", "severity": "os" },
+        "meta+shift+5": { "action": "Screen recording tool", "severity": "os" },
+        "meta+shift+q": { "action": "Log out", "severity": "os" },
+        "meta+ctrl+q": { "action": "Lock screen", "severity": "os" },
+        "meta+ctrl+space": { "action": "Character Viewer", "severity": "os" },
+        "meta+alt+esc": { "action": "Force-quit dialog", "severity": "os" }
+      },
+      "noteForLetterCombos": {
+        "alt+a..z": { "behavior": "compose", "note": "Option+letter types special characters in text inputs (Option+E→´, Option+A→å, Option+F→ƒ). Outside inputs, free for page world." },
+        "ctrl+a..z": { "behavior": "system-text", "note": "Mac uses Ctrl+letter as terminal-style cursor controls inside text inputs (Ctrl+A=line start, Ctrl+E=line end, Ctrl+K=delete-to-end, etc.). Outside inputs, free for page world." }
+      }
+    },
+    "windows": {
+      "browsers": {
+        "firefox": {
+          "ctrl+a": { "action": "Select all", "severity": "hard" },
+          "ctrl+b": { "action": "Bookmarks sidebar", "severity": "hard" },
+          "ctrl+c": { "action": "Copy", "severity": "hard" },
+          "ctrl+d": { "action": "Bookmark this page", "severity": "hard" },
+          "ctrl+f": { "action": "Find in page", "severity": "hard" },
+          "ctrl+g": { "action": "Find next", "severity": "hard" },
+          "ctrl+h": { "action": "History sidebar", "severity": "hard" },
+          "ctrl+j": { "action": "Downloads", "severity": "hard" },
+          "ctrl+l": { "action": "Focus address bar", "severity": "hard" },
+          "ctrl+n": { "action": "New window", "severity": "hard" },
+          "ctrl+o": { "action": "Open file", "severity": "hard" },
+          "ctrl+p": { "action": "Print", "severity": "hard" },
+          "ctrl+r": { "action": "Reload", "severity": "hard" },
+          "ctrl+s": { "action": "Save page", "severity": "hard" },
+          "ctrl+t": { "action": "New tab", "severity": "hard" },
+          "ctrl+u": { "action": "View source", "severity": "hard" },
+          "ctrl+v": { "action": "Paste", "severity": "hard" },
+          "ctrl+w": { "action": "Close tab", "severity": "hard" },
+          "ctrl+x": { "action": "Cut", "severity": "hard" },
+          "ctrl+y": { "action": "Redo", "severity": "hard" },
+          "ctrl+z": { "action": "Undo", "severity": "hard" },
+          "ctrl+shift+a": { "action": "Add-ons manager", "severity": "hard" },
+          "ctrl+shift+b": { "action": "Bookmarks toolbar", "severity": "hard" },
+          "ctrl+shift+c": { "action": "Inspector (element picker)", "severity": "hard" },
+          "ctrl+shift+d": { "action": "Bookmark all tabs", "severity": "hard" },
+          "ctrl+shift+e": { "action": "Network Monitor", "severity": "hard" },
+          "ctrl+shift+g": { "action": "Find previous", "severity": "find-bar-only" },
+          "ctrl+shift+i": { "action": "Developer Tools", "severity": "hard" },
+          "ctrl+shift+j": { "action": "Browser Console", "severity": "hard" },
+          "ctrl+shift+k": { "action": "Web Console", "severity": "hard" },
+          "ctrl+shift+m": { "action": "Responsive Design Mode", "severity": "hard" },
+          "ctrl+shift+n": { "action": "New private window", "severity": "hard" },
+          "ctrl+shift+o": { "action": "Bookmarks library", "severity": "hard" },
+          "ctrl+shift+p": { "action": "New private window (alt)", "severity": "hard" },
+          "ctrl+shift+s": { "action": "Firefox Screenshot", "severity": "hard" },
+          "ctrl+shift+t": { "action": "Reopen closed tab", "severity": "hard" },
+          "ctrl+shift+v": { "action": "Paste as plain text", "severity": "hard" },
+          "ctrl+shift+w": { "action": "Close window", "severity": "hard" },
+          "ctrl+shift+y": { "action": "Downloads (alt)", "severity": "hard" },
+          "ctrl+shift+z": { "action": "Debugger", "severity": "hard" },
+          "alt+f": { "action": "File menu", "severity": "menu-activation" },
+          "alt+e": { "action": "Edit menu", "severity": "menu-activation" },
+          "alt+v": { "action": "View menu", "severity": "menu-activation" },
+          "alt+b": { "action": "Bookmarks menu", "severity": "menu-activation" },
+          "alt+t": { "action": "Tools menu", "severity": "menu-activation" },
+          "alt+h": { "action": "Help menu", "severity": "menu-activation" },
+          "alt+d": { "action": "Focus address bar", "severity": "hard" }
+        },
+        "chrome": {
+          "ctrl+a": { "action": "Select all", "severity": "hard" },
+          "ctrl+c": { "action": "Copy", "severity": "hard" },
+          "ctrl+d": { "action": "Bookmark this page", "severity": "hard" },
+          "ctrl+e": { "action": "Search from page", "severity": "hard" },
+          "ctrl+f": { "action": "Find in page", "severity": "hard" },
+          "ctrl+g": { "action": "Find next", "severity": "hard" },
+          "ctrl+h": { "action": "History page", "severity": "hard" },
+          "ctrl+j": { "action": "Downloads", "severity": "hard" },
+          "ctrl+k": { "action": "Search from page", "severity": "hard" },
+          "ctrl+l": { "action": "Focus address bar", "severity": "hard" },
+          "ctrl+n": { "action": "New window", "severity": "hard" },
+          "ctrl+o": { "action": "Open file", "severity": "hard" },
+          "ctrl+p": { "action": "Print", "severity": "hard" },
+          "ctrl+r": { "action": "Reload", "severity": "hard" },
+          "ctrl+s": { "action": "Save page", "severity": "hard" },
+          "ctrl+t": { "action": "New tab", "severity": "hard" },
+          "ctrl+u": { "action": "View source", "severity": "hard" },
+          "ctrl+v": { "action": "Paste", "severity": "hard" },
+          "ctrl+w": { "action": "Close tab", "severity": "hard" },
+          "ctrl+x": { "action": "Cut", "severity": "hard" },
+          "ctrl+z": { "action": "Undo", "severity": "hard" },
+          "ctrl+shift+b": { "action": "Bookmarks bar toggle", "severity": "hard" },
+          "ctrl+shift+d": { "action": "Bookmark all tabs", "severity": "hard" },
+          "ctrl+shift+g": { "action": "Find previous", "severity": "find-bar-only" },
+          "ctrl+shift+i": { "action": "DevTools", "severity": "hard" },
+          "ctrl+shift+j": { "action": "DevTools (console)", "severity": "hard" },
+          "ctrl+shift+m": { "action": "Switch user / guest", "severity": "hard" },
+          "ctrl+shift+n": { "action": "Incognito window", "severity": "hard" },
+          "ctrl+shift+r": { "action": "Hard reload", "severity": "hard" },
+          "ctrl+shift+t": { "action": "Reopen closed tab", "severity": "hard" },
+          "ctrl+shift+v": { "action": "Paste as plain text", "severity": "hard" },
+          "ctrl+shift+w": { "action": "Close window", "severity": "hard" },
+          "alt+d": { "action": "Focus address bar", "severity": "hard" },
+          "alt+e": { "action": "Customize menu", "severity": "menu-activation" },
+          "alt+f": { "action": "Customize menu (alt)", "severity": "menu-activation" }
+        },
+        "edge": {
+          "ctrl+a": { "action": "Select all", "severity": "hard" },
+          "ctrl+c": { "action": "Copy", "severity": "hard" },
+          "ctrl+d": { "action": "Favorite this page", "severity": "hard" },
+          "ctrl+e": { "action": "Search from page", "severity": "hard" },
+          "ctrl+f": { "action": "Find in page", "severity": "hard" },
+          "ctrl+g": { "action": "Find next", "severity": "hard" },
+          "ctrl+h": { "action": "History", "severity": "hard" },
+          "ctrl+j": { "action": "Downloads", "severity": "hard" },
+          "ctrl+k": { "action": "Search from page", "severity": "hard" },
+          "ctrl+l": { "action": "Focus address bar", "severity": "hard" },
+          "ctrl+m": { "action": "Mute current tab", "severity": "hard" },
+          "ctrl+n": { "action": "New window", "severity": "hard" },
+          "ctrl+o": { "action": "Open file", "severity": "hard" },
+          "ctrl+p": { "action": "Print", "severity": "hard" },
+          "ctrl+r": { "action": "Reload", "severity": "hard" },
+          "ctrl+s": { "action": "Save page", "severity": "hard" },
+          "ctrl+t": { "action": "New tab", "severity": "hard" },
+          "ctrl+u": { "action": "View source", "severity": "hard" },
+          "ctrl+v": { "action": "Paste", "severity": "hard" },
+          "ctrl+w": { "action": "Close tab", "severity": "hard" },
+          "ctrl+x": { "action": "Cut", "severity": "hard" },
+          "ctrl+z": { "action": "Undo", "severity": "hard" },
+          "ctrl+shift+b": { "action": "Favorites bar toggle", "severity": "hard" },
+          "ctrl+shift+d": { "action": "Bookmark all tabs in folder", "severity": "hard" },
+          "ctrl+shift+e": { "action": "Search in sidebar", "severity": "hard" },
+          "ctrl+shift+g": { "action": "Find previous", "severity": "find-bar-only" },
+          "ctrl+shift+i": { "action": "DevTools", "severity": "hard" },
+          "ctrl+shift+j": { "action": "DevTools (console)", "severity": "hard" },
+          "ctrl+shift+k": { "action": "Duplicate tab", "severity": "hard" },
+          "ctrl+shift+l": { "action": "Paste and search", "severity": "hard" },
+          "ctrl+shift+m": { "action": "Switch user / guest", "severity": "hard" },
+          "ctrl+shift+n": { "action": "InPrivate window", "severity": "hard" },
+          "ctrl+shift+o": { "action": "Open favorites", "severity": "hard" },
+          "ctrl+shift+p": { "action": "Print (system dialog)", "severity": "hard" },
+          "ctrl+shift+r": { "action": "Hard reload", "severity": "hard" },
+          "ctrl+shift+t": { "action": "Reopen closed tab", "severity": "hard" },
+          "ctrl+shift+u": { "action": "Read Aloud toggle", "severity": "hard" },
+          "ctrl+shift+v": { "action": "Paste without formatting", "severity": "hard" },
+          "ctrl+shift+w": { "action": "Close window", "severity": "hard" },
+          "ctrl+shift+y": { "action": "Collections", "severity": "hard" },
+          "alt+d": { "action": "Focus address bar", "severity": "hard" },
+          "alt+e": { "action": "Settings menu", "severity": "menu-activation" },
+          "alt+f": { "action": "Settings menu (alt)", "severity": "menu-activation" },
+          "alt+shift+b": { "action": "Focus favorites bar", "severity": "hard" },
+          "alt+shift+i": { "action": "Send feedback dialog", "severity": "hard" },
+          "alt+shift+t": { "action": "Focus app bar toolbar", "severity": "hard" }
+        }
+      },
+      "system": {
+        "meta+a": { "action": "Action Center", "severity": "os" },
+        "meta+c": { "action": "Windows search", "severity": "os" },
+        "meta+d": { "action": "Show desktop", "severity": "os" },
+        "meta+e": { "action": "File Explorer", "severity": "os" },
+        "meta+g": { "action": "Game bar", "severity": "os" },
+        "meta+h": { "action": "Voice dictation", "severity": "os" },
+        "meta+i": { "action": "Settings", "severity": "os" },
+        "meta+l": { "action": "Lock", "severity": "os" },
+        "meta+n": { "action": "Notification center", "severity": "os" },
+        "meta+p": { "action": "Project / display mode", "severity": "os" },
+        "meta+r": { "action": "Run dialog", "severity": "os" },
+        "meta+s": { "action": "Search", "severity": "os" },
+        "meta+v": { "action": "Clipboard history", "severity": "os" },
+        "meta+w": { "action": "Widgets", "severity": "os" },
+        "meta+x": { "action": "Quick Link menu", "severity": "os" },
+        "meta+z": { "action": "Snap layouts", "severity": "os" },
+        "meta+tab": { "action": "Task View", "severity": "os" },
+        "meta+shift+s": { "action": "Screenshot region", "severity": "os" },
+        "ctrl+shift+esc": { "action": "Task Manager", "severity": "os" },
+        "ctrl+alt+del": { "action": "Security screen", "severity": "os" },
+        "alt+tab": { "action": "Switch windows", "severity": "os" },
+        "alt+f4": { "action": "Close active window", "severity": "os" }
+      }
+    },
+    "linux": {
+      "browsers": {
+        "firefox": "$ref:platforms.windows.browsers.firefox",
+        "chrome": "$ref:platforms.windows.browsers.chrome",
+        "edge": "$ref:platforms.windows.browsers.edge"
+      },
+      "system": {
+        "$comment": "GNOME defaults. KDE and other DEs have similar-shaped reservations but vary; this is a conservative baseline.",
+        "meta+tab": { "action": "Switch windows", "severity": "os" },
+        "meta+a": { "action": "Show applications", "severity": "os" },
+        "meta+l": { "action": "Lock screen", "severity": "os" },
+        "meta+v": { "action": "Notification list", "severity": "os" },
+        "alt+tab": { "action": "Switch applications", "severity": "os" },
+        "alt+esc": { "action": "Cycle windows", "severity": "os" },
+        "alt+f2": { "action": "Run command", "severity": "os" },
+        "alt+f4": { "action": "Close window", "severity": "os" },
+        "ctrl+alt+tab": { "action": "Top-bar accessibility switcher", "severity": "os" },
+        "ctrl+alt+del": { "action": "Power-off dialog", "severity": "os" },
+        "ctrl+shift+alt+r": { "action": "Toggle screencast recording", "severity": "os" }
+      },
+      "noteForCtrlAlt": "Some Linux setups map right-Alt (AltGr) to 'compose' for typing accented characters, in which case AltGr+letter is reported as ctrl+alt+letter and types a special character. Avoid the ctrl+alt+letter namespace on Linux."
+    }
+  }
+}