feat(keymap): gaming mode — picker + Minecraft + generic GAME layers (closes #11)

[rdlu]

Closes #11.

Re-applies the gaming layers (originally PR #19 / v2.0.0-rc1, reverted in PR #21 and parked on the stale gaming branch) onto current main (v1.6.0), reconciling the drift that accumulated after the revert. The old gaming branch was built on a pre-v1.4 base and is superseded by this branch.

Decisions (confirmed with owner)

• Structure: picker + Minecraft + one generic GAME layer (the original 4 per-game layers were byte-identical except LoL/Doom/CS2; collapsed into one generic).
• Entry: dedicated free SYS thumb key (the original joystick-center is now the mouse click).
• RGB: no .conf change — OLED name is the indicator.

Summary of all layers after this branch

#	Name	Access
0	BASE	always on
1	NAV	hold mo1 (left thumb)
2	CODE	hold lt(2,DEL) (right thumb)
3	MEDIA	hold mo3 (right thumb)
4	SYS|NUM	hold mo4 (left thumb)
5	GAME? (picker)	&to 5 — SYS right-thumb outer key (pos 63)
6	MINECRFT	picker joystick ↑
7	GAME (generic FPS/MOBA)	picker joystick ↓

Layers 0–4 are unchanged except a single SYS key: pos 63 &trans → &to 5.

Gaming layers

Entry gesture: hold mo(SYS|NUM) → tap SYS pos 63 (&to 5) → GAME? picker. Then joystick ↑ = Minecraft, ↓ = generic GAME, center = cancel. All other picker keys &none.

Entry reconciliation: the locked #11 design entered via the SYS joystick-center (pos 58), which was dead weight then. PR #25 turned the SYS joystick into a mouse, so pos 58 is now &mkp LCLK. Entry moved to the free right-thumb outer key (pos 63); the joystick-mouse is preserved intact.

Chassis (layers 6 & 7, identical except pos 0 — MC F3 / generic `): no HRM/hold-tap/caps_word; plain WASD/QWER + plain right half for chat.

• LCTRL@39 (pinky) · LSHIFT@57 (left thumb) · SPACE@56+@59 (both thumbs) · BSPC@60 · LALT@61 · F13@62 (PTT) · mo(MEDIA)@63
• Joystick = audio cluster (Vol±/Mute/Play-Pause) + center Enter; encoder = volume

Exit / switch combos (scoped layers = <6 7>): 0 + 12 → &GAME_EXIT (RGB off + &to 0); 0 + 5 → &to 5 (re-pick).

RGB: entry macros set per-game underglow (MC green / generic blue). CONFIG_ZMK_RGB_UNDERGLOW_AUTO_OFF_USB=y suppresses it on USB (wired gaming), so the OLED display-name is the primary active-mode indicator. Flip AUTO_OFF_USB=n later if the colour-while-wired is wanted.

Verification

• ✅ Both halves build locally (Zephyr SDK 0.17.0): left 380 KB / 792 KB (48.0%), right 269 KB / 792 KB (33.9%) — gaming adds ~4 KB to the tighter left half.
• ✅ mise run draw parses all 8 layers; picker macros render as icons.
• ⚠️ Local left build needed protobuf>=7.35 in .venv (nanopb/Studio gencode drift) — fixed in env + documented in CLAUDE.md gotchas.

Docs updated

README (layers table + Gaming section + refreshed memory budget), CLAUDE.md (structure table, gaming section, gotchas, active branch), KEYMAP.md (gaming layers section), keymap-drawer config (picker macro legends).

Test plan (hardware)

• Flash both halves; hold SYS, tap pos 63 → OLED shows GAME?
• Joystick ↑ → MINECRFT; ↓ → GAME; center → back to BASE
• In-game: WASD moves, LSHIFT@57 sneaks, LCTRL@39 sprints, SPACE jumps, right half types in chat
• Joystick adjusts volume/mute/play-pause without leaving game mode
• 0 + 12 exits to BASE; 0 + 5 re-opens picker
• F13 works as PTT in Discord; mo(MEDIA)@63 reachable
• Confirm SYS joystick-mouse (move + center-click) still works (pos 58 untouched)

🤖 Generated with Claude Code

---

Also in this branch — printable PDF pagination (tooling)

Adding gaming layers pushed the keymap to 8 layers, which crammed the mise run draw-pdf output onto one A4 page. draw-pdf now renders per-page SVGs (keymap-drawer --select-layers) and lays each group of layers on its own page: LAYERS_PER_PAGE (default 4) → 2 pages. Layer names come from the parsed YAML so the split scales automatically; draw-pdf-ci swaps the YAML instead of the SVG. Verified as a clean 2-page A4 PDF. Only .mise.toml changed (the PDF stays gitignored).

[rdlu]

Session log — gaming mode re-applied onto v1.6.0

Request: add the long-planned gaming mode (#11), but first review the locked plan and the code already written, since the branch/firmware had drifted out of sync.

Review findings:

• The plan (Dedicated gaming layer(s) #11) and code (PR feat(keymap): gaming layers + joystick launcher #19 / gaming branch / v2.0.0-rc1) were verified intact — adversarial check confirmed all position mappings with no off-by-one errors. LoL/Doom/CS2 were byte-identical.
• The gaming branch sits on a pre-v1.4 base; main moved to v1.6.0 via PRs Revert gaming layers to gaming branch + NAV arrows back to HJKL #21/fix(hrm): allow same-hand modifier combos #23/feat(keymap): move AltGr to right-thumb F12 (tap=F12, hold=RALT) #24/feat(keymap): central-column media on BASE; mouse → SYS|NUM only #25/feat(tooling): printable A4 PDF tasks + memory-budget summary in build-flash #26. The one real blocker: PR feat(keymap): central-column media on BASE; mouse → SYS|NUM only #25 turned the SYS joystick into a mouse, so the original entry key (joystick-center, pos 58) is now &mkp LCLK. Everything else re-applied cleanly; .conf is byte-identical so no config change was needed to build.

Decisions taken (owner): picker + Minecraft + 1 generic GAME layer · dedicated SYS thumb key for entry · no .conf change (OLED indicator).

Changed:

• config/eyelash_sofle.keymap: +2 entry macros (GAME_MC_TO/GAME_GEN_TO) + GAME_EXIT, +2 combos (exit 0+12, re-pick 0+5, scoped layers 6-7), SYS pos 63 → &to 5, +3 layers (GAME?/MINECRFT/GAME). Layers 0-4 otherwise untouched.
• Docs: README (layers + gaming section + budget refresh to v-gaming numbers), CLAUDE.md, KEYMAP.md; drawer legends for picker macros.

Verified: both halves build locally (left 48.0%, right 33.9%); mise run draw parses all 8 layers. Left build required protobuf>=7.35 in .venv (nanopb gencode drift) — fixed + noted in CLAUDE.md.

Rationale notes for the future: entry is on pos 63, not pos 58 specifically to preserve the SYS joystick-mouse (move + center-click). RGB color won't show on USB power by design (AUTO_OFF_USB=y); OLED name is the indicator.

[rdlu]

Follow-up — printable PDF now paginates across pages

The draw-pdf task was cramming all layers onto one A4 page (it embedded the full SVG as a single <img> with max-height:100%; with 8 layers everything shrank). A single image can't be split across pages, so draw-pdf now re-renders per-page SVGs (via keymap-drawer --select-layers) and gives each group of layers its own page.

• LAYERS_PER_PAGE (default 4) controls the split → 8 layers = 2 pages. Override e.g. LAYERS_PER_PAGE=3 mise run draw-pdf.
• Layer names are read from the parsed YAML, so the split scales automatically as layers change.
• draw-pdf-ci now swaps the YAML (not the committed SVG) from origin/main.

Verified: 2-page A4 PDF — p1 BASE/NAV/CODE/MEDIA, p2 SYS|NUM/GAME?/MINECRFT/GAME; no overflow/blank pages; header/footer + Page x / y intact. (keymap-drawer/eyelash_sofle.pdf stays gitignored — only .mise.toml changed.)