Module which_key 

Which-key — the pending-chord discoverability subsystem.

Design: docs/dev/architecture/which-key.md (§3 ownership, §5 lifecycle, §8 options). Slice plan: docs/dev/operations/slice-plans/archive/which-key.md (WK.6).

Hold a prefix; after a short idle delay a popup shows what can come next, derived from the live composite keymap the dispatcher itself walks — never from the static catalog (design §2, and the bug :describe-bindings still has).

Shape

Four moving parts, all owned here:

1. install wires the subsystem against the generic SubsystemBoot surface. It adds ZERO Editor:: methods and ZERO host Action variants — the mode-ownership acid test.
2. A PartialChordPending subscription stashes the payload and arms an idle gate.
3. The gate’s handler builds the model + grid and emits Effect::OpenPopup.
4. WhichKeyMode is the popup buffer’s major mode; its on_activate writes the stashed grid into the buffer it was activated on.

The popup is passive

PopupFocus::Passive — the document keeps focus, the caret and the modal state, so every keystroke continues to flow to the trie unchanged. A hint that changed what a chord does would be a vim deviation nobody asked for, and one that failed differently for every prefix (a transient-style takeover’s <C-n> shadows a real n continuation under <C-w>, and a real j under g) is the worst shape of that failure. See design §7.

Structs

WhichKey

Pending-chord discoverability.

WhichKeyDelay

Milliseconds a prefix must sit pending before the popup appears. 0 shows it immediately. The delay is what separates a hint from a stutter: a user who knows their chord finishes it well inside the window and never sees a frame of popup.

WhichKeyEnabled

Show the pending-chord popup at all.

WhichKeyGrid

The grid cell install created, handed to wire so both halves write and read the same one. Opaque: the host only carries it between the two calls.

WhichKeyMaxColumns

Maximum grid columns.

WhichKeyMaxHeight

Maximum content rows. Hard-capped at half the pane regardless.

WhichKeyMode

Major mode for *which-key*.

WhichKeySort

Row ordering: key (digits, lowercase, uppercase, punctuation, special, modifier-bearing) or label.

Constants

WHICH_KEY_BUFFER_NAME

The popup buffer’s registered name.

Functions

install

Register which-key-mode. Phase B, in the host’s install list.

wire

Wire which-key’s lifecycle: the idle gate, the PartialChordPending subscription, and the dismissal path. Called after the keymap and command-registry services are registered — see install for why that cannot be the same call.