Struct TermHandle 

pub struct TermHandle { /* private fields */ }

A cloneable handle for mutating prompt zones from any thread.

Setters update the shared state but do not trigger a redraw. Call redraw after making all changes.

Implementations

impl TermHandle

pub fn request_input_shutdown(&self)

Requests that the prompt input loop stop and return EOF.

The input loop waits on an internal channel rather than polling, so a shutdown message is sent after the shared flag is set to wake any blocked receiver immediately. Blocking crossterm reads that are already in flight may finish later; their events are ignored after this flag is set.

pub fn request_completion_refresh(&self)

Requests a completion-source refresh without changing the prompt buffer.

The input owner recomputes the menu and redraws it, so background state updates never run completion code on their own threads.

pub fn completion_refresh_generation(&self) -> u64

Returns the generation that a background completion owner must preserve before requesting a guarded menu refresh.

pub fn request_completion_refresh_if_generation(&self, generation: u64)

Requests a completion refresh only if the input interaction still matches generation and no candidate is currently previewed.

pub fn with_redraw_suppressed<R>(&self, f: impl FnOnce() -> R) -> R

Run f while redraw notifications from this handle are suppressed.

Mutations remain visible in shared state, but redraw requests are marked dirty and coalesced into one notification after the outermost nested suppression scope exits. Use this to publish related visible-state changes as one coherent rendered frame.

pub fn suppress_redraws(&self) -> RedrawSuppressionGuard

Suppress redraw notifications until the returned owned guard is dropped.

Prefer Self::with_redraw_suppressed for one lexical operation. This owned form exists for bounded multi-message publication such as initial attachment catch-up.

pub fn with_output_transaction<R>(&self, f: impl FnOnce() -> R) -> R

Run f while terminal output snapshot mutations from other threads are blocked.

This transaction is intentionally narrower than the shared terminal-state mutex: callers can perform a multi-step snapshot swap using ordinary TermHandle methods without exposing the temporary snapshot to local output producers that own only a cloned handle.

pub fn redraw(&self)

Triggers a redraw of the terminal.

Call this after updating one or more blocks/zones. Multiple calls coalesce into a single repaint.

This goes through the differential update path — only the visible viewport is repainted. Use it for any mutation guaranteed to be inside the viewport (input, status chip, streaming live blocks, newly-printed blocks). For mutations to past blocks that may have scrolled into scrollback, use invalidate_screen instead. See README.md § “When mutations need a full redraw” for the full rule.

pub fn observe_presentation_mutation( &self, delivery_id: RendererDeliveryId, fact: OpaquePresentationFact, ) -> bool

Registers one completed selected-transcript mutation for flush correlation.

The caller must establish raw frontend-progress TRACE interest before calling. The delivery identity and caller-owned opaque label remain process-local and content-free. A caller whose typed opaque fact invalidates a visible predecessor must suppress redraw capture across both its presentation mutation and this registration. Returns true exactly when redraw capture was suppressed while the registration held shared terminal state; false means capture was not suppressed. The return value does not report notification delivery or eventual writer success.

pub fn clear_output(&self)

Drops every rendered block from every output zone and forces a full repaint. The prompt, current input buffer, and input-line history are left intact.

pub fn output_snapshot(&self) -> OutputSnapshot

Returns a clone of all output blocks/zones, excluding prompt input and prompt-history state.

pub fn output_snapshot_count(&self) -> u64

Returns how many full terminal output snapshots this handle has cloned.

This content-free counter supports frontend progress diagnostics and guards hidden-agent rendering against transcript-sized clone regressions.

pub fn take_output_snapshot(&self) -> OutputSnapshot

Transfers all output blocks and zones out of the visible terminal.

The returned snapshot owns the exact map and zone allocations formerly installed in the terminal. Prompt input and prompt history remain in the terminal. Callers must install another snapshot before allowing visible output mutations.

pub fn output_snapshot_take_count(&self) -> u64

Returns how many output snapshots this handle has transferred by ownership rather than cloned.

This content-free counter distinguishes selection handoffs from transcript-sized clone requests in frontend progress diagnostics.

pub fn replace_output_snapshot(&self, snapshot: OutputSnapshot)

Replaces all output blocks/zones, preserving prompt input and history.

pub fn replace_output_snapshot_quiet(&self, snapshot: OutputSnapshot)

Replaces all output blocks/zones without invalidating or redrawing. The caller must ensure the visible terminal still corresponds to the restored snapshot.

pub fn invalidate_screen(&self)

Forces the next redraw to take the full-render path: clear the visible screen + scrollback (\x1b[2J\x1b[H\x1b[3J) and re-emit the configured suffix of rendered history/log rows plus the fixed tail. Overflow naturally rebuilds recent terminal scrollback, but full-redraw plans intentionally omit rubber.

Use this when a mutation affects rows that may already be in terminal scrollback — e.g. toggling visibility of a block from a past turn (:set show-diff, :set show-thinking). The differential renderer only repaints the visible window, so without invalidation those scrolled-out rows would remain as stale fossils that disagree with current state. See README.md § “When mutations need a full redraw”.

pub fn size(&self) -> (usize, usize)

Current terminal size tracked by the renderer.

pub fn height(&self) -> usize

Current terminal height tracked by the renderer.

pub fn full_render_count(&self) -> u64

Number of full renders performed by the redraw thread since terminal creation. Temporary debugging aid for scrollback bugs.

pub fn redraw_history_size(&self) -> usize

Maximum number of rendered history/log rows replayed during a full redraw. usize::MAX preserves the historical unbounded behavior.

pub fn set_redraw_history_size(&self, redraw_history_size: usize)

Updates the maximum number of rendered history/log rows replayed during full redraw. This method only stores the value; callers decide whether to invalidate the screen immediately.

pub fn redraw_sync(&self)

Triggers a redraw and blocks until the redraw thread has processed it. Uses a generation counter: the caller bumps sync_requested, the redraw thread sets sync_completed atomically with going idle (right before blocking on recv).

After terminal output fail-stop, this returns immediately without requesting or retrying a redraw. The failed attachment can no longer promise that any terminal frame was delivered.

pub fn new_block( &self, debug_id: impl Into<String>, block: impl Into<StyledBlock>, ) -> BlockId

Allocates a new BlockId and stores the block.

pub fn set_block(&self, id: BlockId, block: impl Into<StyledBlock>)

Updates the content of an existing block (or inserts it at the given id).

pub fn set_block_with_presentation_delta( &self, id: BlockId, block: impl Into<StyledBlock>, ) -> bool

Updates a block and reports whether an already-rendered reference changed.

pub fn remove_block(&self, id: BlockId)

Removes a block from the central store and every zone that references it.

pub fn remove_block_with_presentation_delta(&self, id: BlockId) -> bool

Removes a block and reports whether any rendered zone referenced it.

pub fn push_history(&self, id: BlockId)

Appends a block id to the history (persistent output).

pub fn push_above_active(&self, id: BlockId)

Appends a block id to the above-active zone (if not already present).

pub fn push_above_active_with_presentation_delta(&self, id: BlockId) -> bool

Adds an active block and reports whether its rendered zone changed.

pub fn push_above_active_before_any<I>(&self, id: BlockId, anchors: I)

where I: IntoIterator<Item = BlockId>,

Inserts a block id into the above-active zone before the first matching anchor block, or appends it when none of the anchors are active.

Existing references to id are moved rather than duplicated. This keeps callers from rebuilding the whole output snapshot when they need a stable sub-order inside the bottom-anchored live block area.

pub fn push_above_active_before_any_with_presentation_delta<I>( &self, id: BlockId, anchors: I, ) -> bool

where I: IntoIterator<Item = BlockId>,

Reorders an active block and reports whether the rendered order changed.

pub fn remove_above_active(&self, id: BlockId)

Removes a block id from the above-active zone.

pub fn push_above_sticky(&self, id: BlockId)

Appends a block id to the above-sticky zone (if not already present).

pub fn remove_above_sticky(&self, id: BlockId)

Removes a block id from the above-sticky zone.

pub fn push_suggestions(&self, id: BlockId)

Appends a block id to the suggestions zone (if not already present). Rendered between the prompt and below blocks.

pub fn remove_suggestions(&self, id: BlockId)

Removes a block id from the suggestions zone.

pub fn push_below(&self, id: BlockId)

Appends a block id to the below zone (if not already present).

pub fn push_below_with_presentation_delta(&self, id: BlockId) -> bool

Adds a below-prompt block and reports whether its rendered zone changed.

pub fn remove_below(&self, id: BlockId)

Removes a block id from the below zone.

pub fn print_output( &self, debug_id: impl Into<String>, block: impl Into<StyledBlock>, ) -> BlockId

Creates a new block and appends it to the history. Triggers a redraw automatically.

pub fn set_left_prompt(&self, text: impl Into<StyledText>)

Updates the left prompt prefix.

pub fn get_buffer(&self) -> String

Returns a clone of the current input buffer.

pub fn enable_paste_uploads(&self, threshold: usize)

Enables large-paste interception for an application that handles uploads.

pub fn finish_paste_upload(&self, id: u64, result: Result<String, String>)

Delivers a content-free upload outcome to the sole editor input owner.

Success contains only the reference to insert, never original bytes. Late outcomes after cancellation or a later retry are ignored.

pub fn get_cursor(&self) -> usize

Returns the current cursor position in bytes.

pub fn get_buffer_revision(&self) -> u64

Returns the current monotonic editor revision.

pub fn last_submitted_buffer_revision(&self) -> Option<u64>

Returns the exact editor revision captured after the most recent raw line submission cleared the prompt.

pub fn set_buffer(&self, text: String, cursor: usize)

Replaces the input buffer and cursor position. Also clears any active history-navigation, completion menu, and prompt undo state — an external buffer set is treated as a fresh starting point.

pub fn set_buffer_if_revision( &self, expected_revision: u64, text: String, cursor: usize, ) -> bool

Replaces the input buffer only if no raw or external editor mutation has occurred since expected_revision.

pub fn recall_prompt_before_current(&self, text: String)

Recalls a queued prompt before the current draft, matching prompt-history navigation so pressing Down restores the draft that was present at recall time.

pub fn set_buffer_preserving_undo(&self, text: String, cursor: usize)

Replaces the input buffer and cursor position without clearing prompt undo history.

Use this after the caller has explicitly recorded the current prompt as an undo snapshot before launching an external picker. Active history navigation and completion are still closed because the replacement becomes the new editable draft.

pub fn completion_state(&self) -> Option<CompletionView>

Snapshot of the open completion menu, if any. Returns None when no menu is showing.

pub fn set_right_prompt(&self, text: impl Into<StyledText>)

Updates the right prompt.

pub fn set_input_placeholder(&self, text: impl Into<StyledText>)

Updates the placeholder shown when the input buffer is empty.

pub fn set_prompt_scroll_indicator(&self, enabled: bool)

Enables or disables the compact hidden-row indicator for capped prompt input.

pub fn print_terminal_bell(&self)

Queues a terminal bell to be written by the redraw thread on its next pass. Goes through the redraw loop so the byte never interleaves with an in-flight frame.

pub fn print_osc1337_set_user_var(&self, name: &str, value: &str, in_tmux: bool)

Queues an iTerm2 OSC 1337 SetUserVar side effect.

name must be non-empty printable ASCII, must not contain =, and must be at most 128 bytes. Invalid names are skipped and logged without echoing the invalid bytes. When in_tmux is true, the OSC is wrapped in a tmux passthrough DCS sequence so the outer terminal receives it.

value is base64-encoded before being written. Invalid name values are rejected and logged rather than emitted because OSC names are structural escape-sequence fields.

Trait Implementations

impl Clone for TermHandle

fn clone(&self) -> TermHandle

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.