smelt.prompt¶

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

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

The main editable input surface: win handle, text get/set, and cursor control. UiHost-only.

smelt.prompt.acquire¶

fun(): smelt.Reg

Types: smelt.Reg

── Modality lock ─────────────────────────────────────────────────────── Take a modality lock on the prompt area so completers/pickers don't pop while the caller owns the screen. Returns a Reg whose :remove() releases the lock; the last release re-runs the recompute pass. Idempotent - multiple acquirers stack.

smelt.prompt.completer¶

fun(spec: smelt.prompt.CompleterSpec|smelt.prompt.MatchesCompleterSpec): smelt.Reg

Types: smelt.prompt.CompleterSpec, smelt.prompt.MatchesCompleterSpec, smelt.Reg

Register a completer spec. Returns a Reg whose :remove() unregisters the completer and closes the picker if it was active.

smelt.prompt.cursor¶

fun(pos: integer?): integer

Read or write the prompt cursor as a byte offset into text(). Without an argument returns the current offset; with one snaps it to a char boundary and clamps to source length. Returns the resulting offset.

smelt.prompt.has_stash¶

fun(): boolean

Return whether the prompt currently holds a stashed input snapshot (Ctrl+S). The top-bar renderer uses this to surface a ◌ Stashed (ctrl+s to unstash) row.

smelt.prompt.is_modal¶

fun(): boolean

True while at least one smelt.prompt.acquire() lock is outstanding. Plugins read this to skip non-blocking work that would race the modal owner.

smelt.prompt.open_picker¶

fun(opts: smelt.prompt.PickerOpts): table?

Types: smelt.prompt.PickerOpts

Prompt-docked picker. Filters opts.items (or opts.items()) against the current prompt buffer on every keystroke, ranked by opts.rank or smelt.fuzzy.rank; alternatively opts.provider(query, limit) may return the shared provider result shape { items, searching?, scanning?, message?, status? }. Pass opts.on_select for the per-navigation hook; pass opts.on_enter to switch to persistent mode (the picker stays open across selections until Esc). Returns { action, item, index } on accept or nil on dismiss (single-shot mode). Must run inside a smelt.spawn frame.

smelt.prompt.queued¶

fun(): string[]

Return the queued prompt text rows. Empty when the prompt is idle and no active turn, compaction, or busy work is in flight. The top-bar renderer reads this each frame to surface waiting messages above the input.

smelt.prompt.queued_rows¶

fun(): table[]

Return queued prompt rows as { text, kind } tables. kind is request for rows added to the current turn's next request, or turn for rows waiting for the next turn.

smelt.prompt.replace_range¶

fun(start: integer, end: integer, text: string): integer

UTF-8-safe replace of the byte range [start, end) in the prompt with text. Endpoints are snapped to char boundaries and clamped to source length. The cursor lands at start + #text. Returns the new cursor offset.

smelt.prompt.set_text¶

fun(text: string): nil

Replace the prompt buffer with text. The cursor lands at the end and undo state is reset.

smelt.prompt.text¶

fun(): string

Return the prompt input buffer's current text. Internal attachment markers are stripped - plugins see only the user-visible characters.

smelt.prompt.win¶

fun(): smelt.win.Win

Types: smelt.win.Win

Return a Win handle for the prompt input. Use win:key(...) and win:on(...) to attach plugin behaviour.