App
Defined in: src/core/app.ts:62
Owns a running ztui application: the Driver, the screen stack, focus,
input dispatch, theming, and the frame scheduler. Construct one, render()
your tree onto activeScreen, then call run.
Extends
Section titled “Extends”Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new App(
driver?,options?):App
Defined in: src/core/app.ts:164
Parameters
Section titled “Parameters”driver?
Section titled “driver?”Backend to render through. Defaults to BunDriver (the terminal); pass WebDriver for the browser canvas or MockDriver for tests.
options?
Section titled “options?”pointerShapes?
Section titled “pointerShapes?”boolean
Drive the mouse-pointer shape from widget
cursor styles (default true); see App.pointerShapes.
Returns
Section titled “Returns”App
Overrides
Section titled “Overrides”Properties
Section titled “Properties”children
Section titled “children”children:
DOMNode[] =[]
Defined in: src/dom/dom.ts:16
Child nodes in document order.
Inherited from
Section titled “Inherited from”classes
Section titled “classes”classes:
Set<string>
Defined in: src/dom/dom.ts:10
Advisory class names (no CSS cascade today).
Inherited from
Section titled “Inherited from”driver
Section titled “driver”driver:
Driver
Defined in: src/core/app.ts:66
The backend this app renders through.
hotkeys
Section titled “hotkeys”
readonlyhotkeys:HotkeyRegistry
Defined in: src/core/app.ts:114
Global hotkey registry: named, grouped, context-scoped shortcuts. Priority (modified) keys dispatch before the focused widget; bare keys after the focus chain declined them — see the key handler in run.
id:
string=""
Defined in: src/dom/dom.ts:8
Optional stable identifier (from the id prop).
Inherited from
Section titled “Inherited from”
readonlyinput:AppInput
Defined in: src/core/app.ts:100
parent
Section titled “parent”parent:
DOMNode|null=null
Defined in: src/dom/dom.ts:14
Parent node, or null when detached / at the root.
Inherited from
Section titled “Inherited from”screenStack
Section titled “screenStack”screenStack:
Screen[] =[]
Defined in: src/core/app.ts:68
Screen stack; the top is the activeScreen.
tagName
Section titled “tagName”tagName:
string=""
Defined in: src/dom/dom.ts:12
Host element tag, lowercased (e.g. “ztui-button”).
Inherited from
Section titled “Inherited from”instance
Section titled “instance”
staticinstance:App|null=null
Defined in: src/core/app.ts:64
The most recently constructed App (convenience singleton; prefer widget.app).
Accessors
Section titled “Accessors”activeScreen
Section titled “activeScreen”Get Signature
Section titled “Get Signature”get activeScreen():
Screen
Defined in: src/core/app.ts:179
The screen on top of the stack — where render mounts the tree.
Returns
Section titled “Returns”buffer
Section titled “buffer”Get Signature
Section titled “Get Signature”get buffer():
ScreenBuffer
Defined in: src/core/app.ts:187
The most recently rendered frame buffer (read-only view). Exposed for inspection/testing — callers must not mutate it.
Returns
Section titled “Returns”framePipelineRunCount
Section titled “framePipelineRunCount”Get Signature
Section titled “Get Signature”get framePipelineRunCount():
number
Defined in: src/core/app.ts:465
Total render-pipeline runs so far (full or paint-only), regardless of whether they emitted. Tests diff this across an action to assert a frame ran — or, for a no-op, that none did.
Returns
Section titled “Returns”number
hoveredWidget
Section titled “hoveredWidget”Get Signature
Section titled “Get Signature”get hoveredWidget():
Widget|null
Defined in: src/core/app.ts:430
The widget currently under the pointer, or null. Read by the style pass (for
:hover) and the inspector; the live state is owned by AppInput.
Returns
Section titled “Returns”Widget | null
pointerShapes
Section titled “pointerShapes”Get Signature
Section titled “Get Signature”get pointerShapes():
boolean
Defined in: src/core/app.ts:145
Whether the app drives the mouse-pointer shape (OSC 22) from the hovered
widget’s cursor. On by default; set false to leave the pointer alone
(e.g. to cut passive-hover tracking on capable terminals). Turning it off at
runtime immediately resets the pointer to the terminal default. Has no
effect on terminals that don’t advertise TerminalCapabilities.pointerShapes.
Returns
Section titled “Returns”boolean
Set Signature
Section titled “Set Signature”set pointerShapes(
enabled):void
Defined in: src/core/app.ts:148
Parameters
Section titled “Parameters”enabled
Section titled “enabled”boolean
Returns
Section titled “Returns”void
Methods
Section titled “Methods”appendChild()
Section titled “appendChild()”appendChild(
child):void
Defined in: src/dom/dom.ts:23
Append child, detaching it from any previous parent.
Parameters
Section titled “Parameters”Returns
Section titled “Returns”void
Inherited from
Section titled “Inherited from”copyActiveSelection()
Section titled “copyActiveSelection()”copyActiveSelection():
string|null
Defined in: src/core/app.ts:412
Copy the active read-only selection (the true content value across every widget it spans, in document order — see ReadonlySelectionManager). Writes the clipboard and returns the text, or null when the selection is empty.
Returns
Section titled “Returns”string | null
describe()
Section titled “describe()”describe():
string
Defined in: src/dom/dom.ts:59
Human/LLM-readable identity for logs and diagnostics, e.g.
button#submit.primary @ (2,1 10x1). Includes the laid-out region when
one is present (widgets), and the text preview for text nodes.
Returns
Section titled “Returns”string
Inherited from
Section titled “Inherited from”getLastFrame()
Section titled “getLastFrame()”getLastFrame():
FrameSummary|null
Defined in: src/core/app.ts:456
The FrameSummary of the most recent render-pipeline run, or null before the first. For deterministic frame-scheduling tests — inspect it after flushing a frame to assert how the frame was scoped and whether it emitted.
Returns
Section titled “Returns”FrameSummary | null
getMouseDiagnostics()
Section titled “getMouseDiagnostics()”getMouseDiagnostics():
Record<string,number>
Defined in: src/core/app.ts:422
Returns
Section titled “Returns”Record<string, number>
getRenderReasonStats()
Section titled “getRenderReasonStats()”getRenderReasonStats():
Record<string,number>
Defined in: src/core/app.ts:418
Returns
Section titled “Returns”Record<string, number>
insertBefore()
Section titled “insertBefore()”insertBefore(
child,before):void
Defined in: src/dom/dom.ts:41
Insert child before the before sibling (appends if before isn’t found).
Parameters
Section titled “Parameters”before
Section titled “before”Returns
Section titled “Returns”void
Inherited from
Section titled “Inherited from”loadStyles()
Section titled “loadStyles()”loadStyles(
tcssContent):void
Defined in: src/core/app.ts:212
Load a TCSS stylesheet string (selectors + :hover/:focus rules) into the resolver.
Parameters
Section titled “Parameters”tcssContent
Section titled “tcssContent”string
Returns
Section titled “Returns”void
matchesSelector()
Section titled “matchesSelector()”matchesSelector(
selector):boolean
Defined in: src/dom/dom.ts:109
Match a compound selector against this node — tags, IDs, and classes (e.g. tag#id.a.b).
Parameters
Section titled “Parameters”selector
Section titled “selector”string
Returns
Section titled “Returns”boolean
Inherited from
Section titled “Inherited from”popScreen()
Section titled “popScreen()”popScreen():
void
Defined in: src/core/app.ts:203
Pop the top screen, returning to the one beneath (never empties the stack).
Returns
Section titled “Returns”void
pushScreen()
Section titled “pushScreen()”pushScreen(
screen):void
Defined in: src/core/app.ts:192
Push a screen onto the stack and make it active (e.g. a full-screen view).
Parameters
Section titled “Parameters”screen
Section titled “screen”Returns
Section titled “Returns”void
queueRender()
Section titled “queueRender()”queueRender(
reason?):void
Defined in: src/core/app.ts:329
Schedule a full re-render — restyle + measure + layout + paint — on the next microtask (coalesced). This is the safe default: call it after any state change that might affect sizes or structure.
Parameters
Section titled “Parameters”reason?
Section titled “reason?”string = "unknown"
Returns
Section titled “Returns”void
queueRepaint()
Section titled “queueRepaint()”queueRepaint(
region?,reason?):void
Defined in: src/core/app.ts:358
Schedule a paint-only re-render: restyle + paint, reusing the previous frame’s layout (regions/sizes). For high-frequency animations that change appearance but never geometry — the blinking caret above all — so an idle focused editor doesn’t relayout the whole tree ~17×/second. If anything calls queueRender in the same frame, the full path runs instead, so a repaint can never mask a real layout change.
Parameters
Section titled “Parameters”region?
Section titled “region?”{ bottom: number; y: number; } | null
reason?
Section titled “reason?”string = "unknown"
Returns
Section titled “Returns”void
queueRepaintWidget()
Section titled “queueRepaintWidget()”queueRepaintWidget(
widget,reason?):void
Defined in: src/core/app.ts:389
Repaint a single widget whose content changed, scoping the frame to its region — but only after a fresh layout confirms nothing moved. Unlike queueRepaint (caller asserts geometry is stable, e.g. the caret), this is safe for a change that might resize: the frame re-measures and re-lays out (cheap), and if any region shifted it transparently falls back to a full frame. When the layout is unchanged it re-renders only this widget’s subtree instead of the whole tree — the subtree-damage win.
Multiple widgets dirtied in one tick union their regions; a concurrent queueRender or an open overlay/selection escalates to full.
Parameters
Section titled “Parameters”widget
Section titled “widget”reason?
Section titled “reason?”string = "unknown"
Returns
Section titled “Returns”void
refresh()
Section titled “refresh()”refresh(
reason?):void
Defined in: src/core/app.ts:343
Force the next frame to re-emit every cell, even ones whose buffer
content is unchanged. Needed after a global that affects serialization but
not the cell data the per-cell diff compares — toggling colorMode
(NO_COLOR) or the terminal’s colour depth — where a normal
queueRender would find no changed cells and emit nothing.
Parameters
Section titled “Parameters”reason?
Section titled “reason?”string = "refresh"
Returns
Section titled “Returns”void
removeChild()
Section titled “removeChild()”removeChild(
child):void
Defined in: src/dom/dom.ts:32
Remove child if it’s a child of this node.
Parameters
Section titled “Parameters”Returns
Section titled “Returns”void
Inherited from
Section titled “Inherited from”run(
options?):void
Defined in: src/core/app.ts:219
Start the event loop: bind the driver, probe capabilities, and render frames.
Parameters
Section titled “Parameters”options?
Section titled “options?”inspectorPort?
Section titled “inspectorPort?”number
Returns
Section titled “Returns”void
stop()
Section titled “stop()”stop():
void
Defined in: src/core/app.ts:295
Stop the loop and restore the backend; releases timers, the inspector, and the singleton.
Returns
Section titled “Returns”void
walk()
Section titled “walk()”walk(
callback):void
Defined in: src/dom/dom.ts:83
Depth-first visit of this node and its descendants, in z-index (paint)
order — mirrors what’s actually drawn on top, for callers like
toAccessibleText(). z-index is a paint-only concept, so callers that
need tab/focus order (nothing to do with stacking) should use
walkDocumentOrder instead — otherwise a widget with a nonzero
z-index purely for painting (e.g. an overlapping decorative sibling)
jumps to a different position in the Tab sequence than where it
structurally sits.
Parameters
Section titled “Parameters”callback
Section titled “callback”(node) => void
Returns
Section titled “Returns”void
Inherited from
Section titled “Inherited from”walkDocumentOrder()
Section titled “walkDocumentOrder()”walkDocumentOrder(
callback):void
Defined in: src/dom/dom.ts:101
Depth-first visit of this node and its descendants in plain document order, ignoring z-index. Use for tab/focus order (e.g. Screen.getFocusableWidgets) — see walk’s doc comment for why z-index order is wrong there.
Parameters
Section titled “Parameters”callback
Section titled “callback”(node) => void
Returns
Section titled “Returns”void