smelt¶

Tier: UiHost - Requires a terminal UI; calling these from headless mode raises.

Visibility: Public - Stable Lua API intended for user config and plugins.

This namespace mixes Host and UiHost functions; each function below lists its exact tier.

Root smelt namespace. Host-tier bindings are registered first; UiHost-tier bindings are injected when a TUI is active.

smelt.focus¶

fun(): string

Tier: UiHost - Requires a terminal UI; calling these from headless mode raises.

Return which top-level pane currently has focus: "transcript" or "prompt".

smelt.ns¶

fun(name: string): integer

Tier: UiHost - Requires a terminal UI; calling these from headless mode raises.

Look up or allocate a stable namespace id for name. Namespaces scope buf:mark / buf:clear_ns calls so plugins can repaint their region without disturbing others.

smelt.plugin¶

fun(name: any): any

Tier: Host - Available in every runtime, including headless mode.

Promote the current loader frame to plugin scope name and return a small handle exposing the plugin's per-cycle state slot:

local M = smelt.plugin("banner") M.state.fires = 0 -- M.state is smelt.state.get("banner") M.name == "banner"

After this call, bare smelt.state.get() also resolves to the named slot and unnamed resource constructors auto-name keyed by name. Idempotent within a single module body run: counters reset on every promotion so declaration order is what matters.

The handle deliberately doesn't wrap smelt.signal / smelt.cmd / smelt.keymap / smelt.lifecycle.* - those calls would not be scope-aware (signal/cmd names are global), so a method facade would imply encapsulation it can't deliver. Call them directly through smelt.* and namespace your signal/cmd names explicitly.

Must be called from a module body (or init.lua). Outside a loader frame (e.g. from an event callback) it raises immediately.

smelt.quit¶

fun(): nil

Tier: UiHost - Requires a terminal UI; calling these from headless mode raises.

Request a clean shutdown of the app. The quit fires on the next tick after the current handler returns.

smelt.sleep¶

fun(ms: integer): any

Tier: Host - Available in every runtime, including headless mode.

Sleep for ms milliseconds. Must be called from inside smelt.spawn(fn) or a tool.execute. Raises cancelled if the task is cancelled while parked.

smelt.spawn¶

fun(handler: fun()): smelt.Reg

Types: smelt.Reg

Tier: Host - Available in every runtime, including headless mode.

Run handler as a coroutine on the Lua task runtime. The handler may yield; its result is discarded. Returns a Reg whose :remove() cancels the task. Any in-flight smelt.sleep / smelt.task.wait raises cancelled and the coroutine unwinds. Spawns inherit the current task lifecycle; top-level spawns are app-scoped and survive agent-turn interrupts.