keymap: state that chord reservations are opt-in through with_reserved

crates/keymap/README.md

@@ -13,6 +13,9 @@ its file-format readers and its UI.
   kept or reported (`Keymap::problems`, the import report).
 - Hostile input is capped: commands, bindings per command, text lengths, import entries, keys,
   path segments and fuzzy suggestions (the `MAX_*` constants). What is cut is counted.
+- Reserved chords are opt-in. A keymap reserves no chord unless the app passes a list to
+  `Keymap::with_reserved`, e.g. `reserved::system(platform)` for the operating system's window
+  switching and closing chords. A reserved chord cannot be assigned or bound.
 - Dependencies: `serde` and `serde_json`; `egui` with the `egui` feature.
 
 ## A catalogue and dispatch

crates/keymap/src/keymap.rs

@@ -434,7 +434,8 @@ impl Keymap {
         self
     }
 
-    /// Chords that cannot be assigned, e.g. [`reserved::system`](crate::reserved::system).
+    /// Chords that cannot be assigned or bound, e.g. [`reserved::system`](crate::reserved::system).
+    /// Without this call the keymap reserves no chord.
     pub fn with_reserved(mut self, chords: Vec<Chord>) -> Keymap {
         self.reserved = chords;
         self.reload();

crates/keymap/src/lib.rs

@@ -6,8 +6,10 @@
 //! protocols store, display text per platform, and a reader for other applications' key text.
 //! [`command`] names what a binding runs, [`scope`] where it works, and [`keymap`] holds an app's
 //! catalogue with default bindings, the user's [`Overrides`], dispatch ([`Keymap::lookup`]),
-//! editing and conflicts. [`reserved`] lists the chords each operating system takes. [`import`]
-//! brings in other applications' shortcut sets. With the `egui` feature, the `egui` module
+//! editing and conflicts. [`reserved`] lists the chords each operating system takes; a keymap
+//! reserves no chord unless the app opts in with [`Keymap::with_reserved`], e.g.
+//! `with_reserved(reserved::system(platform))`. [`import`] brings in other applications' shortcut
+//! sets. With the `egui` feature, the `egui` module
 //! converts to and from egui keys, matches key presses against bindings and dispatches a frame's
 //! key events.
 //!

crates/keymap/src/reserved.rs

@@ -1,4 +1,7 @@
 //! Chords the operating system takes before the app sees them.
+//!
+//! A keymap reserves these only when the app passes them to
+//! [`Keymap::with_reserved`](crate::Keymap::with_reserved).
 
 use crate::chord::{Chord, Platform};
 
@@ -25,7 +28,8 @@ const LINUX: &[&str] = &[
     "Cmd+Alt+F12",
 ];
 
-/// The window switching, closing and session chords of `platform`.
+/// The window switching, closing and session chords of `platform`, for
+/// [`Keymap::with_reserved`](crate::Keymap::with_reserved).
 pub fn system(platform: Platform) -> Vec<Chord> {
     let list = match platform {
         Platform::Mac => MAC,