dart_terminal (Antgrid fork)

This is a fork of kingwill101/dart_terminal, branched at d9d3096 and maintained for Antgrid. Use upstream unless you need one of the changes below. Issues and pull requests here are triaged on Antgrid's schedule; no support is promised to anyone else.

Prebuilt native libraries come from two places, on purpose: PTY is built and released here, because upstream's Android libraries are 4 KB page-aligned and Play rejects them. VTE is unmodified, so it still resolves from kingwill101/dart_terminal. tool/prebuilt.dart and each package's bin/setup.dart pick the right host per package.

What's different from upstream

• ghostty_vte — regenerated FFI bindings. Published 0.1.4 shipped bindings generated before the vendored ghostty submodule was bumped, so GhosttyFormatterTerminalOptions is missing its trailing selection field. The C API passes that struct by value, so the callee reads the absent field from uninitialised heap, takes the branch, and builds a selection from wild pointers — the formatter segfaults on every call. This also adds the ffigen.yaml that was never checked in, which is why the bindings drifted at all. Affects every 0.1.4 consumer, not only Antgrid.
• ghostty_vte_flutter — Antgrid's terminal engine and rendering patches.
• portable_pty — 16 KB page-aligned Android libraries. Upstream ships .so files whose LOAD segments are aligned at 0x1000, which Google Play rejects outright. The alignment comes from linker flags rather than the NDK version — measured on aarch64-linux-android, NDK r27c gives 0x1000 without them and 0x4000 with them — so they live in the crate's .cargo/config.toml and apply to CI, local builds, and source builds alike. A readelf gate in the release workflow fails the build if any Android library regresses. Affects every consumer shipping to Play, not only Antgrid.

What a green VTE badge does and doesn't mean

VTE / test-flutter builds no native library and downloads no prebuilt one, so flutter_tester never resolves this package's native assets and every engine-backed test is inert there. Most of them look green because they guard with an early return inside the test body, which reports passed, not skipped. The engine is genuinely exercised only by dart test in pkgs/vte/ghostty_vte, which CI does not run — test-native is if: false upstream. Run it locally before trusting a change to the bindings.

New tests here use skip: instead, so the same absence reports as skipped and the count stays honest.

Dart & Flutter packages for building terminal applications. This monorepo provides two complementary package groups — a VT engine powered by Ghostty and a cross-platform PTY backed by Rust — that together give you everything needed to embed a fully functional terminal in any Dart or Flutter app.

Packages

Package	pub.dev	Description
ghostty_vte		Dart FFI bindings for Ghostty's VT engine — paste safety, OSC/SGR parsing, key encoding
ghostty_vte_flutter		Flutter terminal widgets + wasm initialiser
portable_pty		Cross-platform PTY — native shells on desktop, WebSocket/WebTransport on web
portable_pty_flutter		Flutter ChangeNotifier controller for PTY sessions

The pub.dev badges track upstream's published versions. This fork is not published to pub.dev — consume it as a git dependency.

Quick start

git clone https://github.com/antgrid-ai/dart_terminal.git
cd dart_terminal
git submodule update --init --recursive
flutter pub get

Run the VTE tests

cd pkgs/vte/ghostty_vte
dart test

Run the PTY example

cd pkgs/pty/portable_pty
dart run example/pty_example.dart

Run the Flutter example

cd pkgs/vte/ghostty_vte_flutter/example
flutter run

Prerequisites

Tool	Required for	Install
Dart SDK ≥ 3.10	All packages	dart.dev/get-dart
Flutter	Flutter packages & examples	flutter.dev
Zig ≥ 0.15	Building libghostty-vt	ziglang.org/download
Rust ≥ 1.92	Building the PTY library	rustup.rs

Don't want to install Zig or Rust? Download prebuilt libraries for your platform — the build hooks will use them automatically.

dart run tool/prebuilt.dart --tag v0.0.2

Prebuilt assets for downstream consumers

When ghostty_vte or portable_pty are consumed from pub.dev, you don't need Zig or Rust installed — each package ships a setup command that downloads the correct prebuilt library for your platform:

dart run ghostty_vte:setup
dart run portable_pty:setup

This places the native libraries in .prebuilt/<platform>/ at your project root, where the build hooks find them automatically.

The build hooks search for prebuilt libraries in this order:

1. Environment variable — GHOSTTY_VTE_PREBUILT / PORTABLE_PTY_PREBUILT pointing directly to the .so / .dylib file.
2. Monorepo .prebuilt/ — .prebuilt/<platform>/<lib> at the monorepo root (found by walking up looking for pubspec.yaml + pkgs/).
3. Project .prebuilt/ — .prebuilt/<platform>/<lib> at your project root (derived from the build system's output directory). This is the recommended approach for downstream consumers.

You can also specify a release tag or target platform:

dart run ghostty_vte:setup --tag v0.0.2 --platform macos-arm64
dart run portable_pty:setup --tag v0.0.2 --platform macos-arm64

Platform labels follow the pattern {os}-{arch}: linux-x64, linux-arm64, macos-arm64, macos-x64, windows-x64, etc.

Tip: Add .prebuilt/ to your .gitignore — these are binary artifacts that should be downloaded as needed, not committed.

Architecture

dart_terminal/
├── pkgs/
│   ├── vte/                        # Terminal VT engine
│   │   ├── ghostty_vte/            # Core Dart FFI bindings
│   │   └── ghostty_vte_flutter/    # Flutter widgets & controllers
│   └── pty/                        # Pseudo-terminal
│       ├── portable_pty/           # Core PTY library (Rust FFI + web transport)
│       └── portable_pty_flutter/   # Flutter ChangeNotifier controller
└── tool/
    └── prebuilt.dart               # Download prebuilt native libraries

License

MIT — see LICENSE. Upstream's copyright is retained alongside this fork's; both notices must survive in any copy.

The vendored Ghostty source under pkgs/vte/ghostty_vte/third_party/ghostty/ is separately MIT-licensed by Mitchell Hashimoto and the Ghostty contributors, and carries its own LICENSE.