runTuiApp function

TuiApp runTuiApp(
  1. Widget app, {
  2. bool headless = false,
  3. bool enableMouse = false,
  4. void onExitRequested(
    1. int exitCode
    )?,
})

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,
  );
}