smelt.transcript¶

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.

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

fun(): nil

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

Jump the transcript to its semantic tail and enable tail-follow mode.

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

fun(name: string): smelt.transcript.ToolPresentation?

Types: smelt.transcript.ToolPresentation

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

Return a copy of the current presentation policy for name, or nil. Mutating the returned table has no effect; re-register the tool to change its presentation.

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 { record_index, block_id, role, first_row, rows, first_line }.

smelt.transcript.loaded_blocks_expensive¶

fun(callback: fun(value: table)?): table

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

Return loaded transcript blocks as { record_index, block_id, role, first_row, rows, first_line }. In sparse sessions, the no-callback form can return an empty table while background hydration is pending. Pass callback to receive the active loaded-window blocks once hydration completes without blocking Lua; the callback is retained for one invocation and the immediate return is an empty table. record_index describes sparse transcript ordering but is not a navigation handle; use committed view targets with reveal. Prefer visible_blocks() when possible.

smelt.transcript.loaded_text_expensive¶

fun(callback: fun(value: string)?): string

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

Return the currently materialized transcript display text as a single newline-joined string. In sparse sessions, the no-callback form can return an empty string while background hydration is pending. Pass callback to receive the active loaded-window text once hydration completes without blocking Lua; the callback is retained for one invocation and the immediate return is an empty string. Prefer rows(start, count) for bounded display reads.

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

fun(name: string, presentation: smelt.transcript.ToolPresentation): smelt.Reg

Types: smelt.transcript.ToolPresentation, smelt.Reg

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

Register or replace presentation policy for a tool. The supported fields are copied, so later table mutation has no effect; re-register to change behavior or cache keys. The returned registration removes only this exact replacement. Registering presentation changes rebuilds the composed root renderer so all cached standalone and grouped nodes invalidate.

smelt.transcript.reveal¶

fun(target: smelt.transcript.Target, opts: smelt.transcript.RevealOpts?): boolean

Types: smelt.transcript.Target, smelt.transcript.RevealOpts

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

Reveal a semantic transcript target returned by a committed view. Targets are validated against their originating session and block identity before sparse projection is changed. opts.align currently accepts top; opts.top_padding reserves rows above the target and defaults to zero; opts.move_cursor defaults to true.

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), materializing only the bounded range needed for the query. Rows inside an unloaded sparse gap are returned as empty strings until that region becomes the active hydrated window.

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

fun(): smelt.transcript.View?

Types: smelt.transcript.View

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

Return the latest committed transcript view, or nil before the first projection. The returned snapshot remains immutable; use watch_view to observe later revisions.

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 { record_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.

smelt.transcript.watch_view¶

fun(callback: fun(value: smelt.transcript.View)): smelt.Reg

Types: smelt.transcript.View, smelt.Reg

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

Observe committed transcript views. The callback runs after semantic projection has committed and before the frame is painted, receives one immutable View, and is called again only when observable view or navigation state changes. Returns a removable registration.