Externalize the keybind catalog and preset registry to a shared contract

common/configs/keybind_catalog.schema.json

@@ -0,0 +1,76 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "https://raw.githubusercontent.com/beyond-all-reason/Beyond-All-Reason/master/common/configs/keybind_catalog.schema.json",
+	"title": "Keybind catalog",
+	"description": "Ordered, cross-surface catalog of keybindable commands grouped into categories. Shared by the in-game editor and external lobbies. Holds i18n keys and bind-action ids, not resolved strings or actual key bindings.",
+	"type": "array",
+	"items": {
+		"oneOf": [
+			{
+				"type": "object",
+				"description": "Category of keybindable commands.",
+				"required": ["category", "items"],
+				"additionalProperties": false,
+				"properties": {
+					"category": {
+						"type": "string",
+						"description": "i18n key for the category title."
+					},
+					"items": {
+						"type": "array",
+						"items": { "$ref": "#/definitions/item" }
+					}
+				}
+			},
+			{
+				"type": "object",
+				"description": "Actions bound but intentionally never shown, matched by exact id (not prefix).",
+				"required": ["hidden"],
+				"additionalProperties": false,
+				"properties": {
+					"hidden": {
+						"type": "array",
+						"items": { "type": "string", "description": "Exact action id to suppress." }
+					}
+				}
+			}
+		]
+	},
+	"definitions": {
+		"item": {
+			"oneOf": [
+				{
+					"type": "object",
+					"description": "Editable binding the user can rebind.",
+					"required": ["action", "label"],
+					"additionalProperties": false,
+					"properties": {
+						"action": { "type": "string", "description": "Bind command (command + space-separated args), exactly as passed to /bind and reported by GetKeyBindings." },
+						"label": { "type": "string", "description": "i18n key for the display label." }
+					}
+				},
+				{
+					"type": "object",
+					"description": "Informational row: shown read-only with a fixed key hint.",
+					"required": ["label", "keyLabel"],
+					"additionalProperties": false,
+					"properties": {
+						"label": { "type": "string", "description": "i18n key for the display label." },
+						"keyLabel": { "type": "string", "description": "i18n key for the non-editable key hint." }
+					}
+				},
+				{
+					"type": "object",
+					"description": "Prefix group: claims every bound action whose id starts with this prefix. With a label the arg after the prefix is interpolated as %{n} (or its two whitespace-split tokens as %{row}/%{col}); without one, rows show the raw id. With unit=true the arg is resolved to a unit's translated name.",
+					"required": ["prefix"],
+					"additionalProperties": false,
+					"properties": {
+						"prefix": { "type": "string", "description": "Action id prefix." },
+						"label": { "type": "string", "description": "i18n key for the display label, interpolated per matched action." },
+						"unit": { "type": "boolean", "description": "When true, the arg after the prefix is a unit codename resolved to its translated human name." }
+					}
+				}
+			]
+		}
+	}
+}

common/configs/keybind_presets.json

@@ -0,0 +1,9 @@
+{
+	"presets": [
+		{ "name": "Grid", "file": "luaui/configs/hotkeys/grid_keys.txt" },
+		{ "name": "Grid (60% Keyboard)", "file": "luaui/configs/hotkeys/grid_keys_60pct.txt" },
+		{ "name": "Legacy", "file": "luaui/configs/hotkeys/legacy_keys.txt" },
+		{ "name": "Legacy (60% Keyboard)", "file": "luaui/configs/hotkeys/legacy_keys_60pct.txt" },
+		{ "name": "Custom", "file": "uikeys.txt", "custom": true }
+	]
+}

common/configs/keybind_presets.schema.json

@@ -0,0 +1,25 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "https://raw.githubusercontent.com/beyond-all-reason/Beyond-All-Reason/master/common/configs/keybind_presets.schema.json",
+	"title": "Keybind preset registry",
+	"description": "Ordered registry of keybind presets shared across surfaces. The first entry is the default fallback. The active preset is whichever file the engine's KeybindingFile config points at; uikeys.txt is Custom.",
+	"type": "object",
+	"required": ["presets"],
+	"additionalProperties": false,
+	"properties": {
+		"presets": {
+			"type": "array",
+			"minItems": 1,
+			"items": {
+				"type": "object",
+				"required": ["name", "file"],
+				"additionalProperties": false,
+				"properties": {
+					"name": { "type": "string", "description": "Display name; also the key used to look a preset up by name." },
+					"file": { "type": "string", "description": "Bind file this preset loads (the engine KeybindingFile value). uikeys.txt is the Custom preset." },
+					"custom": { "type": "boolean", "description": "True for the user-editable Custom preset (uikeys.txt)." }
+				}
+			}
+		}
+	}
+}

common/configs/keybinds.README.md

@@ -0,0 +1,81 @@
+# Shared keybind contract
+
+These files are the cross-surface source of truth for keybind editing, so the in-game
+editor, Chobby, and the new lobby can each build their own UI without duplicating the
+data or the rules. They hold *data and rules only* - no rendering, no engine calls.
+
+## Files
+
+| File | What it is | Schema |
+|---|---|---|
+| `keybind_catalog.json` | Ordered categories of keybindable commands, with i18n label keys and bind-action ids. | `keybind_catalog.schema.json` |
+| `keybind_presets.json` | Ordered registry of presets (display name -> bind file), with the Custom preset flagged. | `keybind_presets.schema.json` |
+
+Both are validated in CI by `spec/keybind_catalog_spec.lua` (structure + referential
+integrity: preset files exist, every i18n key resolves).
+
+The actual bindings live in the plain-text bind files the registry points at
+(`luaui/configs/hotkeys/*.txt`, and `uikeys.txt` for Custom). Those are already portable -
+a consumer reads or copies them directly; only the registry (which file is which preset)
+needs sharing.
+
+## Catalog item kinds
+
+Each category's `items` entry is exactly one of:
+
+- `{ "action": "<bind command>", "label": "<i18n key>" }` - editable; user can rebind it.
+- `{ "label": "<i18n key>", "keyLabel": "<i18n key>" }` - informational, read-only key hint.
+- `{ "prefix": "<action id prefix>" }` - claims every bound action whose id starts with the
+  prefix, listed by raw id (for numbered families like `group 1`, `group 2`, ...). An optional
+  `"label"` is interpolated per matched action with the arg after the prefix as `%{n}` (or its
+  two whitespace-split tokens as `%{row}`/`%{col}`); an optional `"unit": true` resolves that
+  arg from a unit codename to its translated name.
+
+`action` is the bind command exactly as `/bind` expects and `GetKeyBindings` reports it
+(command plus space-separated args, e.g. `select AllMap++_ClearSelection_SelectAll+`).
+
+A single leading `{ "hidden": ["<action id>", ...] }` entry (not a category) lists actions
+that are bound but never shown - matched by exact id, not prefix, so a future action can't be
+suppressed by coincidence - so they surface neither as a row nor under "Other".
+
+## The config contract (behavior each surface implements)
+
+Structure lives in the schemas; these are the operations, which a schema can't express.
+Every surface answers the same questions from the same facts:
+
+- **Which preset are we on?** Read the engine config string `KeybindingFile`. Match it
+  against `keybind_presets.json` `file` values. `uikeys.txt` means **Custom**; anything
+  else is the named preset. If it points at nothing valid, fall back to the first entry.
+- **Switch preset.** Set `KeybindingFile` to the target preset's `file`, then reload the
+  bindings.
+- **Seed Custom.** The first time Custom is selected, `uikeys.txt` may not exist yet - seed
+  it from the currently active bindings so the user starts from what they had.
+- **Reset Custom to a preset.** Overwrite `uikeys.txt` with the chosen preset's bindings,
+  then reload. (Destructive to the user's custom binds - confirm first.)
+
+### Same rules, different plumbing
+
+| Operation | In-game (LuaUI) | Lobby (Chobby / web) |
+|---|---|---|
+| Read current preset | `Spring.GetConfigString("KeybindingFile")` | read the same engine config value |
+| Switch preset | `Spring.SetConfigString` + `keyreload` | write the config value the game reads on launch |
+| Seed / reset Custom | `keysave` a preset's binds into `uikeys.txt` | copy the preset file's contents into `uikeys.txt` |
+
+## i18n
+
+The catalog carries i18n *keys*, not resolved strings. Each surface resolves them through
+its own localization store - in-game that's `Spring.I18N` (sourced from
+`language/en/interface.json`, translated via Transifex). Sharing the *strings* across
+surfaces is a separate concern from sharing this structure.
+
+## Not covered yet
+
+- A widget/mod action-declaration API, so widgets register their own bindable actions
+  (with label + category + description) into the catalog at runtime instead of only being
+  editable when already bound.
+- Command descriptions / tooltips. The engine ships per-command descriptions in the shared
+  `cmd.*` i18n namespace (in `interface.json`, localized like everything else), so a future
+  iteration can show them by resolving `cmd.<command>` (falling back to `cmd.<command>._description`
+  for the few structured commands, and `cmd.luarules.<command>` for gadget commands) at display
+  time - no catalog change needed, since the catalog already carries the command per row. Widget/mod
+  actions have no `cmd.*` entry, so their descriptions depend on the declaration API above.