barrett/preview.nvim
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 5

feat: unified reload field for live-preview (SSE + long-running watch) (#19)

Browse source 
* feat(reload): add SSE live-reload server module

Problem: HTML output from pandoc has no live-reload; the browser must
be refreshed manually after each compile.

Solution: add lua/preview/reload.lua — a minimal SSE-only TCP server.
start() binds 127.0.0.1:5554 and keeps EventSource connections alive;
broadcast() pushes a reload event to all clients; inject() appends an
EventSource script before </body> (or at EOF) on every compile so
pandoc overwrites do not lose the tag.

* refactor(presets): add reload field, remove synctex field

Problem: the synctex field only handled PDF forward search and left
HTML live-preview and typst watch mode unsupported.

Solution: add reload = function(ctx) returning { 'typst', 'watch',
ctx.file } to typst (long-running watch mode), reload = true to
markdown and github (SSE push after each pandoc compile), and remove
synctex = true from latex (the -synctex=1 arg in latex.args remains
for .synctex.gz generation).

* refactor(init): replace synctex field and validation with reload

Problem: ProviderConfig still declared synctex and validated it, but
the field is being dropped in favour of the general-purpose reload.

Solution: replace the synctex annotation and vim.validate call with the
reload field, accepting boolean | string[] | function.

* feat(compiler): support long-running watch processes and SSE reload

Problem: compile() only supports one-shot invocations, requiring a
BufWritePost autocmd for watch mode and leaving HTML without live-
reload.

Solution: resolve_reload_cmd() maps provider.reload (function or table)
to a command; when present, compile() spawns it as a long-running
process instead of building a one-shot cmd from provider.cmd + args.
toggle() detects long-running providers and toggles the process
directly instead of registering a BufWritePost autocmd. When
reload = true and output is .html, the SSE server is invoked after
each successful compile. status() reports is_reload processes as
watching, not compiling. stop_all() also stops the SSE server.

* fix(compiler): format is_longrunning and annotate is_reload field

Problem: stylua required is_longrunning to be on one line; lua-ls
warned about undefined field is_reload on preview.Process.

Solution: inline the boolean expression and add is_reload? to the
preview.Process annotation.

* refactor: rename compile/toggle commands to build/watch

Problem: `compile` and `toggle` are accurate but unintuitive — `compile`
sounds academic and `toggle` says nothing about what it toggles.

Solution: rename the public API and `:Preview` subcommands to `build`
(one-shot) and `watch` (live preview). Internal compiler functions are
unchanged. No aliases for old names — clean break.
This commit is contained in:
Barrett Ruth 2026-03-03 16:41:47 -05:00 • committed by GitHub
parent bce3cec0e6
commit 62961c8541
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
8 changed files with 340 additions and 20 deletions
Download patch file Download diff file Expand all files Collapse all files

12
lua/preview/commands.lua
View file

@ -1,8 +1,8 @@
local M = {}
local handlers = {
compile = function()
require('preview').compile()
build = function()
require('preview').build()
end,
stop = function()
require('preview').stop()
@ -10,8 +10,8 @@ local handlers = {
clean = function()
require('preview').clean()
end,
toggle = function()
require('preview').toggle()
watch = function()
require('preview').watch()
end,
open = function()
require('preview').open()
@ -33,7 +33,7 @@ local handlers = {
---@param args string
local function dispatch(args)
local subcmd = args ~= '' and args or 'compile'
local subcmd = args ~= '' and args or 'build'
local handler = handlers[subcmd]
if handler then
handler()
@ -58,7 +58,7 @@ function M.setup()
complete = function(lead)
return complete(lead)
end,
desc = 'Compile, stop, clean, toggle, open, or check status of document preview',
desc = 'Build, stop, clean, watch, open, or check status of document preview',
})
end

138
lua/preview/compiler.lua
View file

@ -39,6 +39,18 @@ local function eval_string(val, ctx)
return val
end
---@param provider preview.ProviderConfig
---@param ctx preview.Context
---@return string[]?
local function resolve_reload_cmd(provider, ctx)
if type(provider.reload) == 'function' then
return provider.reload(ctx)
elseif type(provider.reload) == 'table' then
return vim.list_extend({}, provider.reload)
end
return nil
end
---@param bufnr integer
---@param name string
---@param provider preview.ProviderConfig
@ -60,11 +72,6 @@ function M.compile(bufnr, name, provider, ctx)
local resolved_ctx = vim.tbl_extend('force', ctx, { output = output_file })
local cmd = vim.list_extend({}, provider.cmd)
if provider.args then
vim.list_extend(cmd, eval_list(provider.args, resolved_ctx))
end
local cwd = ctx.root
if provider.cwd then
cwd = eval_string(provider.cwd, resolved_ctx)
@ -74,6 +81,103 @@ function M.compile(bufnr, name, provider, ctx)
last_output[bufnr] = output_file
end
local reload_cmd = resolve_reload_cmd(provider, resolved_ctx)
if reload_cmd then
log.dbg(
'starting long-running process for buffer %d with provider "%s": %s',
bufnr,
name,
table.concat(reload_cmd, ' ')
)
local obj = vim.system(
reload_cmd,
{
cwd = cwd,
env = provider.env,
},
vim.schedule_wrap(function(result)
active[bufnr] = nil
if not vim.api.nvim_buf_is_valid(bufnr) then
return
end
if result.code ~= 0 then
log.dbg('long-running process failed for buffer %d (exit code %d)', bufnr, result.code)
local errors_mode = provider.errors
if errors_mode == nil then
errors_mode = 'diagnostic'
end
if provider.error_parser and errors_mode then
local output = (result.stdout or '') .. (result.stderr or '')
if errors_mode == 'diagnostic' then
diagnostic.set(bufnr, name, provider.error_parser, output, ctx)
elseif errors_mode == 'quickfix' then
local ok, diagnostics = pcall(provider.error_parser, output, ctx)
if ok and diagnostics and #diagnostics > 0 then
local items = {}
for _, d in ipairs(diagnostics) do
table.insert(items, {
bufnr = bufnr,
lnum = d.lnum + 1,
col = d.col + 1,
text = d.message,
type = d.severity == vim.diagnostic.severity.WARN and 'W' or 'E',
})
end
vim.fn.setqflist(items, 'r')
vim.cmd('copen')
end
end
end
vim.api.nvim_exec_autocmds('User', {
pattern = 'PreviewCompileFailed',
data = {
bufnr = bufnr,
provider = name,
code = result.code,
stderr = result.stderr or '',
},
})
end
end)
)
if provider.open and not opened[bufnr] and output_file ~= '' then
if provider.open == true then
vim.ui.open(output_file)
elseif type(provider.open) == 'table' then
local open_cmd = vim.list_extend({}, provider.open)
table.insert(open_cmd, output_file)
vim.system(open_cmd)
end
opened[bufnr] = true
end
active[bufnr] = { obj = obj, provider = name, output_file = output_file, is_reload = true }
vim.api.nvim_create_autocmd('BufWipeout', {
buffer = bufnr,
once = true,
callback = function()
M.stop(bufnr)
last_output[bufnr] = nil
end,
})
vim.api.nvim_exec_autocmds('User', {
pattern = 'PreviewCompileStarted',
data = { bufnr = bufnr, provider = name },
})
return
end
local cmd = vim.list_extend({}, provider.cmd)
if provider.args then
vim.list_extend(cmd, eval_list(provider.args, resolved_ctx))
end
log.dbg('compiling buffer %d with provider "%s": %s', bufnr, name, table.concat(cmd, ' '))
local obj = vim.system(
@ -104,6 +208,12 @@ function M.compile(bufnr, name, provider, ctx)
pattern = 'PreviewCompileSuccess',
data = { bufnr = bufnr, provider = name, output = output_file },
})
if provider.reload == true and output_file:match('%.html$') then
local r = require('preview.reload')
r.start()
r.inject(output_file)
r.broadcast()
end
if provider.open and not opened[bufnr] and output_file ~= '' then
if provider.open == true then
vim.ui.open(output_file)
@ -198,6 +308,7 @@ function M.stop_all()
for bufnr, _ in pairs(watching) do
M.unwatch(bufnr)
end
require('preview.reload').stop()
end
---@param bufnr integer
@ -205,6 +316,19 @@ end
---@param provider preview.ProviderConfig
---@param ctx_builder fun(bufnr: integer): preview.Context
function M.toggle(bufnr, name, provider, ctx_builder)
local is_longrunning = type(provider.reload) == 'table' or type(provider.reload) == 'function'
if is_longrunning then
if active[bufnr] then
M.stop(bufnr)
vim.notify('[preview.nvim]: watching stopped', vim.log.levels.INFO)
else
M.compile(bufnr, name, provider, ctx_builder(bufnr))
vim.notify('[preview.nvim]: watching with "' .. name .. '"', vim.log.levels.INFO)
end
return
end
if watching[bufnr] then
M.unwatch(bufnr)
vim.notify('[preview.nvim]: watching stopped', vim.log.levels.INFO)
@ -313,8 +437,8 @@ function M.status(bufnr)
local proc = active[bufnr]
if proc then
return {
compiling = true,
watching = watching[bufnr] ~= nil,
compiling = not proc.is_reload,
watching = watching[bufnr] ~= nil or proc.is_reload == true,
provider = proc.provider,
output_file = proc.output_file,
}

11
lua/preview/init.lua
View file

@ -9,6 +9,7 @@
---@field errors? false|'diagnostic'|'quickfix'
---@field clean? string[]|fun(ctx: preview.Context): string[]
---@field open? boolean|string[]
---@field reload? boolean|string[]|fun(ctx: preview.Context): string[]
---@class preview.Config
---@field debug boolean|string
@ -34,13 +35,14 @@
---@field obj table
---@field provider string
---@field output_file string
---@field is_reload? boolean
---@class preview
---@field setup fun(opts?: table)
---@field compile fun(bufnr?: integer)
---@field build fun(bufnr?: integer)
---@field stop fun(bufnr?: integer)
---@field clean fun(bufnr?: integer)
---@field toggle fun(bufnr?: integer)
---@field watch fun(bufnr?: integer)
---@field open fun(bufnr?: integer)
---@field status fun(bufnr?: integer): preview.Status
---@field statusline fun(bufnr?: integer): string
@ -98,6 +100,7 @@ function M.setup(opts)
return x == nil or x == false or x == 'diagnostic' or x == 'quickfix'
end, 'false, "diagnostic", or "quickfix"')
vim.validate(prefix .. '.open', provider.open, { 'boolean', 'table' }, true)
vim.validate(prefix .. '.reload', provider.reload, { 'boolean', 'table', 'function' }, true)
end
config = vim.tbl_deep_extend('force', default_config, {
@ -141,7 +144,7 @@ function M.build_context(bufnr)
end
---@param bufnr? integer
function M.compile(bufnr)
function M.build(bufnr)
bufnr = bufnr or vim.api.nvim_get_current_buf()
local name = M.resolve_provider(bufnr)
if not name then
@ -173,7 +176,7 @@ function M.clean(bufnr)
end
---@param bufnr? integer
function M.toggle(bufnr)
function M.watch(bufnr)
bufnr = bufnr or vim.api.nvim_get_current_buf()
local name = M.resolve_provider(bufnr)
if not name then

6
lua/preview/presets.lua
View file

@ -107,6 +107,9 @@ M.typst = {
return parse_typst(output)
end,
open = true,
reload = function(ctx)
return { 'typst', 'watch', ctx.file }
end,
}
---@type preview.ProviderConfig
@ -117,6 +120,7 @@ M.latex = {
return {
'-pdf',
'-interaction=nonstopmode',
'-synctex=1',
'-pdflatex=pdflatex -file-line-error -interaction=nonstopmode %O %S',
ctx.file,
}
@ -150,6 +154,7 @@ M.markdown = {
return { 'rm', '-f', (ctx.file:gsub('%.md$', '.html')) }
end,
open = true,
reload = true,
}
---@type preview.ProviderConfig
@ -179,6 +184,7 @@ M.github = {
return { 'rm', '-f', (ctx.file:gsub('%.md$', '.html')) }
end,
open = true,
reload = true,
}
return M

108
lua/preview/reload.lua Normal file
View file

@ -0,0 +1,108 @@
local M = {}
local PORT = 5554
local server_handle = nil
local clients = {}
local function make_script(port)
return '<script>(function(){'
.. 'var es=new EventSource("http://localhost:'
.. tostring(port)
.. '/__live/events");'
.. 'es.addEventListener("reload",function(){location.reload();});'
.. '})()</script>'
end
function M.start(port)
port = port or PORT
if server_handle then
return
end
local server = vim.uv.new_tcp()
server:bind('127.0.0.1', port)
server:listen(128, function(err)
if err then
return
end
local client = vim.uv.new_tcp()
server:accept(client)
local buf = ''
client:read_start(function(read_err, data)
if read_err or not data then
if not client:is_closing() then
client:close()
end
return
end
buf = buf .. data
if buf:find('\r\n\r\n') or buf:find('\n\n') then
client:read_stop()
local first_line = buf:match('^([^\r\n]+)')
if first_line and first_line:find('/__live/events', 1, true) then
local response = 'HTTP/1.1 200 OK\r\n'
.. 'Content-Type: text/event-stream\r\n'
.. 'Cache-Control: no-cache\r\n'
.. 'Access-Control-Allow-Origin: *\r\n'
.. '\r\n'
client:write(response)
table.insert(clients, client)
else
client:close()
end
end
end)
end)
server_handle = server
end
function M.stop()
for _, c in ipairs(clients) do
if not c:is_closing() then
c:close()
end
end
clients = {}
if server_handle then
server_handle:close()
server_handle = nil
end
end
function M.broadcast()
local event = 'event: reload\ndata: {}\n\n'
local alive = {}
for _, c in ipairs(clients) do
if not c:is_closing() then
local ok = pcall(function()
c:write(event)
end)
if ok then
table.insert(alive, c)
end
end
end
clients = alive
end
function M.inject(path, port)
port = port or PORT
local f = io.open(path, 'r')
if not f then
return
end
local content = f:read('*a')
f:close()
local script = make_script(port)
local new_content, n = content:gsub('</body>', script .. '\n</body>', 1)
if n == 0 then
new_content = content .. '\n' .. script
end
local fw = io.open(path, 'w')
if not fw then
return
end
fw:write(new_content)
fw:close()
end
return M

6
spec/commands_spec.lua
View file

@ -17,7 +17,7 @@ describe('commands', function()
it('does not error on :Preview with no provider', function()
require('preview.commands').setup()
assert.has_no.errors(function()
vim.cmd('Preview compile')
vim.cmd('Preview build')
end)
end)
@ -42,10 +42,10 @@ describe('commands', function()
end)
end)
it('does not error on :Preview toggle with no provider', function()
it('does not error on :Preview watch with no provider', function()
require('preview.commands').setup()
assert.has_no.errors(function()
vim.cmd('Preview toggle')
vim.cmd('Preview watch')
end)
end)
end)

21
spec/presets_spec.lua
View file

@ -37,6 +37,18 @@ describe('presets', function()
assert.is_true(presets.typst.open)
end)
it('has reload as a function', function()
assert.is_function(presets.typst.reload)
end)
it('reload returns typst watch command', function()
local result = presets.typst.reload(ctx)
assert.is_table(result)
assert.are.equal('typst', result[1])
assert.are.equal('watch', result[2])
assert.are.equal(ctx.file, result[3])
end)
it('parses errors from stderr', function()
local stderr = table.concat({
'main.typ:5:23: error: unexpected token',
@ -84,6 +96,7 @@ describe('presets', function()
assert.are.same({
'-pdf',
'-interaction=nonstopmode',
'-synctex=1',
'-pdflatex=pdflatex -file-line-error -interaction=nonstopmode %O %S',
'/tmp/document.tex',
}, args)
@ -186,6 +199,10 @@ describe('presets', function()
assert.is_true(presets.markdown.open)
end)
it('has reload enabled for SSE', function()
assert.is_true(presets.markdown.reload)
end)
it('parses YAML metadata errors with multiline message', function()
local output = table.concat({
'Error parsing YAML metadata at "/tmp/test.md" (line 1, column 1):',
@ -290,6 +307,10 @@ describe('presets', function()
assert.is_true(presets.github.open)
end)
it('has reload enabled for SSE', function()
assert.is_true(presets.github.reload)
end)
it('parses YAML metadata errors with multiline message', function()
local output = table.concat({
'Error parsing YAML metadata at "/tmp/test.md" (line 1, column 1):',

58
spec/reload_spec.lua Normal file
View file

@ -0,0 +1,58 @@
describe('reload', function()
local reload
before_each(function()
package.loaded['preview.reload'] = nil
reload = require('preview.reload')
end)
after_each(function()
reload.stop()
end)
describe('inject', function()
it('injects script before </body>', function()
local path = os.tmpname()
local f = io.open(path, 'w')
f:write('<html><body><p>hello</p></body></html>')
f:close()
reload.inject(path)
local fr = io.open(path, 'r')
local content = fr:read('*a')
fr:close()
os.remove(path)
assert.is_truthy(content:find('EventSource', 1, true))
local script_pos = content:find('EventSource', 1, true)
local body_pos = content:find('</body>', 1, true)
assert.is_truthy(body_pos)
assert.is_true(script_pos < body_pos)
end)
it('appends script when no </body>', function()
local path = os.tmpname()
local f = io.open(path, 'w')
f:write('<html><p>hello</p></html>')
f:close()
reload.inject(path)
local fr = io.open(path, 'r')
local content = fr:read('*a')
fr:close()
os.remove(path)
assert.is_truthy(content:find('EventSource', 1, true))
end)
end)
describe('broadcast', function()
it('does not error with no clients', function()
assert.has_no.errors(function()
reload.broadcast()
end)
end)
end)
end)