Module widgets 

Plugin widget runtime.

Plugins describe panels as a WidgetSpec tree. The runtime in this module owns the panel registry, runs the reconciler against the previous spec, renders the resulting tree into [TextPropertyEntry]s, and (in later phases) routes events back through the hook system.

v1 supports the Row / Col / HintBar / Raw widget kinds. Additional kinds (Toggle, Button, TextInput, List, Tree, Layer, Transient, Table) plug into the render dispatch without changing the IPC shape.

See docs/internal/plugin-widget-library-design.md for the full design.

Structs

EmbedRect

A rectangle reserved by a WindowEmbed widget. All coordinates are in display columns (not bytes), so the host can map straight to screen cells via inner.x + col_in_row. width_cols is the column count; height_rows matches the spec’s rows. The host’s floating-panel render walks these and invokes the per-window paint path scoped to the rect.

FocusCursor

Where the host should place the buffer’s hardware cursor — the terminal’s blinking caret — when a TextInput is focused. Built by the renderer; the dispatcher translates (buffer_row, byte_in_row) to an absolute byte position in the virtual buffer and sets the panel buffer’s primary cursor there. When a non-text widget is focused (Toggle / Button / List) or the panel has no tabbable widgets, this is None and the host hides the cursor entirely.

HitArea

One clickable rectangle within a rendered widget panel.

OverlayRow

One row produced by an Overlay widget. buffer_row is the 0-based row inside the panel’s inner area where the entry should be painted; the host’s paint pass writes overlay rows after the main entries so they sit on top.

RenderOutput

What a single render of a WidgetSpec produces.

ScrollRegion

A scrollable List widget’s geometry + scroll state, surfaced so the host can paint a draggable scrollbar over the list’s rightmost column and hit-test mouse press/drag against it. Threaded through the compositor (Row/Col/Section) identically to EmbedRect — buffer_row/col_in_row are panel-relative display coordinates. width_cols spans the list’s column so col_in_row + width_cols - 1 is the scrollbar column; height_rows is the visible track height. total/visible/scroll feed ScrollbarState.

WidgetPanelState

Per-panel state retained between renders. The reconciler will use the previous spec to compute the minimum mutation when a future UpdateWidgetPanel arrives.

WidgetRegistry

Global registry of mounted widget panels.

Enums

WidgetInstanceState

Widget instance state retained across spec updates, keyed by the widget’s stable key. This is the “Spec/instance separation” described in §6 of the design doc — a plugin can rebuild its WidgetSpec from scratch on every model change without losing scroll offset, cursor position, expanded keys, or focus, because stateful widgets look up their instance state by key.

Functions

append_tree_nodes_in_spec

Append new_nodes (and their item keys) to an existing Tree’s node list, preserving everything already present. Returns true when a matching Tree was found and extended.

find_widget_by_key

Locate a widget node in a spec tree by its stable key. Returns the matched node, or None if no widget has that key.

render_spec

Render a spec to a RenderOutput.

render_spec_no_autofocus

Like render_spec but does not fall back to focusing the first tabbable widget when focus_key matches none. Use this when the host owns the focus ring and a state of “no widget focused” is meaningful — e.g. the search overlay, where focus can rest on the input (no toggle highlighted) rather than always on a toolbar control. Pass "" for no focus.

set_list_items_in_spec

In-place mutate a List’s items and item_keys fields. Returns true when a matching List was found and updated.

set_raw_entries_in_spec

Replace a Raw widget’s entries in place. Returns true when a matching Raw was found and updated.

set_toggle_checked_in_spec

In-place mutate a Toggle’s checked field by walking the spec tree and matching on widget_key. Used by the WidgetMutate::SetChecked IPC fast path.

set_tree_checked_keys_in_spec

Stamp Some(checked) onto every TreeNode whose item-key appears in keys. Used by WidgetMutation::SetCheckedKeys — the host writes the new checkbox state into the spec so the next render reflects it without round-tripping through the plugin. Nodes not in keys are unchanged. Nodes whose existing checked is None are left as None (a node only becomes checkable by the plugin emitting Some(_) in the spec).

set_tree_nodes_in_spec

In-place mutate a Tree’s nodes and item_keys fields. Returns true when a matching Tree was found and updated.

tree_parent_index

Resolve the absolute nodes index of the parent of child_idx in a Tree. The parent of a node at depth d is the most recent earlier node at depth d - 1. Returns None for top-level nodes (depth 0) and for out-of-range indices.

Type Aliases

PanelId

Plugin-allocated panel identifier. Unique within a plugin; the editor does not interpret the value.