These docs describe the main branch, including unreleased changes. Read the 0.7.0 docs.

OpenTUI 0.7.0

2026-10-25npm GitHub release

Before 0.7.0, typing one character in a 10,000-line Textarea laid out all 10,000 lines before the key call returned, and the Yoga measure of the next frame walked them again. Typing and pasting slowed down with the size of the document, and word wrap paid the most. In 0.7.0, an edit only records that the view must scroll to the cursor. The layout runs once, at the next read of the viewport or the visual cursor, or at the next frame. It compares the text with the text of the last layout and lays out only the lines around the change. An insert, a delete, an undo, or a join lays out one line. Enter lays out two lines, and a 100-line paste lays out 101.

A read that needs the layout still pays for it. visualCursor lays out the text when an edit is pending. cursorOffset reads the logical cursor and does not lay out the text. To check after each key whether the cursor is at the start of the text, compare cursorOffset:

const atStart = input.cursorOffset === 0 // not input.visualCursor.offset === 0

Before 0.7.0, Renderable found the hooks of each node by reflection. It scanned the property descriptors of every new instance two times. For 10,000 rows of a Text subclass that overrides renderSelf, this took 20,000 scans and 160,000 descriptor reads. Now a node reads its hooks from its class once, at construction. Prototype methods with super, constructor options, and assignments to renderBefore, renderAfter, onLifecyclePass, and onSizeChange work as before.

Three kinds of code must change. First, a hook that you add by reflection does nothing until you call node.refreshHooks(). Examples are an instance class field, Object.defineProperty(), or an assignment to the renderSelf or onUpdate of one node. Second, a patch or spy on a prototype method after nodes exist does not reach those nodes, and untyped JSX props such as onUpdate and onResize have no effect. Third, renderBefore, renderAfter, and onLifecyclePass are now accessors. A class field that overrides one of them is a TypeScript error, so assign the hook in the constructor. An onLifecyclePass class field still runs, because attaching the node registers it.

import { BoxRenderable, RGBA, type BoxOptions, type RenderContext } from "@opentui/core"

class MarkedBox extends BoxRenderable {
  constructor(ctx: RenderContext, options: BoxOptions) {
    super(ctx, options)
    this.renderAfter = (buffer) => {
      buffer.drawText("*", this.screenX, this.screenY, RGBA.fromInts(255, 0, 0))
    }
  }
}

A class that used defineNativeIntegration() must now declare the description directly. Without the type annotation, kind does not keep its literal type:

import { Renderable, type NativeRenderableIntegration } from "@opentui/core"

class Marker extends Renderable {
  static override readonly nativeIntegration: NativeRenderableIntegration = {
    kind: "custom",
    body: "host",
  }
}

The nativeSceneWorkBudget renderer option let a frame yield to the event loop during native preparation. OpenTUI, its SSH package, and OpenCode did not set it. On a 10,000-line log, it cut the longest native slice by about 0.15 ms but used 27% more native time. With one mutation per event-loop turn, each yield started preparation again, until the frame failed with LayoutLimit. A renderer that scrolled or streamed under a budget showed no frames. Now preparation and paint finish in one call. A C binding built against the old header passes every argument after the removed max_work_items one slot off, so the ABI version changes. To update a binding, generate it again from the new opentui.h. Then remove the max_work_items argument and any OT_SCENE_FRAME_YIELD case, and use the 224-byte ot_scene_stats record. The work_budget of ot_session_pump is a different budget and does not change.

0.7.0 also adds a native input parser. The TypeScript parser parses each framed unit again with regular expressions, and its structure caused bugs that are hard to fix in place. These bugs include lost Escape-prefixed events, empty Alt key names, wrong Alt keys for non-ASCII characters, wheel releases that ended drags, and negative X10 coordinates. The native parser is a bounded state machine that does not allocate, and it handles all of these cases. It is off by default while timing and buffering edge cases are tested. To try it, set OTUI_NATIVE_INPUT_PARSER=1 or create the renderer with the option:

const renderer = await createCliRenderer({ experimental_nativeInput: true })

With OTUI_NATIVE_INPUT_SHADOW=1, the renderer also runs the other parser. It writes a [stdin-shadow] warning for each event that the two parsers report differently. The warnings contain your input, so protect them as you would a stdin log. To report a parser bug, include a log from OTUI_STDIN_LOG. The native parser is bounded, so it ignores stdinParserMaxBufferBytes.

Known issue: when the terminal hangs up, as when an SSH connection closes, the renderer prints Error disabling raw mode and Native scene shutdown failed errors with stack traces to stderr. The process still exits with code 0.

Breaking changes

Added

core: The experimental_nativeInput renderer option, or OTUI_NATIVE_INPUT_PARSER, parses stdin with a new native parser. OTUI_NATIVE_INPUT_SHADOW runs both parsers and logs each event that they report differently. See Environment variables. (#1592, #1787)
native: ot_session_input_feed() parses terminal input into caller-owned ot_input_event records, a payload buffer, and an ot_input_drain summary, and it does not allocate. ot_session_input_expect() sets the replies that the parser expects, and ot_session_input_reset() clears the parser state. FFIRenderLib.sessionInputFeed(), sessionInputExpect(), and sessionInputReset() wrap them. See Host I/O and time. (#1592)
core: getNativeStats().frameWork, also in getStats(), counts the work of the last presented scene frame, such as Yoga solves, view preparations, and painted cells. The test renderer option nativeSceneFullFrame makes each frame rebuild its work lists, so tests can compare the counts. See Rendering diagnostics. (#1722)
native: ot_scene_stats reports the work of the last presented scene frame. ot_scene_set_debug_flags() with OT_SCENE_DEBUG_FULL_FRAME forces the full frame path, and full_path_reasons uses the OT_SCENE_FULL_PATH_* bits. See Frames and output. (#1722)
core: The protected _paintWidth and _paintHeight of Renderable give the size that a renderSelf() paints, clamped to the cell range that drawing accepts. See Custom renderables. (#1682)

Changed

Fixed

API changes#

`@opentui/core`#

Added

method FFIRenderLib.sessionInputExpect(context: NativeContextHandle, session: SessionHandle, flags: number): void
method FFIRenderLib.sessionInputFeed(context: NativeContextHandle, session: SessionHandle, bytes: Uint8Array, nowNs: bigint, records: Uint8Array, payload: Uint8Array): NativeInputDrain
method FFIRenderLib.sessionInputReset(context: NativeContextHandle, session: SessionHandle, flags: number): void
property CliRendererConfig.experimental_nativeInput?: boolean
protected readonly property Renderable._paintHeight: number
protected readonly property Renderable._paintWidth: number

Changed

function detectLinks(chunks: TextChunk[], context: { content: string; highlights: SimpleHighlight[]; sourceRanges?: Array<{ start: number; end: number; }>; }): TextChunk[]function detectLinks(chunks: TextChunk[], context: { content: string; highlights: SimpleHighlight[]; sourceRanges?: Array<{ start: number; end: number; }>; syntaxStyle?: SyntaxStyle; }): TextChunk[]
method FFIRenderLib.sceneFrameStep(context: NativeContextHandle, session: SessionHandle, previous: NativeSceneFrameRequest | null, options: NativeSceneFrameOptions, maxWorkItems?: number, recording?: Uint8Array | null): NativeSceneFrameRequestmethod FFIRenderLib.sceneFrameStep(context: NativeContextHandle, session: SessionHandle, previous: NativeSceneFrameRequest | null, options: NativeSceneFrameOptions, recording?: Uint8Array | null): NativeSceneFrameRequest
property Renderable.renderAfter?: (this: Renderable, buffer: OptimizedBuffer, deltaTime: number) => voidproperty Renderable.renderAfter: PaintHook | undefined
property Renderable.renderBefore?: (this: Renderable, buffer: OptimizedBuffer, deltaTime: number) => voidproperty Renderable.renderBefore: PaintHook | undefined
type NativeRenderStats = { nativeLastFrameTime: number; nativeAverageFrameTime: number; nativeFrameCount: number; cellsUpdated: number; averageCellsUpdated: number; nativeRenderTime?: number; nativeStdoutWriteTime?: number; }type NativeRenderStats = { nativeLastFrameTime: number; nativeAverageFrameTime: number; nativeFrameCount: number; cellsUpdated: number; averageCellsUpdated: number; nativeRenderTime?: number; nativeStdoutWriteTime?: number; frameWork: NativeFrameWork; }

Removed

enum-member NativeSceneFrame.Yield
static protected method Renderable.defineNativeIntegration(integration: NativeRenderableIntegration): NativeRenderableIntegration
property CliRendererConfig.nativeSceneWorkBudget?: number
readonly property NativeRenderableIntegration.construction?: "prototype" | "fields"
property NativeSceneFrameRequest.geometryRevision?: number
protected property TextBufferRenderable._textBufferSyntaxStyle: SyntaxStyle

`@opentui/core/testing`#

Added

property TestRendererOptions.nativeSceneFullFrame?: boolean

`opentui.h`#

Added

Changed

const OT_CONTEXT_ABI_VERSION = 1const OT_CONTEXT_ABI_VERSION = 2
function ot_scene_frame_step_with_geometry(ot_context *, const ot_handle *session, const ot_scene_frame_request *previous, const ot_scene_frame_options *, uint32_t max_work_items, const uint8_t *recording, uint32_t recording_length, ot_scene_frame_request *out_request, ot_scene_frame_geometry *out_geometry): ot_statusfunction ot_scene_frame_step_with_geometry(ot_context *, const ot_handle *session, const ot_scene_frame_request *previous, const ot_scene_frame_options *, const uint8_t *recording, uint32_t recording_length, ot_scene_frame_request *out_request, ot_scene_frame_geometry *out_geometry): ot_status

Removed

const OT_SCENE_FRAME_YIELD = 5

OpenTUI 0.7.0

Breaking changes

Added

Changed

Fixed

API changes#

@opentui/core#

@opentui/core/testing#

opentui.h#

`@opentui/core`#

`@opentui/core/testing`#

`opentui.h`#