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.Plugin

Classification: Supported - Primary alpha facade for user config and plugins.

Handle returned by smelt.plugin for a named plugin scope.

Field Type Required Description
name string yes Stable scope name.
state table yes Ephemeral JSON-shaped state that survives /reload but not restart.

smelt.Reg

Classification: Supported - Primary alpha facade for user config and plugins.

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

Classification: Advanced - Documented low-level capability for plugins that need full control. It may evolve more freely than the Supported facade.

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

Classification: Advanced - Documented low-level capability for plugins that need full control. It may evolve more freely than the Supported facade.

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

Classification: Advanced - Documented low-level capability for plugins that need full control. It may evolve more freely than the Supported facade.

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

Classification: Supported - Primary alpha facade for user config and plugins.

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

Classification: Supported - Primary alpha facade for user config and plugins.

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

Classification: Supported - Primary alpha facade for user config and plugins.

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

Classification: Supported - Primary alpha facade for user config and plugins.

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

Classification: Supported - Primary alpha facade for user config and plugins.

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): any yes Handler invoked when the key fires.

smelt.dialog.MenuItem

Classification: Supported - Primary alpha facade for user config and plugins.

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

Classification: Supported - Primary alpha facade for user config and plugins.

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

Classification: Supported - Primary alpha facade for user config and plugins.

Options accepted by smelt.dialog.open / smelt.dialog.new. 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. Without a handler, Enter leaves the dialog open.
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

Classification: Supported - Primary alpha facade for user config and plugins.

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

Classification: Supported - Primary alpha facade for user config and plugins.

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[] \| fun(): any[] Eager item table or a lazy producer; re-evaluated by on_query.
render fun(item: any): table yes 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

Classification: Supported - Primary alpha facade for user config and plugins.

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 LuaExecution::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" | "cyber_policy" | "cancelled" | "other".
message string yes Human-readable single-line description (newlines collapsed to spaces).

smelt.engine.AskMessage

Classification: Supported - Primary alpha facade for user config and plugins.

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

Classification: Supported - Primary alpha facade for user config and plugins.

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

Classification: Supported - Primary alpha facade for user config and plugins.

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

Classification: Supported - Primary alpha facade for user config and plugins.

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

Classification: Supported - Primary alpha facade for user config and plugins.

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

Classification: Supported - Primary alpha facade for user config and plugins.

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

Classification: Supported - Primary alpha facade for user config and plugins.

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

Classification: Supported - Primary alpha facade for user config and plugins.

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

Classification: Supported - Primary alpha facade for user config and plugins.

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

Classification: Advanced - Documented low-level capability for plugins that need full control. It may evolve more freely than the Supported facade.

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

Classification: Supported - Primary alpha facade for user config and plugins.

Cancellation and supersession guard returned by 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

Classification: Supported - Primary alpha facade for user config and plugins.

Structured list handle returned by smelt.list.new.

Field Type Required Description
refresh fun(self: smelt.list.List) yes Re-apply the filter, render visible rows, and move the cursor to the first item.
set_items fun(self: smelt.list.List, items: any[]?) yes Replace the source items and refresh the list.
set_items_preserve fun(self: smelt.list.List, items: any[]?, key_fn: fun(item: any): any) yes Replace items and restore the selected row by its key_fn result when possible.
set_filter fun(self: smelt.list.List, fn: (fun(item: any): boolean)?) yes Replace or clear the filter predicate and refresh the list.
set_render fun(self: smelt.list.List, fn: fun(item: any): smelt.list.Row) yes Replace the row renderer and redraw the current visible items.
visible fun(self: smelt.list.List): any[] yes Return the filtered items in display order.
size fun(self: smelt.list.List): integer yes Return the number of visible items.
selected_index fun(self: smelt.list.List): integer? yes Return the selected visible-item index (0-based), or nil when empty.
selected fun(self: smelt.list.List): any yes Return the selected source item, or nil when empty.
set_cursor fun(self: smelt.list.List, i: integer) yes Move to the clamped 0-based visible-item index.
move_cursor fun(self: smelt.list.List, delta: integer) yes Move the selection by delta rows, clamped to the visible list.

smelt.list.Mark

Classification: Supported - Primary alpha facade for user config and plugins.

Extmark attached to one rendered list row.

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

smelt.list.Opts

Classification: Supported - Primary alpha facade for user config and plugins.

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): smelt.list.Row yes 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

Classification: Supported - Primary alpha facade for user config and plugins.

Row shape returned by a smelt.list render callback.

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

Classification: Supported - Primary alpha facade for user config and plugins.

Styled text segment in a rendered list row.

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

Classification: Supported - Primary alpha facade for user config and plugins.

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.mode.Mode

Classification: Supported - Primary alpha facade for user config and plugins.

Field Type Required Description
name string yes
label string yes
icon string yes
hl_group string yes
note string yes
permissions table yes

smelt.notify.Scoped

Classification: Supported - Primary alpha facade for user config and plugins.

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

Classification: Advanced - Documented low-level capability for plugins that need full control. It may evolve more freely than the Supported facade.

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

Classification: Advanced - Documented low-level capability for plugins that need full control. It may evolve more freely than the Supported facade.

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

Classification: Advanced - Documented low-level capability for plugins that need full control. It may evolve more freely than the Supported facade.

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

Classification: Advanced - Documented low-level capability for plugins that need full control. It may evolve more freely than the Supported facade.

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

Classification: Advanced - Documented low-level capability for plugins that need full control. It may evolve more freely than the Supported facade.

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

Classification: Advanced - Documented low-level capability for plugins that need full control. It may evolve more freely than the Supported facade.

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

Classification: Advanced - Documented low-level capability for plugins that need full control. It may evolve more freely than the Supported facade.

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 exactly one grapheme cluster 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 one optional Unicode scalar and style.

smelt.permissions.EffectRules

Classification: Supported - Primary alpha facade for user config and plugins.

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

Field Type Required Description
read smelt.permissions.Decision Decision for tools that only read data.
write smelt.permissions.Decision Decision for tools that write or mutate data.
network smelt.permissions.Decision Decision for tools that access the network.
process smelt.permissions.Decision Decision for tools that start or control processes.
config smelt.permissions.Decision Decision for tools that modify configuration.
user smelt.permissions.Decision Decision for tools that require direct user interaction.
other smelt.permissions.Decision Decision for tools whose effect has no more specific category.

smelt.permissions.ListResult

Classification: Supported - Primary alpha facade for user config and plugins.

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.
workspace_revision integer yes Revision required to replace the workspace rules safely.
repository smelt.permissions.WorkspaceRule[] yes Repository rules shared by all worktrees. Empty outside a Git repository.
repository_revision integer yes Revision required to replace the repository rules safely.

smelt.permissions.ModePerms

Classification: Supported - Primary alpha facade for user config and plugins.

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

Classification: Supported - Primary alpha facade for user config and plugins.

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.RevokeSpec

Classification: Supported - Primary alpha facade for user config and plugins.

One exact permission entry to revoke transactionally.

Field Type Required Description
scope string yes Permission scope: "session", "workspace", or "repository".
tool string yes Tool name the entry applies to. Use "directory" for path-prefix entries.
pattern string yes Exact pattern to remove. Use "*" for a blanket tool approval.

smelt.permissions.RuleSet

Classification: Supported - Primary alpha facade for user config and plugins.

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.ScopeReplacement

Classification: Supported - Primary alpha facade for user config and plugins.

Revision-checked replacement for one persisted permission scope.

Field Type Required Description
revision integer yes Revision returned by the smelt.permissions.list() snapshot being edited.
rules smelt.permissions.WorkspaceRule[] yes Complete replacement rule set for this scope.

smelt.permissions.SessionEntry

Classification: Supported - Primary alpha facade for user config and plugins.

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

Classification: Supported - Primary alpha facade for user config and plugins.

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

Classification: Supported - Primary alpha facade for user config and plugins.

Spec for smelt.permissions.sync.

Field Type Required Description
session smelt.permissions.SessionEntry[] Session entries to replace for this run. Omit to leave them unchanged.
path_grants smelt.permissions.SessionPathGrant[] Tool-specific session path grants to replace. Omit to leave them unchanged.
workspace smelt.permissions.ScopeReplacement Revision-checked workspace replacement. Cannot be combined with repository.
repository smelt.permissions.ScopeReplacement Revision-checked repository replacement. Cannot be combined with workspace.

smelt.permissions.WorkspaceRule

Classification: Supported - Primary alpha facade for user config and plugins.

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.Item

Classification: Supported - Primary alpha facade for user config and plugins.

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 text considered by fuzzy pickers.

smelt.picker.NewOpts

Classification: Advanced - Documented low-level capability for plugins that need full control. It may evolve more freely than the Supported facade.

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.OpenOpts

Classification: Supported - Primary alpha facade for user config and plugins.

High-level picker options. Static floating pickers accept items and placement. Prompt-docked pickers also support ranking, providers, and persistent on_enter handling.

Field Type Required Description
items (string\|smelt.picker.Item)[] \| fun(): (string\|smelt.picker.Item)[] Eager list or lazy producer.
placement "center"\|"bottom"\|"cursor"\|"prompt_docked" Picker placement. Ranking, providers, and persistent mode use prompt_docked.
provider fun(query: string, limit: integer): table Async 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: string\|smelt.picker.Item): nil Fires on every cursor move.
on_enter fun(item: string\|smelt.picker.Item, idx: integer): nil Persistent-mode accept handler.
rank fun(items: table[], query: string, original: (string\|smelt.picker.Item)[]): integer[] Custom filter/ranker. Return 1-based row indices in display order.
on_dismiss fun(): nil Fires on Esc/Ctrl-C.

smelt.picker.OpenResult

Classification: Supported - Primary alpha facade for user config and plugins.

Accepted value returned by smelt.picker.open; dismissal returns nil.

Field Type Required Description
index integer yes 1-based accepted item index.
item any yes Original item from opts.items.
action "enter"\|"tab" yes Accept action. Floating pickers return "enter".

smelt.picker.Picker

Classification: Advanced - Documented low-level capability for plugins that need full control. It may evolve more freely than the Supported facade.

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

Classification: Supported - Primary alpha facade for user config and plugins.

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

Field Type Required Description
detect fun(text: string, cpos: integer): integer? yes Detect the active trigger and return its 0-based anchor byte offset.
items fun(anchor: integer, text: string, cpos: integer): table[] yes Build a full candidate set for Lua-side ranking.
query fun(text: string, anchor: integer, cpos: integer): string yes Query used for Lua-side ranking.
accept fun(item: table, anchor: integer, action: string): nil yes 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

Classification: Supported - Primary alpha facade for user config and plugins.

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

Field Type Required Description
detect fun(text: string, cpos: integer): integer? yes Detect the active trigger and return its 0-based anchor byte offset.
matches fun(anchor: integer, text: string, cpos: integer, limit: integer): table[]\|table yes Return bounded already-filtered/ranked rows, or { items, status?, message? } for providers with loading/empty/error states.
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): nil yes 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.provider.Config

Classification: Supported - Primary alpha facade for user config and plugins.

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

Classification: Supported - Primary alpha facade for user config and plugins.

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 1M input tokens in USD.
output_cost number Cost per 1M output tokens in USD.
cache_read_cost number Cost per 1M cache-read tokens in USD.
cache_write_cost number Cost per 1M cache-write tokens 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

Classification: Supported - Primary alpha facade for user config and plugins.

Provider rows and loading state returned by smelt.provider.normalize.

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

Classification: Supported - Primary alpha facade for user config and plugins.

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

Classification: Advanced - Documented low-level capability for plugins that need full control. It may evolve more freely than the Supported facade.

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

Classification: Advanced - Documented low-level capability for plugins that need full control. It may evolve more freely than the Supported facade.

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

Classification: Advanced - Documented low-level capability for plugins that need full control. It may evolve more freely than the Supported facade.

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

Classification: Supported - Primary alpha facade for user config and plugins.

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

Classification: Supported - Primary alpha facade for user config and plugins.

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

Classification: Supported - Primary alpha facade for user config and plugins.

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

Classification: Supported - Primary alpha facade for user config and plugins.

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

Classification: Supported - Primary alpha facade for user config and plugins.

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. Callback errors and malformed entries reject tool evaluation rather than being treated as no paths.
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?, display_content? }|nil - immutable pending transcript output derived from final streamed arguments before execution. Growing display payloads belong in display_content, not JSON metadata.
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.ArgumentField

Classification: Supported - Primary alpha facade for user config and plugins.

Opaque top-level string argument passed to transcript renderers. Complete field content remains in Rust and is available only through smelt.layout.content.

Field Type Required Description
name string yes Top-level argument name.
content_id integer yes Stable shared-content id accepted by smelt.layout.content.
content_revision integer yes Monotonic content revision.
content_bytes integer yes Current field size in bytes.
content_lines integer yes Current logical line count.
content_preview string yes Bounded text preview for labels and fallback UI, not complete content.
complete boolean yes True when the JSON parser has consumed the complete field value.

smelt.transcript.Block

Classification: Supported - Primary alpha facade for user config and plugins.

Bounded semantic transcript metadata 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"\|"group"\|"code"\|"exec"\|"mode"\|"process_status"\|"compacted"\|"compaction_preview" 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 Code content.
content_id integer Stable shared-content id for assistant and thinking blocks.
content_revision integer Monotonic shared-content revision.
content_bytes integer Shared content size in bytes.
content_lines integer Shared content logical line count.
content_preview string Bounded preview for labels and fallback UI, not complete 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 Bounded tool-argument previews and complete non-string structured values.
argument_fields smelt.transcript.ArgumentField[] Opaque top-level string arguments. Complete field content is never included in renderer metadata.
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.
called_at_ms integer Invocation start as Unix epoch milliseconds.
elapsed_ms integer Best-known execution duration in milliseconds.
elapsed_active boolean True only while elapsed time can continue advancing.
thinking_summary string Folded thinking summary text.
user_message string Tool user-facing status message.
preview_output smelt.transcript.ToolOutput Immutable pending output metadata for a promoted finished draft.
output smelt.transcript.ToolOutput Tool output metadata.
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.
group_kind string Registered semantic group name.
bucket string Stable planner bucket for a group.
view_state "collapsed"\|"peek"\|"expanded" Effective group or child view state.
children smelt.transcript.GroupChild[] Ordered bounded child presentation metadata for a group.
child_ids integer[] Ordered stable block ids for a group.
child_count integer Number of semantic children in a group.

smelt.transcript.ContentMetadata

Classification: Supported - Primary alpha facade for user config and plugins.

Metadata for a retained payload whose complete content remains in Rust and is available to renderers only through retained layout leaves.

Field Type Required Description
content_id integer yes Stable shared-content id accepted by retained layout leaves.
content_revision integer yes Monotonic content revision.
content_bytes integer yes Current content size in bytes.
content_lines integer yes Current logical line count.
content_preview string yes Strictly bounded preview for labels, never the complete retained payload.

smelt.transcript.Context

Classification: Supported - Primary alpha facade for user config and plugins.

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.
now_ms integer yes Unix epoch milliseconds shared by the complete top-level render pass.
render fun(node: smelt.transcript.Block, overrides?: { view_state?: string }): smelt.layout.Node yes Re-enter the composed root renderer for a semantic child.

smelt.transcript.Cursor

Classification: Supported - Primary alpha facade for user config and plugins.

Visible transcript cursor position relative to the committed viewport.

Field Type Required Description
viewport_row integer yes Zero-based row inside the transcript viewport.

smelt.transcript.Group

Classification: Supported - Primary alpha facade for user config and plugins.

Semantic transcript group snapshot passed to default renderer helpers.

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.GroupChild[] Ordered bounded child presentation metadata.

smelt.transcript.GroupChild

Classification: Supported - Primary alpha facade for user config and plugins.

Bounded semantic metadata for one retained group child. Growing content and complete child payloads are never embedded in group renderer input.

Field Type Required Description
id integer yes Stable child block id.
kind string yes Semantic block kind.
name string Tool name.
status "pending"\|"confirm"\|"ok"\|"err"\|"denied" Tool status.
summary_text string Bounded plain-text summary.
called_at_ms integer Invocation start as Unix epoch milliseconds.
args table Bounded argument previews used by collapsed labels.
output { content_lines?: integer, is_error?: boolean } Bounded output metadata.
event string Process status event type.
event_data { process_id?: string, exit_code?: integer } Bounded process metadata.
process_id string Background process id.
exit_code integer Background process exit code.

smelt.transcript.GroupSelector

Classification: Supported - Primary alpha facade for user config and plugins.

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

Classification: Supported - Primary alpha facade for user config and plugins.

Declarative transcript group registration. The host owns planning; the root transcript renderer owns presentation for the resulting semantic group node.

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.

smelt.transcript.NavigationOpts

Classification: Supported - Primary alpha facade for user config and plugins.

Filters accepted by semantic previous/next block navigation.

Field Type Required Description
role smelt.transcript.Role Match only blocks with this semantic role. Defaults to user.

smelt.transcript.RevealOpts

Classification: Supported - Primary alpha facade for user config and plugins.

Viewport placement used when revealing a semantic transcript target.

Field Type Required Description
align smelt.transcript.RevealAlign Target alignment within the transcript viewport. Currently only top.
top_padding integer Rows to reserve above the target. Defaults to zero.
move_cursor boolean Move the transcript cursor to the target. Defaults to true.

smelt.transcript.Stream

Classification: Supported - Primary alpha facade for user config and plugins.

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

Classification: Supported - Primary alpha facade for user config and plugins.

Rendering options for smelt.transcript.stream.

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.StyledSpan

Classification: Supported - Primary alpha facade for user config and plugins.

One span in a styled tool title. Style attributes may be supplied directly or through style.

Field Type Required Description
text string Span text. The positional field [1] is also accepted.
style smelt.transcript.StyledSpanStyle Nested style attributes.
syntax string Syntax language used to highlight the span text.
hl string Theme highlight group.
fg string Foreground color.
bg string Background color.
dim boolean Whether to dim the text.
bold boolean Whether to render bold text.
italic boolean Whether to render italic text.
selectable boolean Whether copied transcript text includes this span.
title_suffix boolean Whether this span is transient pending-state title metadata.

smelt.transcript.StyledSpanStyle

Classification: Supported - Primary alpha facade for user config and plugins.

Style attributes accepted on one styled title span.

Field Type Required Description
hl string Theme highlight group.
fg string Foreground color.
bg string Background color.
dim boolean Whether to dim the text.
bold boolean Whether to render bold text.
italic boolean Whether to render italic text.

smelt.transcript.Target

Classification: Supported - Primary alpha facade for user config and plugins.

Stable semantic transcript navigation target. Pass the target directly to smelt.transcript.reveal; internal sparse record coordinates are intentionally hidden.

Field Type Required Description
block_id integer yes Stable transcript block identity.
role smelt.transcript.Role yes Semantic block role.
first_line string yes First source line, suitable for navigation labels.

smelt.transcript.ToolBodyOptions

Classification: Supported - Primary alpha facade for user config and plugins.

Options passed to focused tool body and draft callbacks.

Field Type Required Description
gutter string Prefix rendered before each body line.

smelt.transcript.ToolHeaderOptions

Classification: Supported - Primary alpha facade for user config and plugins.

Options accepted by the default tool header renderer.

Field Type Required Description
hl string Status marker highlight group.

smelt.transcript.ToolOutput

Classification: Supported - Primary alpha facade for user config and plugins.

Bounded tool output metadata passed to transcript renderers.

Field Type Required Description
content_id integer yes Stable shared-content id accepted by smelt.layout.content.
content_revision integer yes Monotonic content revision.
content_bytes integer yes Current output size in bytes.
content_lines integer yes Current logical line count.
content_preview string yes Bounded text preview for labels and fallback UI, not complete output.
is_error boolean yes True when the tool result is an error.
metadata table Bounded tool-specific structured metadata.
content_fields table<string, smelt.transcript.ContentMetadata> Named retained payloads referenced by opaque content IDs.

smelt.transcript.ToolPresentation

Classification: Supported - Primary alpha facade for user config and plugins.

Public presentation policy for one tool name. A complete render callback takes precedence; otherwise the default renderer composes the focused pieces. Registrations are copied and immutable.

Field Type Required Description
cache_key string Stable persisted-layout key. Omit for dynamic presentation state.
render fun(tool: smelt.transcript.Block, ctx: smelt.transcript.Context, presentation: smelt.transcript.ToolPresentation): smelt.layout.Node Complete replacement renderer.
title fun(tool: smelt.transcript.Block, ctx: smelt.transcript.Context): string\|smelt.transcript.StyledSpan[][]\|nil Semantic title after the status marker. Return nil to use the tool summary.
body fun(tool: smelt.transcript.Block, ctx: smelt.transcript.Context, opts?: smelt.transcript.ToolBodyOptions): smelt.layout.Node\|nil Expanded body renderer. Return nil to suppress the body.
draft fun(draft: smelt.transcript.Block, ctx: smelt.transcript.Context, opts?: smelt.transcript.ToolBodyOptions): smelt.layout.Node\|nil Draft body renderer. Return nil to suppress the body.
compact fun(tool: smelt.transcript.Block, ctx: smelt.transcript.Context): string\|smelt.layout.Node\|nil Collapsed detail renderer. Return nil to suppress the detail.

smelt.transcript.View

Classification: Supported - Primary alpha facade for user config and plugins.

Immutable committed transcript view delivered to watch_view. Navigation methods resolve from this exact semantic viewport anchor.

Field Type Required Description
revision integer yes Monotonic revision of observable committed transcript state.
window smelt.win.Win yes Transcript window handle for overlay anchoring.
viewport smelt.transcript.Viewport yes Committed viewport geometry and tail state.
focused boolean yes Whether the transcript currently owns the visible cursor.
cursor smelt.transcript.Cursor Visible transcript cursor position, or nil when the transcript does not own a visible cursor.
previous_block fun(opts: smelt.transcript.NavigationOpts?): smelt.transcript.Target? yes Return the nearest actionable matching block when moving backward from this view. A matching block containing the viewport top is returned; one beginning exactly at the top is skipped.
next_block fun(opts: smelt.transcript.NavigationOpts?): smelt.transcript.Target? yes Return the nearest actionable matching block when moving forward from this view.

smelt.transcript.Viewport

Classification: Supported - Primary alpha facade for user config and plugins.

Geometry and tail state from one committed transcript projection.

Field Type Required Description
width integer yes Outer transcript width in cells.
height integer yes Transcript viewport height in rows.
content_width integer yes Inner content width after gutters and scrollbar reservation.
scrollable boolean yes Whether transcript content exceeds the viewport height.
following_tail boolean yes Whether new content keeps the viewport pinned to the tail.
at_top boolean yes Whether the committed viewport is at the transcript top.
at_bottom boolean yes Whether the committed viewport is at the current transcript bottom.

smelt.ui.Size

Classification: Supported - Primary alpha facade for user config and plugins.

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

Classification: Advanced - Documented low-level capability for plugins that need full control. It may evolve more freely than the Supported facade.

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

Classification: Advanced - Documented low-level capability for plugins that need full control. It may evolve more freely than the Supported facade.

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

Classification: Advanced - Documented low-level capability for plugins that need full control. It may evolve more freely than the Supported facade.

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

Classification: Advanced - Documented low-level capability for plugins that need full control. It may evolve more freely than the Supported facade.

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

Classification: Advanced - Documented low-level capability for plugins that need full control. It may evolve more freely than the Supported facade.

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 it 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 resolve a target from a committed smelt.transcript.View and pass it to smelt.transcript.reveal. 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.
set_renderer fun(renderer: fun(value: smelt.win.Win)?): smelt.win.Win yes Register a retained renderer for this window, or clear it with nil. While the window is mounted, the renderer runs once after registration and again only after invalidate_renderer; its backing buffer remains authoritative between runs. An unmounted window stays dirty and runs when a layout mounts it.
invalidate_renderer fun(): smelt.win.Win yes Mark this window's retained renderer dirty. It repaints during the next compositor frame in which the window is mounted. Returns the handle for chaining.

Aliases

smelt.buf.VirtTextPos

Classification: Advanced - Documented low-level capability for plugins that need full control. It may evolve more freely than the Supported facade.

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

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

smelt.cli.FlagKind

Classification: Supported - Primary alpha facade for user config and plugins.

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

Classification: Supported - Primary alpha facade for user config and plugins.

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

Classification: Supported - Primary alpha facade for user config and plugins.

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

smelt.paint.Event

Classification: Advanced - Documented low-level capability for plugins that need full control. It may evolve more freely than the Supported facade.

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

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

smelt.permissions.Decision

Classification: Supported - Primary alpha facade for user config and plugins.

Decision accepted by effect-level permission rules.

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

smelt.reasoning.Effort

Classification: Supported - Primary alpha facade for user config and plugins.

Reasoning effort level string literal.

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

smelt.signal.Name

Classification: Supported - Primary alpha facade for user config and plugins.

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" | "fast_mode" | "history" | "history_epoch" | "input_epoch" | "input_submit" | "keymap_pending" | "model" | "now" | "notification_visible" | "permission_pending" | "prompt_queue_revision" | "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" | "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

Classification: Supported - Primary alpha facade for user config and plugins.

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

Classification: Supported - Primary alpha facade for user config and plugins.

Coarse side-effect classification used by permission policy.

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

smelt.transcript.RevealAlign

Classification: Supported - Primary alpha facade for user config and plugins.

Variants: "top"

smelt.transcript.Role

Classification: Supported - Primary alpha facade for user config and plugins.

Variants: "user" | "mode" | "process_status" | "assistant" | "thinking" | "tool" | "code" | "exec" | "compacted" | "compaction_preview"

smelt.vim.Mode

Classification: Supported - Primary alpha facade for user config and plugins.

Vim mode string literal.

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

smelt.win.Event

Classification: Advanced - Documented low-level capability for plugins that need full control. It may evolve more freely than the Supported facade.

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"