From 62961c854168cec9ae30e52c3e1b2e914248f1f2 Mon Sep 17 00:00:00 2001
From: Barrett Ruth <62671086+barrettruth@users.noreply.github.com>
Date: Tue, 3 Mar 2026 16:41:47 -0500
Subject: [PATCH] feat: unified reload field for live-preview (SSE +
 long-running watch) (#19)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* 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.
---
 lua/preview/commands.lua |  12 ++--
 lua/preview/compiler.lua | 138 +++++++++++++++++++++++++++++++++++++--
 lua/preview/init.lua     |  11 ++--
 lua/preview/presets.lua  |   6 ++
 lua/preview/reload.lua   | 108 ++++++++++++++++++++++++++++++
 spec/commands_spec.lua   |   6 +-
 spec/presets_spec.lua    |  21 ++++++
 spec/reload_spec.lua     |  58 ++++++++++++++++
 8 files changed, 340 insertions(+), 20 deletions(-)
 create mode 100644 lua/preview/reload.lua
 create mode 100644 spec/reload_spec.lua

diff --git a/lua/preview/commands.lua b/lua/preview/commands.lua
index 2c52c5a..c91f4de 100644
--- a/lua/preview/commands.lua
+++ b/lua/preview/commands.lua
@@ -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
 
diff --git a/lua/preview/compiler.lua b/lua/preview/compiler.lua
index eca9f4d..e19cbf0 100644
--- a/lua/preview/compiler.lua
+++ b/lua/preview/compiler.lua
@@ -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,
     }
diff --git a/lua/preview/init.lua b/lua/preview/init.lua
index 2bee03a..bbf70f1 100644
--- a/lua/preview/init.lua
+++ b/lua/preview/init.lua
@@ -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
diff --git a/lua/preview/presets.lua b/lua/preview/presets.lua
index c1de0df..fc20f89 100644
--- a/lua/preview/presets.lua
+++ b/lua/preview/presets.lua
@@ -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
diff --git a/lua/preview/reload.lua b/lua/preview/reload.lua
new file mode 100644
index 0000000..fd64309
--- /dev/null
+++ b/lua/preview/reload.lua
@@ -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
diff --git a/spec/commands_spec.lua b/spec/commands_spec.lua
index 931174f..32da224 100644
--- a/spec/commands_spec.lua
+++ b/spec/commands_spec.lua
@@ -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)
diff --git a/spec/presets_spec.lua b/spec/presets_spec.lua
index 6eaa613..8085a3c 100644
--- a/spec/presets_spec.lua
+++ b/spec/presets_spec.lua
@@ -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):',
diff --git a/spec/reload_spec.lua b/spec/reload_spec.lua
new file mode 100644
index 0000000..12b7aac
--- /dev/null
+++ b/spec/reload_spec.lua
@@ -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)