flutter_alacritty library
Flutter terminal UI backed by an Alacritty-based Rust engine.
Classes
- BellConfig
- CellOffset
- Logical cell coordinate (row, column) exposed to callback parameters so consumers can act on tap location without reaching into the painter.
- ClearHistoryIntent
- ClearSelectionIntent
- ConfigLoader
- App-level glue that turns an on-disk TOML file into a TerminalConfig. The only component that knows the config path; a library consumer skips it and builds TerminalConfig directly. All failures fall back to defaults.
- CopyIntent
- Intent: copy the engine's current selection to the system clipboard.
- CursorConfig
- DecreaseFontSizeIntent
- Intent: bump font size down by 1pt.
- EngineBinding
- Abstracts the FRB engine calls so the client is testable without the native lib. Returns native GridUpdates (translation from FRB types lives in the FRB-backed implementation).
- FlutterPtyBackend
- FontConfig
- FontStyleConfig
- Per-style font override. null family → synthesize from the base family.
- FrbEngineBinding
-
FRB-backed binding. Owns the engine handle, translates FRB
RenderUpdateinto native GridUpdate, and dispatches polled terminal→host events. - ImeConfig
- IncreaseFontSizeIntent
- Intent: bump font size up by 1pt.
- KeyboardConfig
- LinkCellRange
-
A confirmed link column range on one viewport row (half-open
[start, end)). - LinkOverlay
-
Immutable per-frame map of viewport-row -> enabled link ranges. Built by
TerminalViewfrom enabled provider spans and read byTerminalPainterso host-provided links underline like OSC 8 hyperlinks without touching grid flags. - LinkSpan
-
A half-open column range
[start, end)on a single visible line, with an opaque payload handed back to the host on activation. - MouseConfig
- PasteIntent
- Intent: paste the system clipboard's plain-text content into the engine.
- PtyBackend
- A source/sink of terminal bytes. flutter_pty is the v1 implementation; the interface lets us swap to a forked PTY, a dart:ffi PTY, or a remote (SSH) source later without touching the engine.
- RawKeyBinding
-
One raw
[[keyboard.bindings]]entry. Parsing to Flutter Shortcuts/Actions happens inlib/input/key_bindings.dartso this stays a pure data holder. - ResetFontSizeIntent
- Intent: reset font size to the baseline configured size.
- RustLib
- Main entrypoint of the Rust API
- ScrollConfig
- ScrollLineIntent
- ScrollPageIntent
- ScrollToEdgeIntent
- SearchMatchColors
- Foreground/background/selection (packed 0x00RRGGBB) + the 16 ANSI colors. Opaque fg/bg pairs passed to the terminal painter for search highlights.
- SelectionConfig
- SendEscapeIntent
-
Send raw bytes to the engine (alacritty Action::Esc /
chars). - ShellConfig
- Shell spawn configuration. program=null → $SHELL fallback (current behavior).
- ShellSpec
- Pure spawn parameters, derived from ShellConfig + environment. Extracted so the mapping is unit-testable without spawning a process.
- TerminalBehaviorConfig
- TerminalColors
- TerminalConfig
- Immutable, programmatic terminal configuration. Build with TerminalConfig.defaults
- TerminalController
- View-model layer between the TerminalEngine and the widget tree.
- TerminalEngine
- Public, consumer-facing handle to the alacritty engine.
- TerminalGrid
- The grid that fits a terminal viewport at its current font metrics.
- TerminalGridView
- Read-only view of the terminal grid that the engine exposes to consumers.
- TerminalLinkProvider
-
Host-injectable link source for
TerminalView. - TerminalStyle
- Font-family + sizing slice. The view derives its measured TextStyle from this; bold/italic/boldItalic land in 2O-b.
- TerminalTheme
- All colors a TerminalView needs to paint a frame and the bell overlay.
- TerminalView
- Pure render + input view over a TerminalEngine.
- TerminalViewport
-
Alacritty
SizeInfocounterpart: single authority for pixel layout and cell grid. TerminalViewportController.apply keeps engine, mirror, and PTY aligned to this tuple synchronously on each layout pass. - TerminalViewportController
- Owns the resize lifecycle for one TerminalView pane.
- TerminalViewState
- ToggleSearchIntent
- Intent: toggle the search bar visibility (host concern).
- UnsupportedActionIntent
-
Recognized-but-unsupported alacritty actions (vi/tabs/window/fullscreen…).
Wired to a no-op so config validates and the host can override via
TerminalView.actions. name is the alacritty action name (for logging). - UrlLinkProvider
-
Default link provider shipped by the library: detects bare URLs in rendered
text. Replaces the engine's former Rust hint-regex pass. Always enabled —
URLs need no filesystem validation. Activation (launching) is the host's job
via
TerminalView.onLinkActivate. - ViewportQuery
- Parameters for resolving a terminal grid from a viewport size.
- ViewportResolver
- Maps a ViewportQuery to a TerminalViewport. Always returns a usable viewport — fractional leftover pixels become centered padding, never phantom terminal rows.
- WindowConfig
- WindowPadding
Enums
- Osc52Mode
-
OSC 52 policy mirror of alacritty
term::Osc52(lowercase TOML names).
Constants
-
defaultTerminalShortcuts
→ const Map<
ShortcutActivator, Intent> -
Default key bindings for the terminal view. Consumers can override
individual entries by passing a custom
shortcuts:map to TerminalView; passconst {}to disable every default. - kDefaultTerminalTitle → const String
- Title used before the shell sets one and restored on OSC reset-title.
- kMinTerminalColumns → const int
-
Smallest grid the VT model can represent. A fullwidth glyph writes its cell
plus a trailing spacer, so a single-column grid makes the engine index past
the row end and panic. The native engine clamps to this floor at its size
boundary; producers (viewport layout, PTY geometry) clamp here too so they
never even ask for a degenerate grid. Keep in sync with
MIN_COLUMNS/MIN_SCREEN_LINESinrust/src/engine.rs. - kMinTerminalRows → const int
Functions
-
defaultCopyAction(
TerminalEngine engine) → void -
Reads the engine's selection text and writes it to the system clipboard.
Used as the default Copy action so a
TerminalViewwith no host wiring still performs the natural Ctrl+Shift+C. -
defaultPasteAction(
TerminalEngine engine, TerminalController controller) → Future< void> -
Reads
text/plainfrom the system clipboard and writes it to the engine, applying bracketed-paste encoding when active. Goes through TerminalController.onTerminalInputStart which mirrors alacrittyevent.rs:on_terminal_input_start— scrollback rewind, gated selection clear AND the follow-uprefreshViewso any prior selection highlight disappears from the painter before the paste echo arrives. -
defaultTerminalActions(
{required TerminalController controller, required TerminalEngine engine, required ValueSetter< double> onSetZoom, required double baselineFontSize, required double currentFontSize(), VoidCallback? onCopy, Future<void> onPaste()?, VoidCallback? onToggleSearch}) → Map<Type, Action< Intent> > - Default action handlers for the intents in defaultTerminalShortcuts.
-
hoverCursorFor(
{required bool hyperlink, required int modeFlags, required MouseCursor base}) → MouseCursor -
The mouse pointer shape over a terminal cell, mirroring alacritty's
reset_mouse_cursor(MouseCursorDirtyhandling): a link shows the click pointer; when the app captures the mouse (MOUSE_MODE) the pointer reverts to the platform arrow; otherwise the configuredbase(an I-beam) is used. Pure so it's unit-testable without driving pointer events. -
osc52FromString(
String s, Osc52Mode fallback) → Osc52Mode -
osc52ToWire(
Osc52Mode m) → int -
resolveShellSpec(
ShellConfig shell, {Map< String, String> ? env}) → ShellSpec
Typedefs
- EngineFactory = EngineBinding Function({required int columns, required EngineConfig engineConfig, required void onBell(), required void onClipboard(String), required void onClipboardLoad(), required void onNotify(String), required void onPtyWrite(Uint8List), required void onTitle(String), required void onWorkingDir(String), required int rows})
-
Factory that builds an EngineBinding given the engine event callbacks.
The four callbacks are wired into private streams/notifiers on
TerminalEngine — consumers never see the raw
on*callbacks.