NS11: SSH-client-aware keymap redesign #76
Reference in New Issue
Block a user
Delete Branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
OUTCOME:
mimhas a production keymap grammar for mobile SSH that accounts for real iPhone SSH clients exposing Esc/Ctrl and sometimes toolbar/meta keys, while still preserving default iOS keyboard fallback paths and narrow-viewport discoverability.WHY NOW: The current KEYMAP and requirements were shaped around default iOS keyboard constraints and avoided required Esc/Ctrl/Alt/function-key chords. The user clarified that real mobile SSH clients typically provide Esc and Ctrl, which materially changes the available ergonomic surface for mode switching, line motions (
0,^,$), selection, LSP/help workflows, file/search panels, and tool/PI panels. NS10 is proving regressions, but the keymap premise now needs a dedicated redesign parent instead of ad-hoc fixes.AUTHORITY: PRODUCT.md mobile-first terminal editor boundary; KEYMAP.md current v1 grammar; REQUIREMENTS.md input/session/testing/governance rows; NS2 closed mobile-keyboard work (#2); NS8 modal editor implementation (#43); NS10 terminal E2E matrix (#65); user decision that mobile SSH clients commonly expose Esc/Ctrl and this should widen the keymap design space.
REQUIREMENT IMPACT: likely needs REQUIREMENTS.md input rows updated as slices prove the revised keymap contract. Preserve req: input/001’s spirit (common actions must be mobile-reachable) but revisit whether Esc/Ctrl are always forbidden or allowed as first-class mobile SSH paths with fallback.
SLICES:
0,^,$alternatives)MEMBERSHIP MECHANISM: Gitea fallback via this parent checklist plus explicit parent reference in each child issue body.
AGENT AUTHORITY DEFAULTS:
BLOCKERS: Need trace/product evidence for which mobile SSH clients/keyboard rows are baseline versus optional accelerators. Slices may start with documented assumptions, but final grammar should distinguish required fallback, common SSH-toolbar path, and attached-keyboard path.
PROOF: KEYMAP.md and REQUIREMENTS.md distinguish default-iOS fallback, mobile SSH toolbar Esc/Ctrl paths, and attached-keyboard paths; terminal E2E proves mode switching, line motions, selection, LSP help, file/search/job/PI panels, and common editing tasks under explicit keystroke budgets; no common action is reachable only through an untested or hidden chord.
EVIDENCE ARTIFACTS: KEYMAP diffs, requirement rows, terminal E2E transcripts/screenshots/keystrokes, mobile SSH trace fixtures when available, dogfood notes for real clients.
REGRESSION LEDGER: Insert mode cannot be exited comfortably; select mode fails to extend with motions;
$/0/^are inaccessible on mobile; LSP/help and panel workflows become too key-heavy; Esc/Ctrl assumptions are either over-forbidden or over-required; default iOS fallback silently breaks.NON-GOALS: No native iOS keyboard app, runtime keymap config, plugin system, Vim compatibility promise, or unverified Android/keyboards without traces. Do not remove default-iOS fallback just because Esc/Ctrl are available in common SSH clients.
PARENT_CONTRACT:
outcome: SSH-client-aware mobile keymap grammar with explicit fallback tiers and E2E proof.
authority: PRODUCT.md, KEYMAP.md, REQUIREMENTS.md, NS2/NS8/NS10, user Esc/Ctrl decision.
proof: docs/requirements updated plus terminal E2E traces for mode/motion/select/LSP/panels under key budgets.
evidence_artifacts: terminal E2E transcripts, screenshots, keystroke TSVs, mobile SSH traces/dogfood notes.
regression_ledger: inaccessible mode exit, broken select motions, mobile-inaccessible line motions, too-heavy LSP/panel workflows, false Esc/Ctrl assumptions.
requirement_impact: likely updates input requirements.
non_goals: no native client/keymap config/plugin/Vim compatibility promise.
Completed parent checklist item: Define mobile SSH input tiers and update KEYMAP/requirements.
Implemented in local commit
2e60a09(Define mobile SSH input tiers):Verification:
redgate list /opt/repositories/mim/REQUIREMENTS.md && redgate lint /opt/repositories/mim/REQUIREMENTS.md && redgate health /opt/repositories/mim/REQUIREMENTS.md✅zig build test✅Completed parent checklist item: Mode switching contract across Normal/Insert/Select.
Implemented in local commit
d5c31a9(Document Esc and Ctrl bracket mode exits):ESCbyte) normalizes/traces as Escape.ctrl-bracket-mode-switchproving Insert→Normal via Ctrl-[/ESC byte without leaking raw^[text.Verification:
zig build test✅zig build terminal-e2e✅zig build✅zig build run -- --help✅zig build --prefix /tmp/mim-install verify-install-code✅redgate list /opt/repositories/mim/REQUIREMENTS.md✅redgate lint /opt/repositories/mim/REQUIREMENTS.md && redgate health /opt/repositories/mim/REQUIREMENTS.md✅Completed parent checklist item: Motion grammar for line start/end and selection motions.
Implemented in local commit
d7bf5ed(Separate first nonblank line motion):move_line_first_nonblankso^is distinct from absolute line start.H/Laliases for absolute line start/end and attached/Vim-style0/$aliases.^,H,L,0,$line motions.first-nonblank-line-motion.Verification:
zig build test✅zig build terminal-e2e✅zig build✅zig build run -- --help✅zig build --prefix /tmp/mim-install verify-install-code✅redgate list /opt/repositories/mim/REQUIREMENTS.md✅redgate lint /opt/repositories/mim/REQUIREMENTS.md && redgate health /opt/repositories/mim/REQUIREMENTS.md✅Completed parent checklist item: Redesign selection/object workflows for thumb + Esc/Ctrl ergonomics.
Implemented in local commit
accbedb(Add select object rail):s o <object>select-object rail so object selection no longer conflicts withw/l/h/j/kselection motions.sthen motion vss o w/l/i/p/f/dobject selection.select-object-word-rail.Verification:
zig build test✅zig build terminal-e2e✅zig build✅zig build run -- --help✅zig build --prefix /tmp/mim-install verify-install-code✅redgate list /opt/repositories/mim/REQUIREMENTS.md✅redgate lint /opt/repositories/mim/REQUIREMENTS.md && redgate health /opt/repositories/mim/REQUIREMENTS.md✅Completed parent checklist item: Redesign LSP hover/signature/parameter navigation shortcuts for mobile SSH.
Implemented in local commit
4789cf7(Group LSP parameter navigation on language rail):Space l n/Space l pfor next/previous parameter navigation.g a/g Aas attached-keyboard accelerators, documented as aliases rather than the only path.lsp-assisted-codingterminal E2E to exercise hover, signature, parameter panel navigation, diagnostics, formatting, save, and quit.Verification:
zig build test✅zig build terminal-e2e -- --scenario lsp-assisted-coding✅zig build terminal-e2e✅zig build✅zig build run -- --help✅zig build --prefix /tmp/mim-install verify-install-code✅redgate list /opt/repositories/mim/REQUIREMENTS.md✅redgate lint /opt/repositories/mim/REQUIREMENTS.md && redgate health /opt/repositories/mim/REQUIREMENTS.md✅Completed parent checklist item: Redesign file/search/job/PI panels around the wider key surface.
Implemented in local commit
c6c5366(Expose panel rails with mobile aliases):Space afor Pi/assistant panel, preservingSpace Pas attached-keyboard mnemonic.Space jfor jobs/tasks rail, preservingSpace tas task mnemonic.Space yfor symbols rail, preservingSpace pas historical/programming mnemonic.Space f/Space sand updated the top leader status to expose files/search/jobs/Pi/symbols together within narrow help.Space aPi panel andSpace jjob output panel paths.Verification:
zig build test✅zig build terminal-e2e -- --scenario file-and-pi-panels && zig build terminal-e2e -- --scenario job-cancel-output-panel✅zig build terminal-e2e✅zig build✅zig build run -- --help✅zig build --prefix /tmp/mim-install verify-install-code✅redgate list /opt/repositories/mim/REQUIREMENTS.md✅redgate lint /opt/repositories/mim/REQUIREMENTS.md && redgate health /opt/repositories/mim/REQUIREMENTS.md✅Completed final parent checklist item: Prove the revised grammar in terminal E2E with keystroke budgets and traces.
No source changes in this receipt; proof ran from clean local commit
c6c5366.Terminal E2E coverage anchors under
.zig-cache/terminal-e2e/<scenario>/:ctrl-bracket-mode-switch: Insert→Normal via Ctrl-[ / ESC byte without raw^[text.document-half-page-motions:G,gg, Ctrl-D, andg udocument/half-page motion paths.dot-repeat-local-edit: Normal-mode.deterministic local-edit repeat.coding-symbol-rail: coding punctuation rail under mobile/iOS-QWERTZ space path,max_key_events=24.select-mode-motions: Select mode extends selection with line/motion keys.select-object-word-rail: non-conflictings o wobject selection rail.first-nonblank-line-motion:^first-nonblank is distinct from line start.lsp-assisted-coding:Space l h/s/n/p, diagnostics, format, save/quit,max_key_events=27.project-search-panel: project search panel path,max_key_events=13.file-and-pi-panels:Space ffiles and no-shiftSpace aPi panel,max_key_events=8.job-cancel-output-panel: no-shiftSpace jjob output/cancel path,max_key_events=6.multi-file-coding-loop: file-open/edit/save loop,max_key_events=30.Verification:
zig build test✅zig build terminal-e2e✅zig build✅zig build v1-smoke✅zig build run -- --help✅zig build --prefix /tmp/mim-install verify-install-code✅redgate list /opt/repositories/mim/REQUIREMENTS.md✅redgate lint /opt/repositories/mim/REQUIREMENTS.md && redgate health /opt/repositories/mim/REQUIREMENTS.md✅All #76 checklist items are now complete; closing #76.