feat: provide more capable render API

## Details

Adds a new wrapper `render` API accessible via:
`require('render-markdown').render`, built to integrate with other
plugins, be more user friendly, have sane defaults, and a more powerful
and extensible set of features.

This is meant to (eventually) replace all existing usage of the bare
`ui` module's `update` method. This is currently used by picker plugins
like `fzf-lua` and `snacks.nvim`.

Rather than taking multiple parameters the method accepts a single table
as input, with most fields now being optional, only `buf` is mandatory.
This method supports taking an input configuration as well, allowing
callers of the method to modify rendering settings for buffers owned by
them. The majority of the implementation is based on `snacks.nvim`.

In the future the current logic:

```lua
local UI = require("render-markdown.core.ui")
local State = require("render-markdown.state")
local s = State.get(buf)
s.render_modes = true
s.resolved.modes = true
local wins = vim.fn.win_findbuf(buf)
for _, win in ipairs(wins) do
    UI.update(buf, win, "Snacks", true)
end
```

Can be replaced with the following:

```lua
require("render-markdown").render({
    buf = buf,
    event = "Snacks",
    config = { render_modes = true },
})
```

Where the `event` value can be removed, defaults to `Api`.

> [!NOTE]
> While this is added under the API umbrella it cannot be called via the
> command line, only through lua code.

As part of this change some related changes were made:

- The deferred initialization of several components, like completions
  sources, is moved outside of `manger` and into `state` to handle the
  case where the API is the first buffer being rendered by this plugin.
- Handling preview buffer overrides is now part of the main `config`
  module rather than partially in `state`.

Mostly unrelated changes:

- Added `ensure` helper method to `list` module, improves common
  handling of getting a single value from multiple kinds of input.
- Fix presets in preview override, reduce number of empty tables
  returned by `presets.get`.
- Improve type inference in `resolved` module, still not perfect but
  fewer warnings.
- `max_file_size` is no longer a buffer local configuration, decision
  making on what buffers to attach to should be global, anything more
  granular should use the `ignore` callback instead.

Author: MeanderingProgrammer

README.md

@@ -188,9 +188,6 @@ require('render-markdown').setup({
     -- components. Individual components can be enabled for other modes. Remaining modes will be
     -- unaffected by this plugin.
     render_modes = { 'n', 'c', 't' },
-    -- Maximum file size (in MB) that this plugin will attempt to render.
-    -- File larger than this will effectively be ignored.
-    max_file_size = 10.0,
     -- Milliseconds that must pass before updating marks, updates occur.
     -- within the context of the visible window, not the entire buffer.
     debounce = 100,
@@ -208,6 +205,9 @@ require('render-markdown').setup({
     log_runtime = false,
     -- Filetypes this plugin will run on.
     file_types = { 'markdown' },
+    -- Maximum file size (in MB) that this plugin will attempt to render.
+    -- File larger than this will effectively be ignored.
+    max_file_size = 10.0,
     -- Takes buffer as input, if it returns true this plugin will not attach to the buffer.
     ignore = function()
         return false
@@ -912,9 +912,9 @@ require('render-markdown').setup({
         -- More granular configuration mechanism, allows different aspects of buffers to have their own
         -- behavior. Values default to the top level configuration if no override is provided. Supports
         -- the following fields:
-        --   enabled, render_modes, max_file_size, debounce, anti_conceal, bullet, callout, checkbox,
-        --   code, dash, document, heading, html, indent, inline_highlight, latex, link, padding,
-        --   paragraph, pipe_table, quote, sign, win_options, yaml
+        --   enabled, render_modes, debounce, anti_conceal, bullet, callout, checkbox, code, dash,
+        --   document, heading, html, indent, inline_highlight, latex, link, padding, paragraph,
+        --   pipe_table, quote, sign, win_options, yaml
 
         -- Override for different buflisted values, @see :h 'buflisted'.
         buflisted = {},

doc/render-markdown.txt

@@ -1,4 +1,4 @@
-*render-markdown.txt*      For NVIM v0.11.5      Last change: 2025 November 03
+*render-markdown.txt*      For NVIM v0.11.5      Last change: 2025 November 05
 
 ==============================================================================
 Table of Contents                          *render-markdown-table-of-contents*
@@ -254,9 +254,6 @@ Default Configuration ~
         -- components. Individual components can be enabled for other modes. Remaining modes will be
         -- unaffected by this plugin.
         render_modes = { 'n', 'c', 't' },
-        -- Maximum file size (in MB) that this plugin will attempt to render.
-        -- File larger than this will effectively be ignored.
-        max_file_size = 10.0,
         -- Milliseconds that must pass before updating marks, updates occur.
         -- within the context of the visible window, not the entire buffer.
         debounce = 100,
@@ -274,6 +271,9 @@ Default Configuration ~
         log_runtime = false,
         -- Filetypes this plugin will run on.
         file_types = { 'markdown' },
+        -- Maximum file size (in MB) that this plugin will attempt to render.
+        -- File larger than this will effectively be ignored.
+        max_file_size = 10.0,
         -- Takes buffer as input, if it returns true this plugin will not attach to the buffer.
         ignore = function()
             return false
@@ -978,9 +978,9 @@ Default Configuration ~
             -- More granular configuration mechanism, allows different aspects of buffers to have their own
             -- behavior. Values default to the top level configuration if no override is provided. Supports
             -- the following fields:
-            --   enabled, render_modes, max_file_size, debounce, anti_conceal, bullet, callout, checkbox,
-            --   code, dash, document, heading, html, indent, inline_highlight, latex, link, padding,
-            --   paragraph, pipe_table, quote, sign, win_options, yaml
+            --   enabled, render_modes, debounce, anti_conceal, bullet, callout, checkbox, code, dash,
+            --   document, heading, html, indent, inline_highlight, latex, link, padding, paragraph,
+            --   pipe_table, quote, sign, win_options, yaml
 
             -- Override for different buflisted values, @see :h 'buflisted'.
             buflisted = {},

lua/render-markdown/api.lua

@@ -1,6 +1,31 @@
+---@class render.md.render.Context
+---@field buf integer
+---@field win? integer|integer[]
+---@field event? string
+---@field config? render.md.partial.UserConfig
+
 ---@class render.md.Api
 local M = {}
 
+---@param ctx render.md.render.Context
+function M.render(ctx)
+    local env = require('render-markdown.lib.env')
+    local list = require('render-markdown.lib.list')
+    local state = require('render-markdown.state')
+    local ui = require('render-markdown.core.ui')
+
+    local buf = ctx.buf
+    local wins = list.ensure(ctx.win or env.buf.wins(buf))
+    local event = ctx.event or 'Api'
+
+    state.get(buf, ctx.config)
+    state.attach()
+
+    for _, win in ipairs(wins) do
+        ui.update(buf, win, event, true)
+    end
+end
+
 ---@return boolean
 function M.get()
     return require('render-markdown.state').enabled

lua/render-markdown/core/command.lua

@@ -1,39 +1,36 @@
 local api = require('render-markdown.api')
 
----@class render.md.Command
-local M = {}
-
----@private
-M.name = 'RenderMarkdown'
-
----@private
-M.plugin = 'render-markdown.nvim'
-
----@private
+local name = 'RenderMarkdown'
+local plugin = 'render-markdown.nvim'
 ---@type table<string, type?>
-M.args = {
+local method_args = {
     set = 'boolean',
     set_buf = 'boolean',
 }
+---@type string[]
+local code_only = { 'render' }
+
+---@class render.md.Command
+local M = {}
 
 ---called from plugin directory
 function M.init()
-    vim.api.nvim_create_user_command(M.name, M.command, {
+    vim.api.nvim_create_user_command(name, M.command, {
         nargs = '*',
-        desc = M.plugin .. ' commands',
+        desc = plugin .. ' commands',
         ---@param cmdline string
         ---@param col integer
         ---@return string[]
         complete = function(_, cmdline, col)
-            local line = cmdline:sub(1, col):match('^' .. M.name .. '%s+(.*)$')
+            local line = cmdline:sub(1, col):match('^' .. name .. '%s+(.*)$')
             if line then
                 local fargs = vim.split(line, '%s+')
                 if #fargs == 1 then
-                    return M.matches(fargs[1], vim.tbl_keys(api))
+                    return M.matches(fargs[1], vim.tbl_keys(api), code_only)
                 elseif #fargs == 2 then
-                    local arg = M.args[fargs[1]]
+                    local arg = method_args[fargs[1]]
                     if arg == 'boolean' then
-                        return M.matches(fargs[2], { 'true', 'false' })
+                        return M.matches(fargs[2], { 'true', 'false' }, {})
                     end
                 end
             end
@@ -45,12 +42,15 @@ end
 ---@private
 ---@param prefix string
 ---@param values string[]
+---@param skip string[]
 ---@return string[]
-function M.matches(prefix, values)
+function M.matches(prefix, values, skip)
     local result = {} ---@type string[]
     for _, value in ipairs(values) do
-        if vim.startswith(value, prefix) then
-            result[#result + 1] = value
+        if not vim.tbl_contains(skip, value) then
+            if vim.startswith(value, prefix) then
+                result[#result + 1] = value
+            end
         end
     end
     return result
@@ -61,7 +61,7 @@ end
 function M.command(args)
     local err = M.run(args.fargs)
     if err then
-        vim.notify(('%s: %s'):format(M.plugin, err), vim.log.levels.ERROR)
+        vim.notify(('%s: %s'):format(plugin, err), vim.log.levels.ERROR)
     end
 end
 
@@ -72,23 +72,23 @@ function M.run(fargs)
     if #fargs > 2 then
         return ('invalid # arguments - %d'):format(#fargs)
     end
-    local name = fargs[1] or 'enable'
-    local command = api[name] --[[@as fun(enable?: boolean)?]]
-    if not command then
-        return ('invalid command - %s'):format(name)
+    local method = fargs[1] or 'enable'
+    local command = api[method] --[[@as fun(enable?: boolean)?]]
+    if not command or vim.tbl_contains(code_only, method) then
+        return ('invalid command - %s'):format(method)
     end
     if #fargs == 2 then
-        local arg = M.args[name]
+        local arg = method_args[method]
         local value = fargs[2]
         if not arg then
-            return ('no arguments allowed - %s'):format(name)
+            return ('no arguments allowed - %s'):format(method)
         elseif arg == 'boolean' then
             if value == 'true' then
                 command(true)
             elseif value == 'false' then
                 command(false)
             else
-                return ('invalid argument - %s(%s)'):format(name, value)
+                return ('invalid argument - %s(%s)'):format(method, value)
             end
         else
             return ('bug unhandled type - %s'):format(arg)

lua/render-markdown/core/manager.lua

@@ -86,16 +86,7 @@ function M.attach(buf)
 
     local config = state.get(buf)
     state.on.attach({ buf = buf })
-    require('render-markdown.core.ts').init()
-    if state.completions.lsp.enabled then
-        require('render-markdown.integ.lsp').init()
-    elseif state.completions.blink.enabled then
-        require('render-markdown.integ.blink').init()
-    elseif state.completions.coq.enabled then
-        require('render-markdown.integ.coq').init()
-    else
-        require('render-markdown.integ.cmp').init()
-    end
+    state.attach()
 
     local events = {
         'BufWinEnter',
@@ -163,7 +154,7 @@ function M.should_attach(buf)
     end
 
     local file_size = env.file_size_mb(buf)
-    local max_file_size = state.get(buf).max_file_size
+    local max_file_size = state.max_file_size
     if file_size > max_file_size then
         local reason = ('%f > %f'):format(file_size, max_file_size)
         log.attach(buf, 'skip', 'file size', reason)

lua/render-markdown/core/ts.lua

@@ -19,7 +19,7 @@ function M.setup()
     end
 end
 
----called from manager on buffer attach
+---called from state on attach
 function M.init()
     if M.initialized then
         return

lua/render-markdown/health.lua

@@ -6,7 +6,7 @@ local state = require('render-markdown.state')
 local M = {}
 
 ---@private
-M.version = '8.9.13'
+M.version = '8.9.14'
 
 function M.check()
     M.start('versions')

lua/render-markdown/init.lua

@@ -8,6 +8,7 @@ local M = {}
 ---@field log_level render.md.log.Level
 ---@field log_runtime boolean
 ---@field file_types string[]
+---@field max_file_size number
 ---@field ignore fun(buf: integer): boolean
 ---@field nested boolean
 ---@field change_events string[]
@@ -20,7 +21,6 @@ local M = {}
 ---@field custom_handlers table<string, render.md.Handler>
 
 ---@class (exact) render.md.partial.Config: render.md.base.Config
----@field max_file_size number
 ---@field debounce integer
 ---@field anti_conceal render.md.anti.conceal.Config
 ---@field bullet render.md.bullet.Config
@@ -55,9 +55,6 @@ M.default = {
     -- components. Individual components can be enabled for other modes. Remaining modes will be
     -- unaffected by this plugin.
     render_modes = { 'n', 'c', 't' },
-    -- Maximum file size (in MB) that this plugin will attempt to render.
-    -- File larger than this will effectively be ignored.
-    max_file_size = 10.0,
     -- Milliseconds that must pass before updating marks, updates occur.
     -- within the context of the visible window, not the entire buffer.
     debounce = 100,
@@ -75,6 +72,9 @@ M.default = {
     log_runtime = false,
     -- Filetypes this plugin will run on.
     file_types = { 'markdown' },
+    -- Maximum file size (in MB) that this plugin will attempt to render.
+    -- File larger than this will effectively be ignored.
+    max_file_size = 10.0,
     -- Takes buffer as input, if it returns true this plugin will not attach to the buffer.
     ignore = function()
         return false

lua/render-markdown/integ/blink.lua

@@ -9,7 +9,7 @@ Source.__index = Source
 ---@type boolean
 Source.initialized = false
 
----called from manager on buffer attach
+---called from state on attach
 function Source.init()
     if Source.initialized then
         return

lua/render-markdown/integ/cmp.lua

@@ -36,7 +36,7 @@ local M = {}
 ---@type boolean
 M.initialized = false
 
----called from manager on buffer attach
+---called from state on attach
 function M.init()
     if M.initialized then
         return