smelt.prompt¶

Availability: Some functions need the terminal UI; each function below says which.

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

smelt.prompt.acquire¶

fun(): smelt.Reg

Types: smelt.Reg

Availability: Terminal UI only; raises in headless mode.

── 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.cursor¶

fun(pos: integer?): integer

Availability: Terminal UI only; raises in headless mode.

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

Availability: Terminal UI only; raises in headless mode.

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

Availability: Terminal UI only; raises in headless mode.

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.queued¶

fun(): string[]

Availability: Terminal UI only; raises in headless mode.

Return the queued prompt text rows, including while execution is paused. Queue changes invalidate the retained top bar so waiting messages remain visible above the input.

smelt.prompt.queued_rows¶

fun(): table[]

Availability: Terminal UI only; raises in headless mode.

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.register_completer¶

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

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

Availability: Everywhere, including headless mode.

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

smelt.prompt.replace_range¶

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

Availability: Terminal UI only; raises in headless mode.

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

Availability: Terminal UI only; raises in headless mode.

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

smelt.prompt.text¶

fun(): string

Availability: Terminal UI only; raises in headless mode.

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

Availability: Terminal UI only; raises in headless mode.

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