Skip to content

Types

Records and string-literal unions referenced from the namespace pages. Generated from #[derive(LuaOpts)] / #[derive(LuaAlias)] sites in Rust and from ---@class / ---@alias blocks in the bundled Lua modules.

Classes

smelt.Reg

Registration handle returned by every reactive-subscription API. :remove() undoes the binding (frees the underlying callback / cancels the timer / drops the subscription). Idempotent: subsequent calls return false.

Field Type Required Description
remove fun(): boolean yes Undo the registration. Returns true the first time; false on subsequent calls or when the underlying target is already gone.

smelt.buf.Buf

Buffer handle returned by smelt.buf.new(opts?). Setter methods return the same handle for chaining.

Field Type Required Description
source fun(s: string?): any yes Read or write the buffer's full source. Without arg returns the source string (or nil if the buffer is gone). With arg replaces the source and returns the handle for chaining. On the built-in prompt buffer, this routes through smelt.prompt.set_text semantics so cursor, undo, attachments, and completer state stay coherent.
lines fun(arr: string[]?): any yes Read or write the buffer as a string array. Without arg returns the lines; with arg replaces all lines and returns the handle for chaining. On the built-in prompt buffer, writes are joined with \n and installed through smelt.prompt.set_text semantics.
line fun(idx: integer): string? yes Read a single line by 1-based index. nil if out of range or the buffer is gone.
styled fun(lines: table): smelt.buf.Buf yes Replace the buffer with a list of styled lines ({ { text, style?, syntax? }, ... }). Returns the handle for chaining.
readonly fun(val: boolean?): any yes Read or write the readonly flag. With arg, returns the handle for chaining.
mark fun(ns: integer, row: integer, col: integer, opts: smelt.buf.MarkOpts?): integer yes Place a highlight or virt-text extmark at (row, col). Row is 1-based; col and opts.end_col are byte offsets into the line, the same unit as #s, string.find, and string.sub. Off-boundary bytes snap to the nearest UTF-8 char boundary; out-of-range bytes clamp to the line end. Returns the new extmark id. Allocate ns via smelt.ns(name).
clear_ns fun(ns: integer, start: integer?, end_: integer?): smelt.buf.Buf yes Drop every extmark owned by ns between [start, end) (1-based, exclusive end). Defaults clear the whole buffer. Returns the handle for chaining.

smelt.buf.MarkOpts

Options accepted by buf:mark(ns, row, col, opts). Mirrors a useful subset of nvim_buf_set_extmark's keyset; pick highlight or virt-text fields, not both.

Field Type Required Description
id integer Retarget an existing mark by id instead of allocating a new one.
end_row integer 1-based end row (inclusive). nil keeps the mark single-line.
end_col integer End byte offset for highlight ranges (exclusive). Same unit as col - bytes into the line, matching #s and string.find.
priority integer Higher-priority marks paint over lower-priority ones.
right_gravity boolean If true, the mark sticks with text inserted to its right.
end_right_gravity boolean Right-gravity flag for the end-of-range cursor.
hl_group string Theme group whose style is applied as the highlight base.
fg string | integer[] | { ansi: integer } | { rgb: integer[] } Foreground override. Either a theme group name (string) or a direct RGB triple { r, g, b }. Takes precedence over hl_group.
bg string | integer[] | { ansi: integer } | { rgb: integer[] } Background override. Either a theme group name (string) or a direct RGB triple { r, g, b }. Takes precedence over hl_group.
bold boolean Force-bold the highlight.
dim boolean Force-dim the highlight.
italic boolean Force-italic the highlight.
reverse boolean Force reverse-video on the highlight.
hl_eol boolean Extend the highlight past the last column to fill the EOL.
on_cursor_row boolean Paint only on the window's cursor row. Decorates the selected list item without re-rendering on every move.
virt_text string Virtual-text chunk to render alongside the line.
virt_text_hl string Theme group applied to the virt-text chunk. fg, bg, and text attributes below can further override it.
virt_text_pos smelt.buf.VirtTextPos Where the virt-text appears relative to the line.
selectable boolean If false, the range is skipped by mouse selection.
yank_as string Override the yanked string when the user copies this range.

smelt.buf.NewOpts

Options for smelt.buf.new(opts?). Named buffers survive /reload; anonymous buffers are reaped.

Field Type Required Description
name string Stable name used to reuse this buffer across /reload.
readonly boolean When true, UI editing operations cannot mutate the buffer.
editable boolean Enable undo history for plugin-managed editable buffers.
undo integer Undo history entry limit when editable = true (defaults to 100).
mode "plain"|"markdown"|"md"|"code" Attach a parser-backed renderer to the buffer.
lang string Syntax language token required by mode = "code".
diff_base string When mode = "code", render the buffer source as an inline diff against this base text.

smelt.builtins.Selector

Selector accepted by smelt.builtins.disable / enable. Each list is a set of bundled module short-names - see the table below for the smelt.<dotted> form each one expands to. | field | expansion | |---|---| | tools = { "web_search" } | smelt.tools.web_search | | commands = { "compact" } | smelt.commands.compact | | plugins = { "predict" } | smelt.plugins.predict | | dialogs = { "resume" } | smelt.dialogs.resume | | modules = { "smelt.foo.bar" } | passed through verbatim |

Field Type Required Description
tools string[] Short tool names under smelt.tools.* (e.g. "bash", "web_search").
commands string[] Short command names under smelt.commands.* (e.g. "compact").
plugins string[] Short plugin names under smelt.plugins.* (e.g. "predict").
dialogs string[] Short dialog names under smelt.dialogs.* (e.g. "resume").
modules string[] Fully-qualified smelt.<dotted> module names, passed through verbatim.

smelt.cli.RegisterFlagOpts

Flag specification accepted by smelt.cli.register_flag.

Field Type Required Description
name string yes Flag name without --. Used as the key for smelt.cli.get.
kind smelt.cli.FlagKind yes "boolean" (default false), "string", or "integer".
default any Default value when the flag is absent from argv. Type must match kind.
short string Short flag character (e.g. "u" for -u). Optional.
long string Long flag name override. Defaults to name when absent.
description string Human-readable description for --help.
value_optional boolean String/Integer flags only. When true, the flag may be passed without a value (smelt -r valid alongside smelt -r abc); the value-less form yields "" for String and 0 for Integer. Defaults to false. Ignored for Boolean flags.

smelt.cmd.RegisterOpts

Options accepted by smelt.cmd.register.

Field Type Required Description
desc string Human-readable description shown in /help and the slash-command picker.
args string[] Positional argument labels used for help text and completion hints.
busy string Busy behavior while an agent turn is running: run (default), reject, queue_request, or queue_command.
startup_ok boolean If true, the command may run before the runtime has finished bootstrapping. Defaults to false.
hidden boolean If true, the command is hidden from /help and the picker (still callable). Defaults to false.
override boolean If true, replace an existing command with the same name. Defaults to false.

smelt.defaults.Config

Spec accepted by smelt.defaults.

Field Type Required Description
model string Starting model reference ("provider/model" or bare model name).
mode string Starting agent mode. Must name a registered mode.
reasoning_effort string Starting reasoning effort: "off", "low", "medium", "high", "max".

smelt.dialog.Keymap

One dialog-level keymap entry. on_press(ctx) receives the dialog context exposing ctx.close() and ctx.resolve(value) so the handler can dismiss the dialog or resolve the blocking open call.

Field Type Required Description
key string yes Chord string (e.g. "q", "<Esc>", "ctrl-j").
hint string Optional one-line hint surfaced in the dialog footer.
on_press fun(ctx: any): yes any Handler invoked when the key fires.

smelt.dialog.MenuItem

Each item displayed in smelt.dialog.menu. Strings are also accepted and lifted into this shape automatically.

Field Type Required Description
label string yes Row text after the dim N. numbering.
description string Optional second row, rendered dim.
key string Optional chord that triggers this item (defaults to its 1-based index for items 1..9).
disabled boolean Render dimmed and skip selection/submission when true.

smelt.dialog.MenuOpts

Options accepted by smelt.dialog.menu.

Field Type Required Description
selected integer 1-based starting cursor (default 1).
shortcuts "submit"|"select"|false Digit-key behavior. Default "submit".
numbered boolean Show the dim N. prefix (default true).
wrap boolean Hard-wrap long labels/descriptions to the menu width so fit-height dialogs grow vertically instead of clipping or panning.
wrap_width integer Initial wrap width used before the first resize event.
on_submit fun(ctx: any): any Override the submit path. ctx carries the dialog handles plus ctx.index (1-based) and ctx.item. Default resolves the active dialog with { index, item }.

smelt.dialog.Opts

Options accepted by smelt.dialog.open / smelt.dialog.open_handle. Dialogs fit their content by default while preserving transcript context. Integer height values are body-relative and gain the top chrome row automatically. Pick one of height or max_height; setting both raises.

Field Type Required Description
title string Title rendered in the chrome row.
panels smelt.dialog.Panel[] yes Ordered list of body panels.
bottom_panels smelt.dialog.Panel[] Panels pinned to the bottom when the dialog has surplus height; extra height is placed between them and panels.
bottom_gap integer Minimum blank rows between panels and bottom_panels (default 0).
focus smelt.win.Win Leaf that should receive initial focus.
height any Fixed total body size: integer cells, "N%", "fill", or "fit".
max_height any Maximum root-layout height while fitting content.
min_height any Minimum root-layout height while fitting content.
blocks_agent boolean Block the agent loop while the dialog is open. Defaults to false.
border table Top border style override; defaults to { top = "SmeltAccent" }.
resizable boolean Set false to disable the default top-edge resize handle.
keymaps smelt.dialog.Keymap[] Dialog-level key bindings (merged with built-ins).
close_with_q boolean Bind q to close for read-only/list dialogs. Leave false for dialogs that accept text input.
on_submit fun(ctx: any): any Handler invoked on Enter; default resolves with the focused leaf.
on_dismiss fun(): nil Handler invoked when the dialog is dismissed.
on_close fun(ctx: any): nil Handler invoked once whenever the dialog resolves or closes.

smelt.dialog.Panel

One body panel inside a dialog. leaf is the win/leaf built by one of the smelt.dialog.* helpers; height follows the same grammar as smelt.dialog.open (integer cells, "N%", "fill", "fit").

Field Type Required Description
leaf smelt.win.Win yes A leaf returned by smelt.dialog.input/options/list/markdown/content.
height any Integer cells, "N%", "fill", or "fit".

smelt.dialog.PickerOpts

Options accepted by smelt.dialog.picker. Layered on top of smelt.dialog.Opts; only the picker-specific fields are listed.

Field Type Required Description
items any[]
render fun(item: any): yes table Per-item { text, marks } table - see smelt.list.new.
filter fun(item: any): boolean Predicate applied during set_filter / refresh.
placeholder string Input placeholder; defaults to "".
empty_text string Shown in the list when nothing matches.
on_open fun(ctx: any): nil Fires once after the input/list have been built.
on_query fun(query: string, ctx: any): nil Fires on every keystroke; default re-applies filter.
on_submit fun(ctx: any): any Fires on Enter. ctx.item is the highlighted row; defaults to resolving with ctx.item when non-nil.
on_dismiss fun(): nil Fires when the dialog is dismissed.
keymaps smelt.dialog.Keymap[] Extra dialog-level keymaps merged on top of navigation bindings.
title string Forwarded to smelt.dialog.open.
height any Forwarded to smelt.dialog.open.
max_height any Forwarded to smelt.dialog.open.
min_height any Forwarded to smelt.dialog.open.
blocks_agent boolean Forwarded to smelt.dialog.open.

smelt.engine.AskError

Typed error table delivered to on_response when the underlying provider call fails. kind is a stable string the caller can branch on; message is a human-readable single-line description. The struct exists purely as a doc / LuaCATS schema target - the actual table is built in LuaRuntime::fire_ask_callback because it lands on a callback path that bypasses FromLua decoding.

Field Type Required Description
kind string yes One of "network" | "rate_limited" | "quota" | "invalid_response" | "context_window" | "cancelled" | "other".
message string yes Human-readable single-line description (newlines collapsed to spaces).

smelt.engine.AskMessage

One text-only message used by request hooks that exchange plain user/assistant rows.

Field Type Required Description
role string yes Either "user" or "assistant". Other roles are silently dropped.
content string yes Message body as plain text.

smelt.engine.AskResponseFormat

Structured JSON-output specification for smelt.engine.ask.

Field Type Required Description
name string yes Schema name (used by some providers as the response_format label).
schema table yes JSON schema describing the expected response shape. Accepts a Lua table that round-trips through lua_table_to_json into a JSON value.

smelt.engine.AskSpec

Spec for smelt.engine.ask.

Field Type Required Description
system string yes System prompt sent before the conversation.
messages table Prior turns. When present, this must be a sequence of full protocol::Message-shaped rows such as { role, content?, reasoning_content?, tool_calls?, tool_call_id?, is_error? }.
question string Single-shot question appended as a final user message after messages.
model string Model reference ("provider/model" or a bare name resolved against the configured providers). When nil, falls back to the primary model.
response_format smelt.engine.AskResponseFormat JSON-schema response constraint.
reasoning_effort smelt.reasoning.Effort Reasoning effort for the request; defaults to "off".
guard table Lifecycle guard returned by smelt.lifecycle.guard(...). When provided, the Lua bootstrap suppresses on_delta and on_response after the guard expires.
visible_retries boolean Surface provider retry events on the main work indicator. Intended for foreground auxiliary work such as compaction.
on_delta fun(value: string) Fires for each streamed assistant text delta when provided. The final on_response still fires once with the full assistant message.
on_response fun(arg1: any, arg2: smelt.engine.AskError?) Fires once with (response, err). On success err is nil and response is a full assistant message table; on failure response is nil and err is a smelt.engine.AskError table.

smelt.engine.CommandOverrides

Front-matter override block accepted by smelt.engine.submit_command. Mirrors what plugin commands set in their markdown header. Tool-name keys (e.g. bash, edit) become per-subcommand pattern buckets.

Field Type Required Description
description string Override the command description shown in /help.
provider string Force a specific provider for this command's turn.
model string Force a specific model id.
temperature number Sampling temperature override.
top_p number Nucleus-sampling cutoff override.
top_k integer Top-k sampling cutoff override.
min_p number Minimum-probability cutoff override.
repeat_penalty number Repeat-penalty override.
reasoning_effort string Reasoning-effort override; one of the smelt.reasoning.Effort strings.
tools smelt.engine.RuleOverride Per-tool allow/ask/deny patterns for the duration of the turn.
[string] smelt.engine.RuleOverride Per-subcommand pattern buckets keyed by tool name.

smelt.engine.InheritedAskSpec

Spec for smelt.engine.ask_inherited.

Field Type Required Description
messages table Prior turns. When present, this must be a sequence of full protocol::Message-shaped rows such as { role, content?, reasoning_content?, tool_calls?, tool_call_id?, is_error? }. When omitted or empty, the live model-visible history is inherited.
question string Single-shot question appended as a final user message after messages.
model string Model reference ("provider/model" or a bare name resolved against the configured providers). When nil, falls back to the primary model.
response_format smelt.engine.AskResponseFormat JSON-schema response constraint.
reasoning_effort smelt.reasoning.Effort Reasoning effort for the request; defaults to "off".
guard table Lifecycle guard returned by smelt.lifecycle.guard(...). When provided, the Lua bootstrap suppresses on_delta and on_response after the guard expires.
visible_retries boolean Surface provider retry events on the main work indicator. Intended for foreground auxiliary work such as compaction.
on_delta fun(value: string) Fires for each streamed assistant text delta when provided. The final on_response still fires once with the full assistant message.
on_response fun(arg1: any, arg2: smelt.engine.AskError?) Fires once with (response, err). On success err is nil and response is a full assistant message table; on failure response is nil and err is a smelt.engine.AskError table.

smelt.engine.PrepareContextEstimate

Token accounting breakdown passed inside smelt.engine.PrepareRequest.

Field Type Required Description
source string yes One of "full_request_estimate" | "provider_snapshot" | "provider_snapshot_plus_history_delta" | "checkpoint_estimate" | "checkpoint_estimate_plus_history_delta".
total_context_tokens integer yes Total active-context estimate used by auto-compaction.
provider_context_tokens integer Latest provider-reported active context, when available.
estimated_delta_tokens integer yes Locally estimated tokens added on top of provider usage.
latest_snapshot_history_len integer History length attached to the latest token snapshot, when available.
current_history_len integer yes Current session history length at the prepare hook.

smelt.engine.PrepareRequest

Request object passed to smelt.engine.on_prepare_request.

Field Type Required Description
messages smelt.engine.AskMessage[] yes Model-visible conversation excluding the system prompt.
estimated_tokens integer yes Conservative token estimate for the request about to be sent, including system prompt, messages, and tool definitions.
estimated_context_tokens integer yes Active-context estimate for auto-compaction. When a provider has reported context usage, this starts from that server-observed count and adds only local messages appended after the matching token snapshot. After a compaction checkpoint and before the next provider usage report, this starts from the checkpoint's post-compaction estimate. Before either baseline exists, it equals estimated_tokens.
context_estimate smelt.engine.PrepareContextEstimate yes Structured breakdown explaining how estimated_context_tokens was computed.

smelt.engine.RuleOverride

Subcommand rule override accepted inside CommandOverrides. Mirrors the front-matter { allow?, ask?, deny? } shape.

Field Type Required Description
allow string[] Patterns that auto-allow.
ask string[] Patterns that always prompt.
deny string[] Patterns that auto-deny.

smelt.input.Input

Single-line input handle returned by smelt.input.new(opts).

Field Type Required Description
win fun(): smelt.win.Win yes Return the underlying Win handle for layout, focus, and advanced event bindings.
buf fun(): smelt.buf.Buf? yes Return the backing buffer, or nil if the input window is gone.
text fun(): string yes Return the current input text.
set_text fun(text: string): nil yes Replace the current input text. Newlines are collapsed to spaces and the cursor moves to the end.
on fun(event: smelt.input.Event, func: fun(value: table)): smelt.Reg yes Subscribe to change, submit, or cancel. Callback payload carries ctx.text.
key fun(chord: string, func: fun(value: table)): smelt.Reg yes Bind func to chord on the underlying input window. Returns a Reg handle.

smelt.layout.Node

Opaque block-layout node returned by smelt.layout.* constructors and accepted by transcript renderers, tool previews, and other content-layout APIs.

Field Type Required Description

smelt.lifecycle.Guard

Field Type Required Description
alive fun(self:smelt.lifecycle.Guard):boolean yes Return true while every captured epoch still matches and the guard was not cancelled or superseded.
cancel fun(self:smelt.lifecycle.Guard) yes Mark the guard stale immediately.
latest fun(self:smelt.lifecycle.Guard,key:string):smelt.lifecycle.Guard yes Mark this guard as the latest request for key; older guards with the same key become stale.
wrap fun(self:smelt.lifecycle.Guard,fn:function):function yes Return a wrapper that calls fn only while the guard is alive.

smelt.list.List

Field Type Required Description
refresh fun(self: smelt.list.List) yes
set_items fun(self: smelt.list.List, items: any[]?) yes
set_items_preserve fun(self: smelt.list.List, items: any[]?, key_fn: fun(item: any): any) yes
set_filter fun(self: smelt.list.List, fn: (fun(item: any): boolean)?) yes
set_render fun(self: smelt.list.List, fn: fun(item: any): smelt.list.Row) yes
visible fun(self: smelt.list.List): yes any[]
size fun(self: smelt.list.List): yes integer
selected_index fun(self: smelt.list.List): yes integer?
selected fun(self: smelt.list.List): yes any
set_cursor fun(self: smelt.list.List, i: integer) yes
move_cursor fun(self: smelt.list.List, delta: integer) yes

smelt.list.Mark

Field Type Required Description
col integer 0-based byte column for the mark.
opts smelt.buf.MarkOpts Mark/highlight options.

smelt.list.Opts

Options accepted by smelt.list.new. leaf and buf are mandatory - they own the rendered selection cursor and the backing line buffer; the rest configure how data is sourced, filtered, and rendered.

Field Type Required Description
leaf smelt.win.Win yes Selectable list leaf (typically from smelt.dialog.list).
buf smelt.buf.Buf yes Backing buffer that mirrors the rendered rows.
items any[] Initial item set. Mutate via :set_items(...) later if needed.
render fun(item: any): yes smelt.list.Row Returns { text, spans?, marks? } per visible row.
filter fun(item: any): boolean Predicate re-run on :set_filter / :refresh.
empty_text string Placeholder line shown when no row passes the filter.
anchor "top"|"bottom" Render short lists at the top or bottom of the viewport. Defaults to "top".

smelt.list.Row

Field Type Required Description
text string Plain row text. Used when spans is omitted.
spans smelt.list.Span[] Styled spans for the row.
marks smelt.list.Mark[] Extmarks to apply after rendering.

smelt.list.Span

Field Type Required Description
text string yes Span text.
style table Highlight style passed through to buf:styled.
syntax string Inline syntax token for this span.

smelt.mcp.Config

MCP server config accepted by smelt.mcp.register.

Field Type Required Description
type string Server kind. Only "local" (the default) is supported.
command string|string[] Executable + leading argv. Either a string ("my-server") or a list ({"my-server", "--flag"}).
args string[] Trailing arguments appended after command.
description string Human-readable description shown by /mcp.
env table<string, string> Extra environment variables to set on the child process.
timeout integer Request timeout in milliseconds. Defaults to 30000.
enabled boolean Whether the server is enabled. Defaults to true.

smelt.notify.Scoped

Source-bound notify handle returned by smelt.notify.scoped. Use handle.info(msg), handle.error(msg), or handle.warn(msg) to tag every toast with the bound source.

Field Type Required Description
info fun(msg: string) yes Raise an informational toast tagged with the bound source.
error fun(msg: string) yes Raise an error toast tagged with the bound source.
warn fun(msg: string) yes Raise a warning toast tagged with the bound source.

smelt.overlay.DragConfig

Overlay drag configuration table. Use true for the floating default: title chrome plus inert-body drag.

Field Type Required Description
title boolean When true, the overlay chrome moves the overlay unless a resize handle owns the cell.
body boolean | "inert" true moves from any body leaf; "inert" moves only from non-focusable, non-selectable leaves.

smelt.overlay.Keymap

One overlay-scoped key binding installed by smelt.overlay.new({ keymaps = ... }).

Field Type Required Description
key string yes Key chord such as <Esc>, <C-j>, or q.
on_press fun(ctx: table) yes Handler invoked when the key fires while any overlay leaf has focus.
hint string Human-readable hint for key-discovery plugins.

smelt.overlay.NewOpts

Options for smelt.overlay.new(opts). The overlay body comes from a smelt.ui.layout tree.

Field Type Required Description
layout smelt.ui.layout yes Layout tree to render inside the overlay.
name string Stable name used to hot-reload this overlay in place.
title string | table Optional title rendered in the overlay border.
border table Border style override; parsed with the shared border vocabulary.
anchor "dock_bottom"|"dock_top"|"dock_left"|"dock_right"|"center"|"screen_at"|"win" Where to place the overlay. Defaults to dock_bottom.
above_rows integer Rows to keep clear above the bottom dock, typically the statusline height.
target smelt.win.Win | integer Target window for anchor = "win".
attach string Alignment point for anchor = "win" such as nw, center, or se.
row integer Screen row offset for anchor = "screen_at".
col integer Screen column offset for anchor = "screen_at".
row_offset integer Row offset for anchor = "win".
col_offset integer Column offset for anchor = "win".
corner string Corner used by anchor = "screen_at" (nw, ne, sw, or se).
width integer | string | table Overlay width constraint. Accepts cells, "N%", "fit", "fill", "min:N", "max:N", "ratio:N/M", or long table form.
height integer | string | table Overlay height constraint. Same vocabulary as width.
max_width integer | string | table Optional upper bound applied after width resolves.
max_height integer | string | table Optional upper bound applied after height resolves.
min_width integer | string | table Optional lower bound applied after width resolves.
min_height integer | string | table Optional lower bound applied after height resolves.
modal boolean Whether the overlay blocks input behind it. Defaults to true.
blocks_agent boolean Whether the overlay should block agent progress while open.
z integer Z-index. Higher overlays render above lower overlays.
draggable boolean | smelt.overlay.DragConfig Enable or configure mouse dragging.
resizable boolean | smelt.overlay.ResizeConfig Enable or configure mouse resize handles.
keymaps smelt.overlay.Keymap[] Overlay-scoped key bindings.

smelt.overlay.Overlay

Overlay handle returned by smelt.overlay.new(opts).

Field Type Required Description
close fun(): nil yes Close the overlay. No-op if already closed.
key fun(chord: string, func: fun(value: table)): smelt.Reg yes Bind func to chord on this overlay. Fires when any leaf of the overlay holds focus, after a per-window keymap miss but before global Lua keymaps. Returns a Reg whose :remove() undoes the binding.

smelt.overlay.ResizeConfig

Overlay resize configuration table. Use true for the floating default: left/right/bottom edges and corners, leaving the top chrome for drag.

Field Type Required Description
top boolean Enable top-edge resize.
right boolean Enable right-edge resize.
bottom boolean Enable bottom-edge resize.
left boolean Enable left-edge resize.
corners boolean Upgrade cells where two enabled edges meet into diagonal resize handles.

smelt.paint.Paint

Opaque handle returned by smelt.paint.register. Usable directly in smelt.ui.layout.leaf(handle, opts) (it stands in for a Win in layout leaves).

Field Type Required Description
remove fun(): boolean yes Drop the paint callback. Returns true if it was still registered. Subsequent paints of this id no-op.
rect fun(): any yes Return the paint leaf's current screen rect as { row, col, width, height }, or nil until the first render lays it out.
on fun(event: smelt.paint.Event, func: fun(value: table)): smelt.Reg yes Subscribe func to event on this paint leaf. Returns a Reg handle whose :remove() undoes the subscription.

smelt.paint.Slice

Grid slice passed to paint callbacks. Methods delegate to the live grid slice for the current frame; out-of-scope calls fail cleanly.

Field Type Required Description
width fun(): integer yes Return the slice width in cells.
height fun(): integer yes Return the slice height in cells.
set fun(row: integer, col: integer, ch: string, style: table?): nil yes Write a single character with optional style at (row, col).
put_str fun(row: integer, col: integer, text: string, style: table?): nil yes Write a string with optional style at (row, col).
fill_rect fun(row: integer, col: integer, w: integer, h: integer, ch: string?, style: table?): nil yes Fill a rectangle with an optional character and style.

smelt.permissions.EffectRules

Effect-level decisions that apply to tools without a more specific rule.

Field Type Required Description
read string
write string
network string
process string
config string
user string
other string

smelt.permissions.ListResult

Current permission state returned by smelt.permissions.list().

Field Type Required Description
session smelt.permissions.SessionEntry[] yes Session-scoped tool/pattern approvals for this run.
path_grants smelt.permissions.SessionPathGrant[] yes Session-scoped path grants for this run.
workspace smelt.permissions.WorkspaceRule[] yes Workspace rules loaded from the on-disk store rooted at the current cwd.

smelt.permissions.ModePerms

Permission slots that apply within a single agent mode.

Field Type Required Description
tools smelt.permissions.RuleSet Exact tool-name allow/ask/deny entries.
effects smelt.permissions.EffectRules Effect-level decisions keyed by effect name.
patterns table<string, smelt.permissions.RuleSet> Tool-specific argument patterns keyed by tool name ("bash", "web_fetch", …).

smelt.permissions.PolicySpec

Spec for smelt.permissions.extend. Each mode falls back to default.

Field Type Required Description
default smelt.permissions.ModePerms Baseline rules applied unless a mode-specific slot overrides.
[string] smelt.permissions.ModePerms Mode-specific rules keyed by registered mode name.

smelt.permissions.RuleSet

allow/ask/deny arrays accepted by permission policy sections.

Field Type Required Description
allow string[] Patterns that auto-allow without prompting.
ask string[] Patterns that always prompt.
deny string[] Patterns that auto-deny.

smelt.permissions.SessionEntry

A single session permission entry (one approved tool/pattern pair).

Field Type Required Description
tool string yes Tool name the rule applies to (e.g. "bash"). Special value "directory" grants generic path access.
pattern string yes Pattern matched against the tool's argument bucket.

smelt.permissions.SessionPathGrant

A tool-specific session path grant. Grants are in-memory only and can satisfy workspace path checks for the matching tool. When mode is set, the grant applies only in that mode.

Field Type Required Description
kind string yes Grant kind. Currently only "path" is supported.
mode string Optional mode, e.g. "plan". Omit for mode-independent path trust.
tool string yes Tool name the grant applies to, e.g. "read_file" or "edit_file".
access string yes Path access granted: "read" or "write".
path_prefix string yes Directory prefix covered by the grant.

smelt.permissions.SyncSpec

Spec for smelt.permissions.sync.

Field Type Required Description
session smelt.permissions.SessionEntry[] Session entries; applied for this run only.
path_grants smelt.permissions.SessionPathGrant[] Tool-specific session path grants; applied for this run only.
workspace smelt.permissions.WorkspaceRule[] Workspace rules; persisted to disk under the current cwd.

smelt.permissions.WorkspaceRule

A workspace permission rule (one tool with N patterns, persisted to disk).

Field Type Required Description
tool string yes Tool name the rule applies to.
patterns string[] yes Patterns granted for this tool.

smelt.picker.FuzzyOpts

Field Type Required Description
items (string|smelt.picker.Item)[] yes Items to filter.
placement "center"|"bottom"|"cursor"|"prompt_docked" Picker placement. Defaults to "prompt_docked" for this wrapper.
on_select fun(item: smelt.picker.Item) Live selection callback.

smelt.picker.FuzzyResult

Field Type Required Description
index integer yes 1-based accepted item index.
item smelt.picker.Item yes Accepted normalized item.
action string yes Accept action reported by the prompt picker.

smelt.picker.Item

Row accepted by picker constructors. A bare string is also accepted and is treated as { label = string }.

Field Type Required Description
label string yes Primary text shown for this row.
description string Secondary text shown next to the label.
prefix string Small prefix rendered before the label.
ansi_color integer ANSI color slot for the prefix.
label_color integer ANSI color slot for the label.
search_terms string[] Extra strings considered by fuzzy pickers.

smelt.picker.NewOpts

Options for the low-level non-blocking picker handle constructor.

Field Type Required Description
items (string | smelt.picker.Item)[] yes Initial picker rows. Must be non-empty.
placement "center"|"bottom"|"cursor"|"prompt_docked" Where to place the picker. Defaults to center.

smelt.picker.OpenResult

Field Type Required Description
index integer yes 1-based accepted item index.
item any yes Original item from opts.items.

smelt.picker.Picker

Picker handle returned by smelt.picker.new(opts). Setter methods return the same handle for chaining.

Field Type Required Description
win fun(): smelt.win.Win yes Return the underlying Win handle (use win:key(...), win:on(...) to bind input).
close fun(): nil yes Close the picker overlay. No-op if already closed.
items fun(items: table, selected: integer?): smelt.picker.Picker yes Replace the picker's items. Each entry is a string or { label, description?, ansi_color?, label_color?, prefix?, icon?, ... }. icon = { kind = "file"|"dir", path = string } renders file-list icons unless prefix is set. selected is the 0-based logical index to land the cursor on (default 0 - top of the new list); pass the current selection here to avoid a flash to row 0 followed by a separate :selected() call. Returns the handle for chaining.
selected fun(idx: integer?): any yes Read or write the current logical selection (0-based). Without arg returns the index (nil if the picker is empty); with arg sets the selection and returns the handle for chaining.
move fun(delta: integer): smelt.picker.Picker yes Move the picker's cursor by delta rows (clamped to the buffer's line count). Returns the handle for chaining.

smelt.prompt.CompleterSpec

Completer specification handed to smelt.prompt.completer for full candidate sets ranked in Lua.

Field Type Required Description
detect fun(text: string, cpos: integer): yes integer? Detect the active trigger and return its 0-based anchor byte offset.
items fun(anchor: integer, text: string, cpos: integer): yes table[] Build a full candidate set for Lua-side ranking.
query fun(text: string, anchor: integer, cpos: integer): yes string Query used for Lua-side ranking.
accept fun(item: table, anchor: integer, action: string): yes nil Splice the accepted candidate into the prompt.
manual boolean Whether Tab can open this completer when no picker is active.
auto boolean Set false to prevent text_changed from auto-opening this completer.
accept_single boolean Set false to keep a manual Tab picker open when there is exactly one match.
on_select fun(item: table): nil Live selection callback.

smelt.prompt.MatchesCompleterSpec

Completer specification handed to smelt.prompt.completer for bounded, already-ranked providers.

Field Type Required Description
detect fun(text: string, cpos: integer): yes integer? Detect the active trigger and return its 0-based anchor byte offset.
matches fun(anchor: integer, text: string, cpos: integer, limit: integer): yes table[]
query fun(text: string, anchor: integer, cpos: integer): string Query identity used to distinguish user edits from provider refreshes.
accept fun(item: table, anchor: integer, action: string): yes nil Splice the accepted candidate into the prompt.
manual boolean Whether Tab can open this completer when no picker is active.
auto boolean Set false to prevent text_changed from auto-opening this completer.
accept_single boolean Set false to keep a manual Tab picker open when there is exactly one match.
limit integer Maximum rows requested from matches providers.
poll_ms integer Refresh interval while matches returns { scanning = true } or { searching = true }.
loading_delay_ms integer Delay before showing an initial loading row when there are no stale rows to keep.
loading_poll_ms integer Quiet polling interval before the initial loading row appears.
on_select fun(item: table): nil Live selection callback.

smelt.prompt.PickerItem

Picker entry shown in the prompt-docked dropdown. label and the optional flavour fields mirror what the fuzzy ranker renders; the caller is free to attach extra fields and read them back from on_select / on_enter.

Field Type Required Description
label string yes Primary text rendered for the row.
description string Secondary text shown dimmed after the label.
ansi_color any ANSI color spec used for the prefix glyph.
label_color any Override the label's color.
prefix string Glyph rendered before the label.
search_terms string Extra haystack tokens for the fuzzy match.

smelt.prompt.PickerOpts

Options accepted by smelt.prompt.open_picker. Passing on_enter switches the picker to persistent mode (stays open across selects); omit it for single-shot behaviour.

Field Type Required Description
items smelt.prompt.PickerItem[]
provider fun(query: string, limit: integer): table Async/ranked provider returning { items, searching?, scanning?, message?, status? }.
limit integer Maximum rows requested from provider; defaults to 200.
poll_ms integer Refresh interval while provider returns { scanning = true } or { searching = true }.
loading_delay_ms integer Delay before showing an initial loading row when there are no stale rows to keep.
loading_poll_ms integer Quiet polling interval before the initial loading row appears.
on_select fun(item: smelt.prompt.PickerItem): nil Fires on every cursor move.
on_enter fun(item: smelt.prompt.PickerItem, idx: integer): nil Persistent-mode accept handler.
rank fun(items: table[], query: string, original: smelt.prompt.PickerItem[]): integer[] Custom filter/ranker. items are stamped picker rows; return 1-based row indices in display order.
on_dismiss fun(): nil Fires on Esc/Ctrl-C.

smelt.provider.Config

Spec accepted by smelt.provider.register.

Field Type Required Description
type string Provider kind tag ("openai", "anthropic", etc.).
api_base string Base URL the engine talks to.
api_key_env string Environment variable that holds the bearer token.
models string|smelt.provider.Model[] Models offered by this provider.

smelt.provider.Model

One model entry in a provider's models list. Plugin authors can pass either a bare model id string or a full table - the wrapper handles both forms transparently.

Field Type Required Description
name string Model id as it appears in API requests.
temperature number Default sampling temperature.
top_p number Default nucleus-sampling cutoff.
top_k integer Default top-k sampling cutoff.
min_p number Default minimum-probability cutoff.
repeat_penalty number Default repeat penalty.
tool_calling boolean Whether the model supports tool calls.
input_cost number Cost per input token in USD.
output_cost number Cost per output token in USD.
cache_read_cost number Cost per cache-read token in USD.
cache_write_cost number Cost per cache-write token in USD.
max_tokens integer Maximum output tokens for this model. Defaults to the model's own limit, falling back to 4096 if unknown.
thinking_budgets table Per-level token budgets for budget-based thinking.
context_window integer Total context window, in tokens.
supports_reasoning boolean Whether this model supports reasoning/thinking parameters.
supports_fast_mode boolean Whether this model supports accelerated inference.
input_modalities string[] Input modalities supported by this model, for example { "text", "image", "pdf" }.

smelt.provider.NormalizedResult

Field Type Required Description
rows table[] yes Rows to render after optional synthetic message insertion.
result table Original provider result when the input used the provider shape.
loading boolean yes True while the provider is still scanning or searching.

smelt.remember.Config

Spec accepted by smelt.remember.

Field Type Required Description
model boolean When true (default), restore the last-used model on launch.
mode boolean When true (default), restore the last-used agent mode on launch.
reasoning_effort boolean When true (default), restore the last-used reasoning effort on launch.

smelt.render.DiffSplitOpts

Options for smelt.render.diff_split.

Field Type Required Description
old string Left/pre-edit text.
new string Right/post-edit text.
lang string Syntax language token such as "rust", "lua", or "py".
path string Path whose extension is used when lang is omitted.

smelt.render.SyntaxOpts

Options for smelt.render.syntax.

Field Type Required Description
content string Source code to render.
lang string Syntax language token such as "rust", "lua", or "py".
path string Path whose extension is used when lang is omitted.

smelt.render.TextOpts

Options for smelt.render.text.

Field Type Required Description
hl_group string Highlight group applied to the whole block. When omitted, text renders dim.
width integer Wrapping width in terminal cells. Defaults to the current terminal width.

smelt.theme.ColorDecl

Color value. Set ansi (256-color palette index) or rgb ({R, G, B} triple) for a direct color, or dark / light (themselves ColorDecls) for a branch that resolves against the terminal background. A matching-side branch wins over the direct fields.

Field Type Required Description
ansi integer ANSI 256-color palette index for the default (non-branched) case.
rgb integer[] [r, g, b] sRGB triple for the default (non-branched) case.
light smelt.theme.ColorDecl Color this branch resolves to when is_light == true.
dark smelt.theme.ColorDecl Color this branch resolves to when is_light == false.

smelt.theme.StyleDecl

Style table for a single highlight group. Every field is optional - unset fields stay at Style::default(). Pass a string in place of this struct (at the group-map level) to alias another group.

Field Type Required Description
fg smelt.theme.ColorDecl Foreground color.
bg smelt.theme.ColorDecl Background color.
bold boolean Bold text.
italic boolean Italic text.
dim boolean Dim / faint text.
underline boolean Underline.
crossedout boolean Strikethrough.
reverse boolean Reverse video.

smelt.theme.ThemeSpec

Colorscheme table with optional metadata and a required groups map. syntax selects a bundled two-face syntax theme for code highlighting. light marks the palette as light or dark; omit it to use terminal background detection. Every themable color (foreground, background, diff row and inline fills, scrollbar colors, mode indicators) is a group.

Field Type Required Description
name string Display name for this colorscheme.
syntax string Bundled syntect/two-face syntax theme name for code highlighting.
light boolean Whether this colorscheme is light. Omit to use terminal background detection.
groups table<string, string | smelt.theme.StyleDecl> yes Highlight groups keyed by group name.

smelt.tools.PermissionDefaults

Per-mode default decisions installed by smelt.tools.register. Keys are mode names and values are "allow", "ask", or "deny".

Field Type Required Description
[string] smelt.tools.Decision Per-mode decisions keyed by registered mode name.

smelt.tools.ToolDef

Plugin tool definition passed to smelt.tools.register. execute is required; the remaining hooks are optional and are invoked at well-defined points during a tool turn - see the field docs for each callback's contract.

Field Type Required Description
name string yes Tool name; used as the engine-facing identifier.
execute function yes Required handler: execute(args, ctx) - returns the tool result.
description string Human-readable description shown to the model.
parameters table JSON-schema parameters table passed through to the model.
permission_defaults smelt.tools.PermissionDefaults Per-mode default decisions.
effect smelt.tools.Effect Coarse side-effect classification used by permission policy.
default_allow string[] Subcommand patterns that auto-allow without prompting.
subpattern_parser string Built-in subpattern parser kind (e.g. "bash").
modes table Agent modes the tool is available in; nil means all modes.
execution_mode string "concurrent" (default) or "sequential".
summary function summary(args) -> string | styled_lines | nil - styled label rendered in the transcript header AND confirm dialog body header. Plain string is auto-wrapped as one plain span; the styled-lines form is { { { text, syntax?, selectable?, title_suffix?, style? }, ... }, ... } - same span shape as buf:styled plus optional selectable = false for chrome text and title_suffix = true for metadata rendered after the live tool timer.
approval_patterns function approval_patterns(args, ctx) -> string[] - patterns offered as one-click approvals.
preflight function preflight(args, ctx) -> table? - validation hook; nil result skips.
paths_for_workspace function paths_for_workspace(args) -> (string|{ path: string, kind?: "file"|"directory"|"unknown" })[] - paths this invocation will touch.
preview function preview(args) -> smelt.layout - pre-execute preview render. The confirm dialog renders it directly into the preview pane.
preview_output function preview_output(args) -> { content, is_error?, metadata? }|nil - immutable pending transcript output derived from final streamed arguments before execution.
draft_preview function draft_preview(args, ctx, block, opts) -> smelt.layout|nil - best-effort renderer for streamed partial arguments in the transcript.
watchdog_timeout_ms integer Outer watchdog deadline for this tool's coroutine, in milliseconds. This is separate from any timeout the tool implements internally.
watchdog_max_timeout_ms integer Maximum watchdog deadline accepted from tool arguments, in milliseconds.
watchdog_timeout_arg string Tool argument that controls the watchdog deadline. Defaults to timeout_ms.
watchdog_timeout_arg_scale_ms integer Multiplier that converts watchdog_timeout_arg values to milliseconds. Use 1000 for second-based arguments.
watchdog_grace_ms integer Extra time added when a tool argument sets the watchdog deadline, in milliseconds.
headless boolean Whether the tool is available when running headless. Defaults to true. Set to false for tools that require a UI surface (dialogs, menus, managed worktree creation, cwd switching).
override boolean Replace a core tool of the same name (advanced).

smelt.transcript.Block

Semantic transcript block snapshot passed to the root renderer.

Field Type Required Description
id integer yes Stable block id within the session.
index integer yes Zero-based block index in transcript order.
kind "user"|"assistant"|"thinking"|"tool"|"code"|"exec"|"mode"|"process_status"|"compacted" yes Block kind.
text string User/mode/process text.
user_lines table User text as styled span lines, including slash/ref/image accents.
content string Assistant/thinking/code content.
title string Latest structured reasoning-summary title.
summary_titles string[] Ordered structured reasoning-summary title history.
reasoning_kind "summary"|"raw" Reasoning source for thinking blocks.
image_labels string[] User image labels.
icon string Mode icon.
hl_group string Mode/process highlight group.
lang string Code language.
call_id string Tool call id.
name string Tool name.
args table Tool arguments.
summary any Tool styled summary lines or compacted summary text.
summary_text string Tool summary flattened to plain text.
status "pending"|"confirm"|"ok"|"err"|"denied" Tool status.
status_hl string Tool status highlight group.
elapsed table Dynamic elapsed descriptor for smelt.layout.elapsed.
elapsed_secs integer Terminal/static tool elapsed seconds.
elapsed_text string Terminal/static tool elapsed label.
thinking_summary string Folded thinking summary text.
user_message string Tool user-facing status message.
preview_output smelt.transcript.ToolOutput Immutable pending output snapshot for a promoted finished draft.
output smelt.transcript.ToolOutput Tool output snapshot.
event string Process status event type, e.g. "background_process_completed".
event_type string Alias for event.
event_data table Full typed process status event payload.
process_id string Background process id for process status events.
exit_code integer Background process exit code when known.
command string Exec command.
command_spans table Exec command as one styled span line, including the ! accent.

smelt.transcript.Context

Renderer context. Width, theme, and scroll state are intentionally absent.

Field Type Required Description
view_state "collapsed"|"peek"|"expanded"|"trimmed_head"|"trimmed_tail" yes Effective view state for the node currently being rendered.
renderer_generation integer yes Current renderer generation used for cache invalidation.
surface string yes Rendering surface name, currently "transcript".
limits table yes Numeric product row budgets such as tool_output_rows.

smelt.transcript.Group

Field Type Required Description
id integer Stable render-plan group id.
name string Group spec name.
title string Optional display title.
view_state string Current group view state.
children smelt.transcript.Block[] Child block snapshots.
blocks smelt.transcript.Block[] Legacy alias for children.

smelt.transcript.GroupSelector

Group selector declared through smelt.transcript.groups.register.

Field Type Required Description
kind string Match block kind.
name string Match one tool name for tool blocks.
names string[] Match any listed tool name for tool blocks. Cannot be combined with name.
terminal boolean Match terminal/non-terminal blocks.
event string Match typed process status event type.
event_type string Alias for event.
process_id string Match typed background process id.
exit_code integer|string Match typed background process exit code.
fields table<string,string|integer> Exact block-field matches such as { event = "background_process_completed" }.

smelt.transcript.GroupSpec

Declarative transcript group registration. The host owns planning; Lua owns the selector metadata and the virtual-node renderer.

Field Type Required Description
name string yes Unique group name. Registering the same name replaces it.
cache_key string Persisted layout cache key; omit to opt out while active.
priority integer Higher priority plans first. Defaults to 0.
min integer Minimum adjacent matching blocks required. Defaults to 2.
default_view "collapsed"|"peek"|"expanded" Initial presentation when the group first appears.
selector smelt.transcript.GroupSelector yes Declarative block matcher.
bucket string|string[] Stable field names used to split adjacent matching runs.
render fun(group: table, ctx: smelt.transcript.Context): yes table Virtual group renderer.

smelt.transcript.Stream

Transcript-shaped streaming renderer for plugin-owned buffers. Append model text deltas and it renders through the same incremental markdown block pipeline as the main transcript.

Field Type Required Description
append fun(delta: string): nil yes Append one assistant text delta and re-render the target buffer.
finish fun(final_text: string?): nil yes Finalize the streaming block. If final_text is provided and differs from the streamed text, the final text is rendered instead.
reset fun(): nil yes Clear the stream and the target buffer.
width fun(width: integer?): integer? yes Read or set the render width in terminal cells.

smelt.transcript.StreamOpts

Field Type Required Description
width integer Rendering width in terminal cells. Defaults to the target window's content width when the buffer is visible, then falls back to the current terminal width minus dialog gutters.

smelt.transcript.ToolOutput

Tool output snapshot passed to transcript renderers.

Field Type Required Description
content string yes Captured output text.
is_error boolean yes True when the tool result is an error.
metadata table Tool-specific structured metadata.

smelt.ui.Size

Terminal size in cells.

Field Type Required Description
width integer yes Terminal width in cells.
height integer yes Terminal height in cells.

smelt.ui.layout.Measure

Shareable natural-size handle returned by smelt.ui.layout.measure.

Field Type Required Description
set fun(w: integer, h: integer): nil yes Update the measured natural size.
get fun(): integer, integer yes Return the current measured width and height.

smelt.win.Decoration

Handle returned by Win:decorate(opts) for a window-owned decoration.

Field Type Required Description
close fun(): nil yes Remove the decoration and any window leaves it owns.

smelt.win.DecorationOpts

Options accepted by Win:decorate(opts). The required layout is a smelt.ui.layout tree. align is one of nw|n|ne|w|center|e|sw|s|se and defaults to center. Width/height constraints use the same vocabulary as overlays but resolve against the owner window rect.

Field Type Required Description
layout smelt.ui.layout.Layout yes Decoration layout tree.
align string Owner-relative alignment point; default center.
row_offset integer Rows to offset after alignment.
col_offset integer Columns to offset after alignment.
z integer Owner-local stacking order.
width any Width constraint; defaults to fit.
height any Height constraint; defaults to fit.
max_width any Optional width cap.
max_height any Optional height cap.
min_width any Optional width floor.
min_height any Optional height floor.

smelt.win.RowHighlight

Window-owned row background highlight. Ranges use absolute visual rows and an exclusive end; { cursor = true } follows the window cursor row. mode is always (default) or focused; width is full (default) or content.

Field Type Required Description
start integer First absolute visual row to highlight (0-based). Required unless cursor = true.
end integer Exclusive absolute visual row end. Defaults to start + 1.
cursor boolean When true, highlight the current cursor row instead of a fixed range.
hl_group string Theme highlight group to resolve at render time. Default CursorLine.
mode "always"|"focused" Paint always or only while the window is focused. Default always.
width "full"|"content" Paint the full window row, including gutter and padding, or only the content region. Default full.

smelt.win.Win

Window handle returned by smelt.win.new(buf, opts?). Setter methods return the same handle for chaining.

Field Type Required Description
close fun(): nil yes Close the overlay leaf. No-op if the window is already closed.
focus fun(): nil yes Move keyboard focus to this window. No-op if the window is not focusable.
buf fun(): smelt.buf.Buf? yes Return the backing Buf handle, or nil if the window is gone.
rect fun(): any yes Return the window's current viewport rect as { row, col, width, height }, or nil until the first render lays it out.
content_width fun(): any yes Return the inner-content width in cells (gutter and pad_left/pad_right already subtracted), or nil until the first render lays the window out. Use this instead of rect().width when fitting text into the window's actual content budget.
decorate fun(opts: table): smelt.win.Decoration yes Attach a decoration to this window. Decorations are clipped to and painted with their owner pane, below later layout leaves and below global overlays.
cursor fun(row: integer?): any yes Read or write the absolute cursor row (0-based). Without arg returns the row; with arg sets and returns the handle for chaining. The built-in prompt window ignores row-cursor writes; use smelt.prompt.cursor(byte_offset) for prompt text cursor control.
move_cursor fun(delta: integer): smelt.win.Win yes Move the cursor by delta rows (clamped to the buffer's line count). Returns the handle for chaining. The built-in prompt window ignores row-cursor moves; use smelt.prompt.cursor(byte_offset) for prompt text cursor control.
reveal fun(row: integer, opts: table?): smelt.win.Win yes Reveal row row (0-based) and return the handle for chaining. By default this also moves the row cursor there. opts.top_padding reserves rows above the target after the jump; opts.bottom_padding reserves rows below it; opts.cursor = false scrolls without moving the cursor. This is a generic row reveal for ordinary windows and explicit row debugging; transcript message navigation should use smelt.transcript.previous_block, smelt.transcript.next_block, and smelt.transcript.reveal_block. The built-in prompt window ignores row reveals; use smelt.prompt.cursor(byte_offset) for prompt text cursor control.
key fun(chord: string, func: fun(value: table)): smelt.Reg yes Bind func to chord on this window. Returns a Reg handle whose :remove() undoes the binding. Raises on unknown chords.
on fun(event: smelt.win.Event, func: fun(value: table)): smelt.Reg yes Subscribe func to event on this window. Returns a Reg handle whose :remove() undoes the subscription.
placeholder fun(text: string, opts: table?): smelt.win.Win yes Set the window's placeholder - a dim suggestion rendered when the buffer is empty. Replaces any prior placeholder. text must be a single line (no \n); split before calling. opts.accept_keys (array of chord strings, default {}) accept the placeholder into the buffer and fire placeholder_accepted. opts.dismiss_keys (default { "esc", "c-c" }) clear the placeholder and fire placeholder_dismissed. Typing does not destroy the placeholder; the stored text survives so an undo back to an empty buffer makes it visible again. The prompt renders placeholders as wrapped ghost text; other windows render a single virtual-text row. Returns the handle for chaining.
clear_placeholder fun(): nil yes Clear the window's placeholder text and opts. Idempotent.
placeholder_text fun(): string? yes Return the current placeholder text, or nil if none is set.
row_highlights fun(specs: table?): smelt.win.Win yes Replace window-owned row background highlights and return the handle. Specs are smelt.win.RowHighlight tables. Pass nil or {} to clear. Use this for selection/cursor backgrounds that belong to a window view rather than buffer text.
link_scroll fun(others: smelt.win.Win): smelt.win.Win yes Link scroll_top between this window and the variadic others. Closing any member auto-removes it. Returns the handle for chaining.
scroll fun(arg: any): any yes Read or write the window's scroll state. No arg returns { top, follow, total, viewport, max, overflow, at_top, at_bottom, needs_tail_repin } (total is the buffer's line count; viewport is the leaf's height; max is the largest valid top; needs_tail_repin means content overflows and the viewport is not already at bottom). An integer sets scroll_top and clears the pin-to-tail flag. The literal string "tail" jumps the viewport to the buffer's tail while keeping the cursor on the same screen row, then enables tail-follow.

Aliases

smelt.buf.VirtTextPos

Where a virtual-text chunk is rendered relative to the line.

Variants: "inline" | "overlay" | "right_align" | "eol"

smelt.cli.FlagKind

Type of CLI flag declared via smelt.cli.register_flag. Matches the subset of clap that we expose to Lua.

Variants: "boolean" | "string" | "integer"

smelt.events.Name

Name of an event-shaped signal. Open alias - plugin-defined event names are accepted alongside the built-in events listed here.

Open alias - accepts any string. Well-known names: "block_done" | "cmd_post" | "cmd_pre" | "confirm_resolved" | "history" | "input_submit" | "session_ended" | "session_started" | "shutdown" | "stream_delta" | "stream_phase" | "tool_end" | "tool_start" | "turn_complete" | "turn_end" | "turn_error" | "turn_start".

smelt.input.Event

Variants: "change" | "submit" | "cancel"

smelt.paint.Event

Paint-leaf events accepted by paint:on(event, fn).

Variants: "press" | "release" | "drag"

smelt.reasoning.Effort

Reasoning effort level string literal.

Variants: "off" | "low" | "medium" | "high" | "max"

smelt.signal.Name

Name of a reactive signal. Open alias - plugin-defined signals declared via smelt.signal.new are accepted alongside the well-known runtime signals listed here.

Open alias - accepts any string. Well-known names: "agent_mode" | "block_done" | "branch" | "cmd_post" | "cmd_pre" | "confirm_requested" | "confirm_resolved" | "confirms_pending" | "cursor_pos" | "cwd" | "cwd_branch" | "cwd_managed_worktree" | "cwd_project" | "cwd_worktree" | "cwd_worktree_path" | "errors" | "history" | "history_epoch" | "input_epoch" | "input_submit" | "keymap_pending" | "model" | "now" | "notification_visible" | "permission_pending" | "prompt_resize_active" | "prompt_resize_chrome" | "reasoning" | "running_procs" | "session_ended" | "session_epoch" | "session_started" | "session_slug" | "session_title" | "settings_terminal_title" | "shutdown" | "spinner_frame" | "stream_delta" | "stream_phase" | "task_label" | "tokens_used" | "tool_end" | "tool_start" | "tps" | "transcript_navigation_generation" | "turn_complete" | "turn_end" | "turn_error" | "turn_start" | "viewport_pos" | "vim_mode" | "vim_pending_input" | "work_busy" | "work_elapsed_ms" | "work_label" | "work_outcome" | "work_retry_attempt" | "work_retry_remaining_ms" | "work_state".

smelt.tools.Decision

Decision string accepted by decide callbacks and permission_defaults. Matches protocol::Decision::{Allow, Ask, Deny} - the engine's Error(_) variant is not exposed.

Variants: "allow" | "ask" | "deny"

smelt.tools.Effect

Coarse side-effect classification used by permission policy.

Variants: "read" | "write" | "network" | "user" | "process" | "config" | "other"

smelt.vim.Mode

Vim mode string literal.

Variants: "insert" | "normal" | "visual" | "visual_line"

smelt.win.Event

Window-event names accepted by win:on(event, fn). Maps onto the internal WinEvent enum.

Variants: "open" | "close" | "focus" | "blur" | "selection_changed" | "submit" | "text_changed" | "dismiss" | "tick" | "press" | "release" | "drag" | "scrolled" | "resized" | "placeholder_accepted" | "placeholder_dismissed"