smelt.prompt¶

Tier: Mixed - Contains both Host and UiHost functions; each function below lists its exact tier.

Classification: Supported - Primary alpha facade 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

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

── 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

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

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

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

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

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

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[]

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

Return the queued prompt text rows. Empty when the prompt is idle and no active turn, compaction, or busy work is in flight. Queue changes invalidate the retained top bar so waiting messages appear above the input.

smelt.prompt.queued_rows¶

fun(): table[]

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

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

Tier: Host - Available in every runtime, 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

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

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

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

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

smelt.prompt.text¶

fun(): string

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

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

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

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