zuqini · zuqini · May 7, 2026 · May 7, 2026 · May 7, 2026 · May 7, 2026
diff --git a/doc/zpack.txt b/doc/zpack.txt
@@ -820,6 +820,10 @@ pattern         (string|string[], optional)
       mode = "n"|{"n","v"},           -- Mode(s), default: "n"
       remap = true|false,             -- Allow remapping, default: false
       nowait = true|false,            -- Default: false
+      expr = true|false,              -- RHS is an expression, default: false
+      silent = true|false,            -- Suppress command-line output, default: false
+      noremap = true|false,           -- Inverse of `remap` (lazy.nvim alias)
+      replace_keycodes = true|false,  -- Replace keycodes in expr result; defaults to true when expr is true
     }
 <
 
@@ -843,11 +847,35 @@ mode            (string|string[], optional)
 remap           (boolean, optional)
                 Whether to allow remapping (recursive mapping). When false,
                 the mapping is non-recursive (like noremap). Default: false.
+                Wins over the `noremap` alias when both are set.
 
                                                       *zpack.KeySpec.nowait*
 nowait          (boolean, optional)
                 Whether to use nowait. Default: false.
 
+                                                        *zpack.KeySpec.expr*
+expr            (boolean, optional)
+                Whether the right-hand side is an expression. When true, the
+                returned value of the rhs is used as the keys to feed.
+                Default: false.
+
+                                                      *zpack.KeySpec.silent*
+silent          (boolean, optional)
+                Whether the keymap should be silent (suppress command-line
+                output). Default: false.
+
+                                                     *zpack.KeySpec.noremap*
+noremap         (boolean, optional)
+                lazy.nvim compatibility alias for the inverse of `remap`.
+                Consulted only when `remap` is unset; explicit `remap` always
+                wins. When neither is set, the keymap is non-remappable
+                (matching `remap = false`).
+
+                                            *zpack.KeySpec.replace_keycodes*
+replace_keycodes (boolean, optional)
+                When `expr` is true, replace keycodes in the resulting
+                string. Default: true when `expr` is true; otherwise unused.
+
 ==============================================================================
 11. TIPS & MIGRATION                                *zpack-tips-and-migration*
 

diff --git a/docs/spec.md b/docs/spec.md
@@ -85,6 +85,10 @@ The plugin data object passed to hooks and trigger functions:
   mode = "n"|{"n","v"},           -- Mode(s), default: "n"
   remap = true|false,             -- Allow remapping, default: false
   nowait = true|false,            -- Default: false
+  expr = true|false,              -- RHS is an expression, default: false
+  silent = true|false,            -- Suppress command-line output, default: false
+  noremap = true|false,           -- Inverse of `remap` (lazy.nvim alias)
+  replace_keycodes = true|false,  -- Replace keycodes in expr result; defaults to true when expr is true
 }
 ```
 

diff --git a/lua/zpack/keymap.lua b/lua/zpack/keymap.lua
@@ -2,18 +2,32 @@ local util = require('zpack.utils')
 
 local M = {}
 
----@param mapping string
+local SUPPORTED_OPTS = { 'desc', 'remap', 'nowait', 'expr', 'silent', 'replace_keycodes' }
+
+---@param lhs string
 ---@param rhs string|fun()
----@param remap? boolean
----@param desc? string
----@param mode? string|string[]
----@param nowait? boolean
-M.map = function(mapping, rhs, remap, desc, mode, nowait)
-  if remap == nil then remap = false end
-  desc = desc or ""
-  mode = mode or { 'n' }
-  if nowait == nil then nowait = false end
-  vim.keymap.set(mode, mapping, rhs, { desc = desc, remap = remap, nowait = nowait })
+---@param opts? zpack.KeySpec|zpack.KeymapOpts
+M.map = function(lhs, rhs, opts)
+  opts = opts or {}
+  local set_opts = {}
+  for _, k in ipairs(SUPPORTED_OPTS) do
+    set_opts[k] = opts[k]
+  end
+  -- lazy.nvim compat: noremap is the inverse of remap. Explicit `remap` wins;
+  -- the alias is consulted only when remap is unset.
+  if set_opts.remap == nil and opts.noremap ~= nil then
+    set_opts.remap = not opts.noremap
+  end
+  if set_opts.expr then
+    -- Mirror Neovim's documented expr→replace_keycodes default so zpack owns the contract.
+    if set_opts.replace_keycodes == nil then
+      set_opts.replace_keycodes = true
+    end
+  else
+    -- vim.keymap.set raises when replace_keycodes is set without expr.
+    set_opts.replace_keycodes = nil
+  end
+  vim.keymap.set(opts.mode or { 'n' }, lhs, rhs, set_opts)
 end
 
 ---@param keys zpack.KeySpec|zpack.KeySpec[]|string
@@ -22,7 +36,7 @@ M.apply_keys = function(keys)
 
   for _, key in ipairs(key_list) do
     if key[2] ~= nil then
-      M.map(key[1], key[2], key.remap, key.desc, key.mode, key.nowait)
+      M.map(key[1], key[2], key)
     end
   end
 end

diff --git a/lua/zpack/lazy_trigger/keys.lua b/lua/zpack/lazy_trigger/keys.lua
@@ -47,13 +47,25 @@ M.setup = function(registered_pack_specs)
   -- Create keymaps
   for _, key_info in pairs(key_to_info) do
     local lhs = key_info.key_spec[1]
+    local key_spec = key_info.key_spec
     keymap.map(lhs, function()
       pcall(vim.keymap.del, key_info.split_mode, lhs)
       for _, pack_spec in ipairs(key_info.pack_specs) do
         loader.process_spec(pack_spec)
       end
       vim.api.nvim_feedkeys(vim.keycode(lhs), 'm', false)
-    end, false, key_info.key_spec.desc, key_info.split_mode, false)
+    end, {
+      desc = key_spec.desc,
+      mode = key_info.split_mode,
+      -- Forward user-facing opts so the first (proxy) press matches subsequent
+      -- presses through the real keymap. expr/replace_keycodes are the only
+      -- omissions: the proxy's rhs is a Lua callback returning nil, so making
+      -- it expr would feed nil keys and the plugin would never load.
+      nowait = key_spec.nowait,
+      silent = key_spec.silent,
+      remap = key_spec.remap,
+      noremap = key_spec.noremap,
+    })
   end
 end
 

diff --git a/lua/zpack/types.lua b/lua/zpack/types.lua
@@ -1,10 +1,16 @@
----@class zpack.KeySpec
----@field [1] string
----@field [2]? string|fun()
----@field remap? boolean
----@field desc? string
+---@class zpack.KeymapOpts
 ---@field mode? string|string[]
+---@field desc? string
+---@field remap? boolean
 ---@field nowait? boolean
+---@field expr? boolean
+---@field silent? boolean
+---@field replace_keycodes? boolean
+
+---@class zpack.KeySpec : zpack.KeymapOpts
+---@field [1] string
+---@field [2]? string|fun()
+---@field noremap? boolean
 
 ---@class zpack.EventSpec
 ---@field event string|string[] Event name(s) to trigger on