smelt.transcript¶

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

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.

Transcript display policy and rendered transcript inspection. Host-tier renderer hooks are layered with UiHost read APIs when a TUI is active.

smelt.transcript.extend_renderer¶

fun(name: string, renderer: fun(next: fun(block: smelt.transcript.Block, ctx: smelt.transcript.Context): table?, block: smelt.transcript.Block, ctx: smelt.transcript.Context): table?, opts: table?): smelt.Reg

Types: smelt.transcript.Block, smelt.transcript.Context, smelt.Reg

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

Add or replace named middleware around the root renderer. Later extensions run first. The callback receives (next, block, ctx) and may return its own layout or delegate with next(block, ctx). The returned Reg removes only this registration instance. Omit opts.cache_key to opt out of persisted DisplayIR while the middleware is active.

smelt.transcript.fold_all¶

fun(action: string): boolean

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

Apply a fold action (open or close) to every current transcript render node.

smelt.transcript.fold_at_row¶

fun(row: integer, action: string, opts: table?): boolean

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

Apply a fold action (toggle, peek, open, close) to the render node at absolute display row row. Pass { explicit = true } to require a collapsed summary/elision affordance row.

smelt.transcript.fold_kind¶

fun(kind: string, action: string): boolean

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

Apply a fold action (toggle, peek, open, or close) to every current block node with the given kind, e.g. thinking. toggle is aggregate: open all if any matching node is folded, otherwise close all.

smelt.transcript.fold_node¶

fun(node_id: table, action: string): boolean

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

Apply a fold action (toggle, peek, open, close) to a typed render node id returned by node_at_row(...).node_id.

smelt.transcript.get_renderer¶

fun(): (fun(block: smelt.transcript.Block, ctx: smelt.transcript.Context): table?)?

Types: smelt.transcript.Block, smelt.transcript.Context

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

Return the current composed root transcript renderer, or nil before the default renderer has been installed.

smelt.transcript.invalidate_renderer¶

fun(): integer

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

Bump the renderer generation after changing closed-over state that affects renderer output without calling set_renderer, extend_renderer, or a registration's :remove(). This also opts out of persisted DisplayIR until the renderer is installed again with a cache key.

smelt.transcript.is_empty¶

fun(): boolean

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

Return true when the transcript history holds no blocks (user, assistant, thinking, tool, exec, code, compacted). Reads transcript.history directly, so unlike loaded_blocks_expensive() it works before the first frame projects and is the right signal for empty-state plugins (logo splash, onboarding hints).

smelt.transcript.loaded_block_at_row¶

fun(row: integer): table?

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

Return the exact loaded transcript block containing absolute display row row, or nil when the row is outside a loaded block. This may materialize loaded-window block layout and returns { descriptor_index, block_id, role, first_row, rows, first_line }.

smelt.transcript.loaded_blocks_expensive¶

fun(): table

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

Return loaded transcript blocks as { descriptor_index, block_id, role, first_row, rows, first_line }. descriptor_index is the stable sparse descriptor index accepted by reveal_block. This may force layout for the loaded descriptor window; prefer visible_blocks() when possible.

smelt.transcript.loaded_text_expensive¶

fun(): string

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

Return the currently loaded transcript display text as a single newline-joined string. This is an explicit expensive materialization API; sparse sessions may only have the active descriptor window loaded. Prefer rows(start, count) for bounded display reads.

smelt.transcript.next_block¶

fun(opts: table?): table?

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

Return the nearest transcript block after the current viewport anchor, optionally filtered by opts.role, as { descriptor_index, block_id, role, first_line, already_at_top }. This uses descriptor/block identity, not estimated absolute rows.

smelt.transcript.node_at_row¶

fun(row: integer): table?

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

Return render-node metadata for absolute display row row, including { kind, id, node_id, block_id?, group_id?, index, first_row, rows, row_offset, view_state, explicit_fold_target }, or nil when outside the transcript. id/node_id is a stable typed table { kind = "block"|"group", id = number } accepted by fold_node.

smelt.transcript.previous_block¶

fun(opts: table?): table?

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

Return the nearest transcript block before the current viewport anchor, optionally filtered by opts.role, as { descriptor_index, block_id, role, first_line, already_at_top }. This uses descriptor/block identity, not estimated absolute rows.

smelt.transcript.reveal_block¶

fun(descriptor_index: integer, opts: table?): boolean

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

Reveal transcript descriptor block descriptor_index exactly, loading the sparse descriptor window around it if needed, with optional opts.top_padding and opts.cursor.

smelt.transcript.rows¶

fun(start: integer, count: integer): table

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

Return rendered transcript display rows in [start, start + count). This is exact for the requested absolute display-row range and materializes only the bounded range needed for the query.

smelt.transcript.set_renderer¶

fun(renderer: fun(block: smelt.transcript.Block, ctx: smelt.transcript.Context): table?, opts: table?): nil

Types: smelt.transcript.Block, smelt.transcript.Context

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

Replace the base transcript renderer used when the host asks Lua for a transcript block layout. Existing middleware registered with extend_renderer remains wrapped around the new base. The renderer must return a smelt.layout value; return smelt.layout.empty() to hide a block. Omit opts.cache_key to opt out of persisted DisplayIR, or bump it whenever renderer output changes across process restarts.

smelt.transcript.stream¶

fun(buf: smelt.buf.Buf, opts: smelt.transcript.StreamOpts?): smelt.transcript.Stream

Types: smelt.buf.Buf, smelt.transcript.StreamOpts, smelt.transcript.Stream

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

Create a transcript-shaped streaming renderer for buf. The returned object feeds deltas through the same incremental markdown parser and renderer used by the main transcript.

smelt.transcript.visible_blocks¶

fun(): table

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

Return transcript blocks materialized in the current visible projection as { descriptor_index, block_id, role, first_row, rows, first_line } entries. Unlike loaded_blocks_expensive(), this does not force loaded-window block layout beyond the visible projection.