Muse

Muse is a Flutter-like terminal UI framework built on OpenTUI via Dart FFI, providing declarative widgets, terminal-first layout, focus management, animations, and native buffer APIs familiar to Flutter developers.

A declarative widget framework with StatelessWidget, StatefulWidget, BuildContext, and setState.
Terminal-first layout primitives such as Row, Column, Container, Padding, SizedBox, Align, Flexible, and Expanded.
Shared framework services including focus, pointer routing, inherited dependencies, diagnostics, and animations.
Native OpenTUI bindings, packaged binaries, and low-level buffer/renderer APIs for direct use when needed.

The repo is the development home for the framework and is preparing its first development release on pub.dev as muse.

Current Status

Core framework work is in place:

runTuiApp is the primary application entry point and returns a TuiBinding lifecycle handle
Layout, styling, focus/input routing, inherited state, diagnostics, and animation scaffolding are implemented
Analyzer and test coverage are in active use for framework changes
Packaged native binaries are checked in under native/
Local Go parity exists for primitive scenes; widget parity is the next active lane

Quick Start

Clone the repo and install Dart dependencies:

dart pub get

Run a few representative examples:

dart run example/hello.dart
dart run example/layout_demo.dart
dart run example/focus_form.dart
dart run example/pulse_animation.dart

Run the baseline validation commands:

dart analyze
dart test

Example Apps

Static rendering and animation:

example/hello.dart — minimal rendering
example/counter.dart — stateful rebuilds
example/layout_basics.dart — core layout tour
example/layout_demo.dart — richer flex/alignment/decorations
example/inherited_example.dart — inherited dependencies and rebuild propagation
example/bindings_validation.dart — low-level FFI smoke test
example/pulse_animation.dart — AnimationController and ticker usage

Interactive widgets (use these to verify keyboard/mouse work in your terminal):

example/focus_form.dart — focus manager and TextInput routing
example/select_demo.dart — Select<T> with arrows / j/k / Enter
example/scrollbox_demo.dart — ScrollBox with arrows / PgUp / PgDn / Home / End
example/textarea_demo.dart — multi-line TextArea, Ctrl+Enter to submit
example/widgets_tour.dart — combined tour, Tab cycles focus

Supported Keyboard and Mouse Input

The stdin parser (lib/src/core/stdin_input_driver.dart) decodes:

Input	Result
Printable ASCII / UTF-8	`KeyEvent(key: '<char>')`
Backspace (BS / DEL)	`KeyEvent(key: 'Backspace')`
Tab	`KeyEvent(key: 'Tab')`
Enter (CR / LF)	`KeyEvent(key: 'Enter')`
Escape	`KeyEvent(key: 'Escape')`
Ctrl + letter	`KeyEvent(key: '<letter>', modifiers: KeyModifiers.ctrl)`
Arrow keys	`ArrowUp` / `ArrowDown` / `ArrowLeft` / `ArrowRight`
Home / End	`Home` / `End`
Delete / PageUp / PageDown	`Delete` / `PageUp` / `PageDown`
Function keys	`F1`–`F12` (both `ESC O P/Q/R/S` and `ESC [N~`)
Mouse SGR	`MouseEvent { type, button, x, y, modifiers, scrollDelta }`
Bracketed paste	one `PasteEvent` per block — subscribe via `binding.inputManager.onPaste`
Kitty CSI-u	`KeyEvent` with full Kitty modifiers when `binding.enableKittyKeyboard()`

Signal handling: SIGINT, SIGTERM, and SIGHUP restore terminal modes and exit cleanly (POSIX). SIGWINCH triggers a buffer resize and re-layout.

Basic Framework Usage

import 'package:muse/muse.dart';

class CounterApp extends StatefulWidget {
  const CounterApp({super.key});

  @override
  State<CounterApp> createState() => _CounterAppState();
}

class _CounterAppState extends State<CounterApp> {
  int count = 0;

  @override
  Widget build(BuildContext context) {
    return Container(
      alignment: Alignment.center,
      child: Text('Count: $count'),
    );
  }
}

void main() {
  runTuiApp(const CounterApp());
}

For inspection-heavy tests and diagnostics, runTuiApp(..., headless: true) avoids drawing while still exercising the widget and render pipelines.

Native Libraries

Native OpenTUI binaries are packaged as Dart native assets. The build hook (hook/build.dart) verifies native_manifest.json, bundles the current platform library for dart run, dart test, and dart build cli, and falls back to a manifest download or Zig source build when the checked-in binary is missing.

Standard development flow uses the bundled native asset automatically
OPENTUI_LIBRARY_PATH is the exact development override for a custom build
dart run scripts/fetch_opentui_binaries.dart --verify-only verifies that native_manifest.json matches the checked-in binaries
dart build cli -t bin/health_check.dart produces a CLI bundle with the executable under bundle/bin/ and libopentui under bundle/lib/

Examples:

dart run scripts/fetch_opentui_binaries.dart --verify-only
dart build cli -t bin/health_check.dart

If you need to point at a custom library build:

export OPENTUI_LIBRARY_PATH=/path/to/libopentui.dylib
dart run example/hello.dart

Testing and Goldens

Detailed testing notes live in test/README.md. The short version:

dart analyze
dart test

Regenerate goldens only when the visual change is intentional:

UPDATE_GOLDENS=1 dart test test/golden
UPDATE_GOLDENS=1 dart test test/example/layout_basics_golden_test.dart

Failure artifacts are written to test/failures/ during failed golden runs and are intentionally ignored by git.

Local Go Parity

Primitive parity compares Dart-rendered snapshots against a repo-owned Go snapshot tool that uses the external/opentui git submodule bindings.

Initialize the OpenTUI submodule first if your checkout did not fetch submodules:

git submodule update --init external/opentui

Run the wrapper directly:

./scripts/run_go_snapshot.sh --scene S1 --width 20 --height 5

Run the comparator:

GO_SNAPSHOT_CMD=./scripts/run_go_snapshot.sh \
dart run bin/parity_compare.dart --scenes S1,S2,S3 --width 20 --height 5

Run the parity tests:

GO_SNAPSHOT_CMD=./scripts/run_go_snapshot.sh \
dart test test/parity

Repo References

tasks/plan.md — canonical roadmap
example/README.md: example catalog
test/README.md: testing workflow
FFIGEN.md: binding regeneration notes

For OpenTUI behavior validation, compare against:

external/opentui/packages/core
external/opentui/packages/go
external/opentui/packages/react

Notes

Alternate-screen rendering and debug logging are controlled by TuiBinding and TERMINAL_TUI_DEBUG_LOG=1.
The current roadmap intentionally prioritizes correctness, parity, and cleanup over backward compatibility or deprecation work.