From f831b569861df8188d536224acc7267ecd2876fe Mon Sep 17 00:00:00 2001
From: Barrett Ruth <br.barrettruth@gmail.com>
Date: Sat, 7 Feb 2026 13:22:19 -0500
Subject: [PATCH] feat: add <Plug> mappings for all primary actions

Problem: users who want keybindings must call vim.cmd('CP run') or
reach into internal Lua modules directly. There is no stable,
discoverable, lazy-load-friendly public API for key binding.

Solution: define 7 <Plug> mappings in plugin/cp.lua that dispatch
through the same handle_command() code path as :CP. Document them
in a new MAPPINGS section in the vimdoc with helptags and an example
config block.
---
 doc/cp.nvim.txt | 37 +++++++++++++++++++++++++++++++++++++
 plugin/cp.lua   | 14 ++++++++++++++
 2 files changed, 51 insertions(+)

diff --git a/doc/cp.nvim.txt b/doc/cp.nvim.txt
index 17fd18c..9361121 100644
--- a/doc/cp.nvim.txt
+++ b/doc/cp.nvim.txt
@@ -202,6 +202,43 @@ Debug Builds ~
         }
 <
 
+==============================================================================
+MAPPINGS                                                        *cp-mappings*
+
+cp.nvim provides <Plug> mappings for all primary actions. These dispatch
+through the same code path as |:CP|.
+
+                                                              *<Plug>(cp-run)*
+<Plug>(cp-run)          Run tests in I/O view. Equivalent to :CP run.
+
+                                                            *<Plug>(cp-panel)*
+<Plug>(cp-panel)        Open full-screen test panel. Equivalent to :CP panel.
+
+                                                             *<Plug>(cp-edit)*
+<Plug>(cp-edit)         Open the test case editor. Equivalent to :CP edit.
+
+                                                             *<Plug>(cp-next)*
+<Plug>(cp-next)         Navigate to the next problem. Equivalent to :CP next.
+
+                                                             *<Plug>(cp-prev)*
+<Plug>(cp-prev)         Navigate to the previous problem. Equivalent to :CP prev.
+
+                                                             *<Plug>(cp-pick)*
+<Plug>(cp-pick)         Launch the contest picker. Equivalent to :CP pick.
+
+                                                         *<Plug>(cp-interact)*
+<Plug>(cp-interact)     Open interactive mode. Equivalent to :CP interact.
+
+Example configuration: >lua
+    vim.keymap.set('n', '<leader>cr', '<Plug>(cp-run)')
+    vim.keymap.set('n', '<leader>cp', '<Plug>(cp-panel)')
+    vim.keymap.set('n', '<leader>ce', '<Plug>(cp-edit)')
+    vim.keymap.set('n', '<leader>cn', '<Plug>(cp-next)')
+    vim.keymap.set('n', '<leader>cN', '<Plug>(cp-prev)')
+    vim.keymap.set('n', '<leader>cc', '<Plug>(cp-pick)')
+    vim.keymap.set('n', '<leader>ci', '<Plug>(cp-interact)')
+<
+
 ==============================================================================
 CONFIGURATION                                                      *cp-config*
 
diff --git a/plugin/cp.lua b/plugin/cp.lua
index b91a3d5..2689e71 100644
--- a/plugin/cp.lua
+++ b/plugin/cp.lua
@@ -154,3 +154,17 @@ end, {
     return {}
   end,
 })
+
+local function cp_action(action)
+  return function()
+    require('cp').handle_command({ fargs = { action } })
+  end
+end
+
+vim.keymap.set('n', '<Plug>(cp-run)', cp_action('run'), { desc = 'CP run tests' })
+vim.keymap.set('n', '<Plug>(cp-panel)', cp_action('panel'), { desc = 'CP open panel' })
+vim.keymap.set('n', '<Plug>(cp-edit)', cp_action('edit'), { desc = 'CP edit test cases' })
+vim.keymap.set('n', '<Plug>(cp-next)', cp_action('next'), { desc = 'CP next problem' })
+vim.keymap.set('n', '<Plug>(cp-prev)', cp_action('prev'), { desc = 'CP previous problem' })
+vim.keymap.set('n', '<Plug>(cp-pick)', cp_action('pick'), { desc = 'CP pick contest' })
+vim.keymap.set('n', '<Plug>(cp-interact)', cp_action('interact'), { desc = 'CP interactive mode' })