ci: scripts

Problem: the help file listed compile as the default subcommand, still
included the stop subcommand, omitted the reload provider field, and
had a misleading claim about shipping with zero defaults.

Solution: make toggle the default in the commands section, remove stop
from subcommands, add reload to provider fields, fix the introduction
text, reorder API entries to match new primacy, and add an output path
override example addressing #26/#27.

.luarc.json

@@ -2,7 +2,13 @@
   "runtime.version": "LuaJIT",
   "runtime.path": ["lua/?.lua", "lua/?/init.lua"],
   "diagnostics.globals": ["vim", "jit"],
-  "workspace.library": ["$VIMRUNTIME/lua", "${3rd}/luv/library"],
+  "workspace.library": [
+    "$VIMRUNTIME/lua",
+    "${3rd}/luv/library",
+    "${3rd}/busted/library",
+    "${3rd}/luassert/library"
+  ],
   "workspace.checkThirdParty": false,
+  "workspace.ignoreDir": [".direnv"],
   "completion.callSnippet": "Replace"
 }

.styluaignore

@@ -0,0 +1 @@
+.direnv/

doc/preview.nvim.txt

@@ -10,8 +10,8 @@ preview.nvim is an extensible framework for compiling documents asynchronously
 in Neovim. It provides a unified interface for any compilation workflow —
 LaTeX, Typst, Markdown, or anything else with a CLI compiler.
 
-The plugin ships with zero provider defaults. Users must explicitly configure
+The plugin ships with opt-in presets for common tools (Typst, LaTeX, Pandoc)
-their compiler commands. preview.nvim is purely an orchestration framework.
+and supports fully custom providers. See |preview.nvim-presets|.
 
 ==============================================================================
 REQUIREMENTS                                          *preview.nvim-requirements*
@@ -93,6 +93,14 @@ Provider fields:~
                                        |vim.ui.open()|. A string[] is run as
                                        a command with the output path appended.
 
+  `reload`           boolean|string[]|function
+                                       Reload the output after recompilation.
+                                       `true` uses a built-in SSE server for
+                                       HTML files. A string[] is run as a
+                                       command. If a function, receives a
+                                       |preview.Context| and returns a
+                                       string[].
+
                                                         *preview.Context*
 Context fields:~
 
@@ -115,6 +123,17 @@ Example overriding a preset field:~
     })
 <
 
+Example overriding the output path (e.g. latexmk `$out_dir`):~
+>lua
+    require('preview').setup({
+      latex = {
+        output = function(ctx)
+          return 'build/' .. vim.fn.fnamemodify(ctx.file, ':t:r') .. '.pdf'
+        end,
+      },
+    })
+<
+
 Example with a fully custom provider (key is not a preset name):~
 >lua
     require('preview').setup({
@@ -160,30 +179,30 @@ COMMANDS                                              *preview.nvim-commands*
 
     Subcommands:~
 
-    `compile`    Compile the current buffer (default if omitted).
+    `toggle`     Toggle auto-compile on save (default if omitted).
-    `stop`       Kill active compilation for the current buffer.
+    `compile`    One-shot compile of the current buffer.
     `clean`      Run the provider's clean command.
-    `toggle`     Toggle auto-compile on save for the current buffer.
     `open`       Open the last compiled output without recompiling.
     `status`     Echo compilation status (idle, compiling, watching).
 
 ==============================================================================
 API                                                        *preview.nvim-api*
 
-preview.compile({bufnr?})                                *preview.compile()*
-    Compile the document in the given buffer (default: current).
-
-preview.stop({bufnr?})                                      *preview.stop()*
-    Kill the active compilation process for the buffer.
-
-preview.clean({bufnr?})                                    *preview.clean()*
-    Run the provider's clean command for the buffer.
-
 preview.toggle({bufnr?})                                  *preview.toggle()*
     Toggle auto-compile for the buffer. When enabled, the buffer is
     immediately compiled and automatically recompiled on each save
     (`BufWritePost`). Call again to stop.
 
+preview.compile({bufnr?})                                *preview.compile()*
+    One-shot compile the document in the given buffer (default: current).
+
+preview.stop({bufnr?})                                      *preview.stop()*
+    Kill the active compilation process for the buffer. Programmatic
+    escape hatch — not exposed as a subcommand.
+
+preview.clean({bufnr?})                                    *preview.clean()*
+    Run the provider's clean command for the buffer.
+
 preview.open({bufnr?})                                      *preview.open()*
     Open the last compiled output for the buffer without recompiling.
 

flake.nix

@@ -16,6 +16,8 @@
       forEachSystem = f: nixpkgs.lib.genAttrs (import systems) (system: f nixpkgs.legacyPackages.${system});
     in
     {
+      formatter = forEachSystem (pkgs: pkgs.nixfmt-tree);
+
       devShells = forEachSystem (pkgs: {
         default = pkgs.mkShell {
           packages = [

lua/preview/commands.lua

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

lua/preview/init.lua

@@ -39,10 +39,10 @@
 
 ---@class preview
 ---@field setup fun(opts?: table)
----@field build fun(bufnr?: integer)
+---@field compile fun(bufnr?: integer)
 ---@field stop fun(bufnr?: integer)
 ---@field clean fun(bufnr?: integer)
----@field watch fun(bufnr?: integer)
+---@field toggle fun(bufnr?: integer)
 ---@field open fun(bufnr?: integer)
 ---@field status fun(bufnr?: integer): preview.Status
 ---@field statusline fun(bufnr?: integer): string
@@ -144,7 +144,7 @@ function M.build_context(bufnr)
 end
 
 ---@param bufnr? integer
-function M.build(bufnr)
+function M.compile(bufnr)
   bufnr = bufnr or vim.api.nvim_get_current_buf()
   local name = M.resolve_provider(bufnr)
   if not name then
@@ -176,7 +176,7 @@ function M.clean(bufnr)
 end
 
 ---@param bufnr? integer
-function M.watch(bufnr)
+function M.toggle(bufnr)
   bufnr = bufnr or vim.api.nvim_get_current_buf()
   local name = M.resolve_provider(bufnr)
   if not name then

scripts/ci.sh

@@ -0,0 +1,10 @@
+#!/bin/sh
+set -eu
+
+nix develop --command stylua --check .
+git ls-files '*.lua' | xargs nix develop --command selene --display-style quiet
+nix develop --command prettier --check .
+nix fmt
+git diff --exit-code -- '*.nix'
+nix develop --command lua-language-server --check . --checklevel=Warning
+nix develop --command busted

spec/commands_spec.lua

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