From fa3a6c48e765a6b8446c4fb9709f74f8948527d3 Mon Sep 17 00:00:00 2001
From: Barrett Ruth <br.barrettruth@gmail.com>
Date: Thu, 26 Feb 2026 22:54:27 -0500
Subject: [PATCH] docs: add statusline integration recipes

Problem: cp.nvim exposed no documentation showing how to integrate its
runtime state into a statusline. Users had to discover the state module
API by reading source.

Solution: add a STATUSLINE INTEGRATION section to the vimdoc with a
state API reference and recipes for vanilla statusline, lualine, and
heirline. Also anchors the *cp.State* help tag referenced in prose
elsewhere in the doc.
---
 doc/cp.nvim.txt | 110 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 110 insertions(+)

diff --git a/doc/cp.nvim.txt b/doc/cp.nvim.txt
index 49cdaf7..27563a1 100644
--- a/doc/cp.nvim.txt
+++ b/doc/cp.nvim.txt
@@ -888,6 +888,116 @@ Functions ~
         Parameters: ~
             {bufnr}  (integer) Buffer handle
 
+==============================================================================
+STATUSLINE INTEGRATION                                        *cp-statusline*
+
+cp.nvim exposes its runtime state through a public module that can be queried
+from any statusline plugin. Import it with: >lua
+    local state = require('cp.state')
+<
+All getters return nil when no problem is active, so guard every value before
+use. Calling any getter outside a CP context is safe and has no side effects.
+
+State API ~
+                                                                  *cp.State*
+The following getters are available for statusline use:
+
+    get_platform()      (string?) Platform id. e.g. "codeforces", "atcoder"
+    get_contest_id()    (string?) Contest id. e.g. "1933", "abc324"
+    get_problem_id()    (string?) Problem id. e.g. "A", "B"
+    get_language()      (string?) Language id. e.g. "cpp", "python"
+    get_base_name()     (string?) Derived filename stem. e.g. "1933a"
+    get_source_file()   (string?) Full source filename. e.g. "1933a.cc"
+    get_active_panel()  (string?) Non-nil when the test panel is open.
+
+Recipe: vanilla statusline ~
+
+Set vim.o.statusline from an autocommand so it is recalculated on every
+BufEnter: >lua
+    local function cp_component()
+      local state = require('cp.state')
+      local platform = state.get_platform()
+      if not platform then
+        return ''
+      end
+      local parts = {
+        platform,
+        state.get_contest_id(),
+        state.get_problem_id(),
+        state.get_language(),
+      }
+      local filtered = {}
+      for _, v in ipairs(parts) do
+        if v then filtered[#filtered + 1] = v end
+      end
+      return '[' .. table.concat(filtered, ' · ') .. ']'
+    end
+
+    vim.api.nvim_create_autocmd({ 'BufEnter', 'User' }, {
+      callback = function()
+        vim.o.statusline = cp_component() .. ' %f %=%l:%c'
+      end
+    })
+<
+
+Recipe: lualine ~
+
+Add a custom component to any lualine section. The cond field hides the
+component entirely when no problem is active: >lua
+    local function cp_lualine()
+      local state = require('cp.state')
+      local parts = {
+        state.get_platform(),
+        state.get_contest_id(),
+        state.get_problem_id(),
+        state.get_language(),
+      }
+      local filtered = {}
+      for _, v in ipairs(parts) do
+        if v then filtered[#filtered + 1] = v end
+      end
+      return table.concat(filtered, ' · ')
+    end
+
+    require('lualine').setup({
+      sections = {
+        lualine_c = {
+          {
+            cp_lualine,
+            cond = function()
+              return require('cp.state').get_platform() ~= nil
+            end,
+          },
+        },
+      },
+    })
+<
+
+Recipe: heirline ~
+
+Build a heirline component using a provider and condition: >lua
+    local CpComponent = {
+      condition = function()
+        return require('cp.state').get_platform() ~= nil
+      end,
+      provider = function()
+        local state = require('cp.state')
+        local parts = {
+          state.get_platform(),
+          state.get_contest_id(),
+          state.get_problem_id(),
+          state.get_language(),
+        }
+        local filtered = {}
+        for _, v in ipairs(parts) do
+          if v then filtered[#filtered + 1] = v end
+        end
+        return '[' .. table.concat(filtered, ' · ') .. ']'
+      end,
+    }
+<
+Include CpComponent in your heirline StatusLine spec wherever desired.
+
 ==============================================================================
 PANEL KEYMAPS                                                  *cp-panel-keys*