A remote console for HPE iLO managed servers.

A map is a delta over a protected base

A protected base map, us-base, holds the identity translation: 96 physical key rules and 97 clipboard character rules. A language map declares "extends": "us-base" and lists only what differs. The built-in German map is 20 physical rules, because the other 76 keys already behave correctly.

Inheritance is resolved when the maps load, nests deeper than one level, and a map that extends itself through a cycle is rejected instead of hanging the loader.

Physical rules rewrite one key per state

The German 7, which carries / on Shift and { on AltGr:

{
  "input": "7",
  "plain": { "key": "DIGIT_7" },
  "shift": { "key": "SLASH" },
  "altGr": { "key": "LEFT_BRACKET",
             "modifiers": ["left_shift"] }
}

Text rules drive clipboard paste

Clipboard text is retyped as real keystrokes, so it works in BIOS/UEFI screens that have no clipboard of their own:

{
  "char": "@",
  "strokes": [
    { "key": "DIGIT_2", "modifiers": ["left_shift"] }
  ]
}

Because the remote target is always US, us-base already covers every character a US keyboard can produce, so most language maps need no text rules at all. The built-in German map defines none.

How a keystroke resolves

• State priority is AltGr, then Shift, then plain.
• A key with a plain rule but no shift rule falls back to the plain stroke plus left_shift, so the common case needs one line.
• Ctrl, Alt and GUI combinations bypass language translation entirely. CTRL+C stays CTRL+C, and CTRL+ALT+DEL keeps working under any map.
• { "suppress": true } marks a source key with no portable US equivalent, so it is swallowed rather than mistyped.
• A clipboard character that neither the map nor its base defines is counted and reported after the paste instead of being silently dropped.

Adding your own layout

1. Export the template. Keyboard Layout → Export built-in German map... writes a working german.json next to an English authoring guide, as one atomic pair with rollback, so a failed export never leaves half a file behind.
2. Edit it, or let an LLM do it. The guide carries a prompt template written for exactly that, and a JSON Schema documents every field.
3. Drop it in and restart. Put the .json file directly into the keyboard-maps directory beside Firstlight.exe. It appears in the menu under its own displayName.

A broken map never breaks the session

Maps are parsed strictly: unknown or trailing JSON, a wrong schemaVersion, a non-US targetLocale, a duplicated key or character, an unknown HID name and files over 1 MiB are all rejected. Every rejection becomes a startup warning rather than a failure. The remaining maps stay selectable, a built-in map shadowed by a broken external file is restored, and two external files claiming the same id cancel each other out, so a forgotten copy cannot silently win.