React-Ink Widgets

indusagi.react_ink is the terminal-UI component library for the coding agent — a streaming markdown renderer, a colored structured-diff view, twelve focus-trapping modal dialogs, per-role chat widgets, chrome (Footer, StatusLine, TaskPanel), a theme adapter, and a set of framework-free helper modules. Built on Textual + Rich. Imported as import indusagi.react_ink.

The package surface re-exports every widget and helper from its snake_cased submodules so each symbol can be reached from the top level. The pure logic lives in three framework-light subpackages — diff/, markdown/, and utils/ — while the on-screen surfaces live under components/. Chat data flows from the UI Bridge as a SessionSnapshot into MessageList, Footer, StatusLine, TaskPanel, and StreamingMarkdown, and dialogs are pushed onto the Shell App as Textual ModalScreens.

Table of Contents

• Layout
• View-model types
• Theme adapter
• Markdown stream
• Diff view
• Message list and per-role widgets
• Chrome widgets
• The twelve dialogs
• Pure helpers
• Relationship to neighbors

Layout

Three layers under indusagi/react_ink/:

The pure subpackages (diff.structured, diff.word_diff, and all of utils/) import no textual or rich. Importing the top-level indusagi.react_ink package does pull in Textual/Rich because the widget modules need them; import from the subpackages directly when you only want the logic.

Two modules are deliberately not re-exported at the package top level: components.editor (PromptEditor) and the session-browser engine utils.session_browser (reachable via indusagi.react_ink.utils). Where the same name is exported by two modules, the package resolves to the defining module: status_marker / split_visible_lines / clamp_content_lines come from components.tool_event, and VISIBLE_SESSION_COUNT / build_session_metadata come from components.dialogs.session.

View-model types

types.py is the UI vocabulary. Every chrome widget renders from a single immutable SessionSnapshot; the rest are frozen data carriers and type aliases.

Type aliases include StatusKind, ToolExecutionStatus, LoginAuthKind, and PendingMessageMode. Field names mirror the TypeScript ground truth verbatim (tool_call_id, is_streaming, updated_at, cache_read) and most dataclasses are frozen=True, slots=True. The agent and AI imports (AgentMessage, Model, the auth prompt types) sit under TYPE_CHECKING to keep types.py dependency-light.

Theme adapter

theme_adapter.py projects one flat host palette (Mapping[str, str]) onto three consumers. create_theme_bundle packs all three into a ThemeBundle.

Role resolution is a role-key → fallback-key → text-fallback dict lookup (DEFAULT_ROLE_KEYS, ROLE_FALLBACK_KEYS). Degradation is deliberate: invalid colors are caught via Rich's ColorParseError, and non-hex colors simply drop out of the Pygments style.

from indusagi.react_ink import create_theme_bundle

bundle = create_theme_bundle("midnight", {
    "text": "#e5e5e7",
    "background": "#1e1e2e",
    "diffAddedBg": "#1b3a2a",
    "diffRemovedBg": "#3a1b1b",
})
app.register_theme(bundle.theme)            # textual.theme.Theme
text = bundle.adapter.role("assistant", "hello")   # rich.text.Text

Markdown stream

The markdown stack renders both settled history and live streaming turns.

A streaming assistant turn calls await write(delta) per chunk and await settle() once the turn ends. write prepends the held suffix from the previous delta so prompt-XML tags are always stripped whole, then enqueues the safe portion on the stream (which coalesces bursts internally — settled blocks never re-render). settle flushes any held suffix as literal text and stops the stream task; the widget keeps the full document as the permanent history entry. asyncio.CancelledError is never swallowed.

from indusagi.react_ink import StreamingMarkdown

view = StreamingMarkdown()
await view.mount()  # inside a Textual app
async for delta in channel:        # gateway text deltas
    await view.write(delta)
await view.settle()

Helpers has_markdown_syntax, get_list_number, pad_aligned, and string_width are pure; constants BLOCKQUOTE_BAR, PROMPT_XML_TAG_NAMES, and Alignment ship alongside.

Diff view

diff/ is a structured-patch engine plus its renderer.

build_structured_diff(old_str, new_str, file_path="") walks the raw hunk lines into typed DiffLines carrying gutter line numbers, then pairs adjacent removed→added runs index-for-index and hands them to word_diff_line so the renderer emphasizes only the changed sub-range of each line. file_path is accepted for signature parity only. The diff engine uses difflib (Ratcliff-Obershelp) rather than a Myers diff, so hunk boundaries can differ on adversarial input; tests/react_ink/test_diff.py is the declared arbiter.

from indusagi.react_ink import build_structured_diff, DiffView

diff = build_structured_diff("line one\nold\n", "line one\nnew\n", "x.py")
if diff is not None:
    panel = DiffView(diff)   # mount in a Textual app

Message list and per-role widgets

The transcript is an anchored, append-only VerticalScroll reconciled by a stable entry key, so settled history never re-renders.

group_messages/visible_entries/entry_keys group each tool-calling assistant message with its following toolResult run, merge UiDisplayBlocks, and sort by timestamp; MessageList.sync then reconciles mounted rows by stable key. create_message_row dispatches each AgentMessage by role (user / assistant / toolResult / bash / branch / compaction / custom) to the matching widget. Most widgets ship a pure build_*_text(message, theme) renderer returning Rich Text: build_user_message_text, build_bash_text (+bash_status), build_compaction_text, build_branch_summary_text, build_custom_text, build_skill_invocation_text.

Chrome widgets

Persistent UI surfaces driven by the snapshot.

ToolCallMessage subclasses ToolEventBlock; TaskPanel keeps private status_marker/split_visible_lines/clamp_content_lines variants while the top-level package re-exports the tool_event originals.

The twelve dialogs

All dialogs are Textual ModalScreens pushed via app.push_screen and resolved with dismiss(result). DialogFrame and SelectableDialog are the reusable base; WrapCursorMixin gives wrap-around cursors. The dialogs package uses lazy importlib re-export so importing the group-A pickers never pulls in the group-B auth dialogs.

ModelDialog, ThemeDialog, SettingsDialog, and ScopedModelsDialog are the group-A pickers built on SelectableDialog; LoginDialog, OAuthDialog, SessionDialog, StartupSessionPicker, TreeDialog, and UserMessageDialog are the group-B auth/navigation modals.

from indusagi.react_ink import ModelDialog

chosen = await app.push_screen_wait(ModelDialog(snapshot.model))
if chosen is not None:
    ...  # the dialog resolves via dismiss(result)

Pure helpers

Framework-free logic in utils/. These feed the widgets and dialogs.

A ToolCardDescriptor can carry a StructuredDiff, which DiffView draws. The session-browser names (ParsedSearchQuery, SearchToken, SessionFilterResult, SessionBrowserProgress, and the functions above) are exported from indusagi.react_ink.utils rather than the package root.

Relationship to neighbors

react_ink is the presentation layer of the rebuild. It depends on Agent for AgentMessage, ToolCall, and the role-specific message types, and on AI for Model, the auth prompt types, and the model catalog that backs ModelDialog. It is driven by the UI Bridge, which builds a SessionSnapshot per agent event and pushes the dialogs onto the Shell App. The theme adapter registers its Theme and Pygments style with the Textual app and shares the host-palette layer described in TUI. session_browser backs SessionDialog/StartupSessionPicker against the Runtime sessions subsystem, and the login/oauth dialogs drive the auth subsystem.

Back to the Architecture overview.