runTuiApp function
Mounts app and returns its owning application lifecycle facade.
This is the whole entry point — void main() => runTuiApp(const MyApp());.
Dart's event loop keeps the process alive after main() returns, because
the stdin subscription and signal watchers own the lifetime; quitting means
disposing the app, not awaiting a future. Call TuiApp.exit from anywhere
in the tree to do that.
A real terminal auto-detects its own size and tracks resizes, so there is
no size to pass here; a non-TTY or headless run gets 80x24. Hosting a
custom canvas without a terminal is advanced work — use TuiBinding from
package:noir/noir_low_level.dart, which keeps its size parameters.
Pass enableMouse to turn on mouse reporting as the app mounts; the
returned handle still exposes runtime toggles. Movement reporting is enabled
for hover pointers; enableMouse(enableMovement: false) opts out. Hot reload
is registered automatically, so an edited build() shows up without extra wiring.
When onExitRequested is supplied, OS termination signals and unhandled
Ctrl+C notify it once with 130 (interrupt), 143 (terminate), or 129 (hangup).
Noir does not dispose or exit on this path. The application owns cancellation,
awaiting outstanding work, disposing the returned handle, and setting its
final exit code. This keeps asynchronous cleanup from being cut short.
The callback is invoked synchronously; Noir does not await asynchronous work
it starts. If it throws synchronously, Noir attempts best-effort terminal
cleanup and propagates the original error. Drive mode has no OS signal
subscriptions; handle its keys through TuiApp.onKey at app priority.
With NOIR_DRIVE=1 in the environment the app mounts in drive mode
instead: a headless binding painting into a non-terminal renderer, with the
ext.noir.driver.* service extensions published for an external driver.
Drive mode replaces the terminal session, so headless does not apply to
it; see createDriveModeHost. Without that variable the branch is inert
and this is the ordinary terminal path.
Implementation
TuiApp runTuiApp(
Widget app, {
bool headless = false,
bool enableMouse = false,
void Function(int exitCode)? onExitRequested,
}) {
final host = createDriveModeHost(io.Platform.environment);
if (host != null) {
try {
return _mount(
host.binding,
app,
enableMouse: enableMouse,
exitCodeSink: host.handleAppExit,
onMounted: host.start,
);
} on Object {
try {
// The binding borrows its renderer from this host, so mount rollback
// must also release the host's renderer and any started keep-alive.
host.dispose();
} on Object {
// The startup failure remains primary after every cleanup attempt.
}
rethrow;
}
}
if (headless && enableMouse) {
throw StateError('Mouse support requires a renderer');
}
return _mount(
TuiBinding(headless: headless, onExitRequested: onExitRequested),
app,
enableMouse: enableMouse,
onMounted: registerHotReloadExtension,
);
}