Overview
TheKraken class is the main entry point for Kraken TUI applications. It manages:
- Application lifecycle (initialization and shutdown)
- Root widget mounting
- Event loop execution
- Focus management
- Terminal state queries
- Developer-assigned widget IDs
- Performance counters
- Animation choreography
Always call
shutdown() to restore terminal state, even if errors occur. Use try/finally blocks.Initialization
init()
Initialize the TUI system in normal terminal mode. Enters alternate screen, raw mode, and captures mouse input.A new Kraken instance with the TUI system initialized.
initHeadless()
Initialize the TUI system in headless mode (no terminal needed). Useful for testing and server-side rendering.Virtual terminal width in columns.
Virtual terminal height in rows.
A new Kraken instance in headless mode.
shutdown()
Shut down the TUI system and restore the terminal to its original state. Clears all internal state.Widget Tree
setRoot()
Set the root widget of the composition tree. This widget and its descendants will be rendered.The widget to use as the tree root.
Event Loop
run()
Run the application event loop. Resolves whenstop() is called. Does not call shutdown() automatically.
Configuration for the event loop.
Loop mode:
"onChange": Renders only when work exists (input, animations, dirty nodes)"continuous": Runs at fixed FPS regardless of activity
Target frames per second for continuous mode or animation bursts.
Input poll timeout in milliseconds when idle in onChange mode.
Callback invoked for each drained event.
Callback invoked each tick after events are drained, before render.
Enable debug logging to stderr.
Disable automatic dispatch to JSX event handler props.
stop()
Signal the event loop to stop after the current tick. Safe to call from event handlers or external async code.readInput()
Read terminal input and buffer events. Does not return the events directly; usedrainEvents() to retrieve them.
Timeout in milliseconds:
0: Non-blocking (return immediately)> 0: Block up to N milliseconds waiting for input
Number of events buffered by this call.
drainEvents()
Drain all buffered events. Events are removed from the internal buffer and returned as an array.Array of events drained from the buffer.
render()
Execute the full render pipeline: layout computation, diff, and terminal I/O.The
run() method calls this automatically. Only needed for manual event loops.Terminal Queries
getTerminalSize()
Get the current terminal dimensions.Object containing terminal dimensions:
width: Terminal width in columnsheight: Terminal height in rows
Focus Management
getFocused()
Get the handle of the currently focused widget.Widget handle of the focused widget, or
0 if nothing is focused.focusNext()
Advance focus to the next focusable widget in tree order.focusPrev()
Move focus to the previous focusable widget in tree order.Widget IDs
setId()
Register a developer-assigned string ID for a widget. Useful for focus management and programmatic access.Developer-assigned identifier.
Widget to associate with the ID.
getHandle()
Get a widget handle by developer-assigned ID.Developer-assigned identifier.
Widget handle, or
undefined if the ID is not registered.Theme Management
switchTheme()
Apply a theme to the current root widget. Shorthand fortheme.applyTo(root).
Theme to apply.
Animation Choreography
chainAnimation()
Chain animation B to start when animation A completes. Cancelling A prevents B from auto-starting.Animation handle that triggers the next animation.
Animation handle to start when the first completes.
createChoreoGroup()
Create a choreography animation group for coordinating multiple animations on an absolute timeline.Choreography group handle.
choreoAdd()
Add an animation to a choreography group at a specific timeline offset.Choreography group handle.
Animation to add to the group.
Absolute timeline offset in milliseconds.
startChoreo()
Start a choreography group timeline.Choreography group handle.
cancelChoreo()
Cancel a running choreography group and all its animations.Choreography group handle.
destroyChoreoGroup()
Destroy a choreography group handle and free its resources.Choreography group handle.
Debug & Performance
setDebug()
Enable or disable debug logging to stderr.Whether to enable debug logging.
getPerfCounter()
Query a performance counter by ID.Performance counter ID.
Current value of the performance counter.
getNodeCount()
Get the total number of nodes in the widget tree.Total node count.
RunOptions Interface
Loop mode.
"onChange" renders only when work exists (default). "continuous" runs at fixed fps.FPS target for continuous mode or animation bursts in onChange mode.
Input poll timeout (ms) when idle in onChange mode.
Called for each drained event.
Called each tick after events are drained, before render.
Enable debug overlay (wires setDebug).
Disable automatic dispatch to JSX event handler props.