Changelog
RSSEvery dart_tui release, newest first: breaking changes, fixes and new features.
3.2.0
LatestChanges
Answered sync prompts draw compact frames. On an interactive terminal,
promptSelectSync,promptMultiSelectSync,promptConfirmSyncandpromptInputSynccollapse to one line with the answer. Esc cancels without replacing the full prompt with an answer summary. Plain mode still uses line-based questions. The summary can be truncated to the terminal width.Single-choice navigation wraps in compact prompts. Arrow navigation wraps only in interactive
promptSelectSync,Logger.chooseOneandLogger.chooseOneSync. BarepromptSelectand the multi-select prompts still stop at the ends.
Fixes
Sync prompts work outside the main isolate.
promptSelectSync,promptMultiSelectSync,promptConfirmSync,promptInputSyncand theLoggersync methods threw aStateErrorin any isolate other thanmain, which includes every test underpackage:test. They start no stdin reader, so the main-isolate rule forProgramdoes not apply to them (#45). TheStateErrorguard sees only readers in the same isolate: do not let another isolate read stdin or change the terminal mode during a prompt.
dart_tui now does CLIs: CliRunner with shell completions, a Logger with task lists and sync prompts, and spinner presets. Programs also run inline, detect colours, fall back to plain mode, and test with testing.dart.
Features
Sync prompts.
promptSelectSync,promptMultiSelectSync,promptConfirmSyncandpromptInputSynctake the same parameters as the async prompts, use the same models and views, and return the value itself instead of aFuture. Code that already calls prompts synchronously, such as helpers that wrap thepromptspackage (melos), interact'sConfirmandSelect(fvm) or mason_logger'sLogger, can switch by changing only those helpers, with noasyncup the call chain. On a terminal they use raw mode, readstdin.readByteSync, decode keys as before, repaint inline and restore the terminal in afinallyblock. Esc returnsnull. Ctrl+C restores the terminal and exits the process with code 130, unlike the async prompts, which returnnull. A lone Esc is told apart with a 50 ms wait. In plain mode they ask the same numbered line questions withstdin.readLineSync, and the end of input returnsnull. Limits: no Cmds run, no spinner, no redraw on resize, only the process stdin (withInput(stream)throwsArgumentError,withInput(null)returnsnullat once),StateErrorwhile aProgramor an async prompt reads stdin and underTuiTester, and a signal from outside during a prompt ends the process without restoring the terminal.Loggerinpackage:dart_tui/cli.dartgainspromptSync,promptAnySync,confirmSync,chooseOneSyncandchooseAnySync, with the parameters and return types of mason_logger's methods, so moving from mason_logger is a rename with noawait. ALoggerwith a customstdin:stream throwsStateErrorfrom them. Use them to migrate existing synchronous code; write new code with the async prompts. On Windows the raw path is implemented but checked only by unit tests on windows-latest, not in an interactive console; the pseudo-terminal tests run on macOS and Linux only.CLI task lists. The new
Logger.tasks(List<Task>, {concurrency, exitOnError})inpackage:dart_tui/cli.dartshows a live task list, likepnpm installordocker pull. ATaskhas a title and arunfunction that gets aTaskContext: settitle, calllog(line)for output under the task,skip([reason])to end the task as skipped, ortasks(list, {concurrency})for nested steps at any depth. A task whoseenabledreturns false is skipped. Tasks show in declaration order. A task that succeeds collapses to one line, and a failed task stays open with its output. WithexitOnError: true, the default, a failure starts no new tasks, waits for the running ones, draws the last frame and throwsTasksFailedwith every failure (Parent > Childfor nested ones).CliRunner.runAndExitturns it into exit code 70 with one line. In plain mode (pipes, CI,ACCESSIBLE=1,--plain) it writes no escape codes and one line for each finished task.--quietshows only failures and the summary, on stderr.--verboseprints every logged line above the list. The live list is at most the terminal height minus 1 and each line is cut to the width minus 1. It does not read stdin and does not install signal handlers. Callinglogger.taskswhile another list runs throws aStateError. Seeexample/cli_tasks.dartand the "Task lists" section of the guide "Build a CLI with commands".Shell completions.
CliRunneradds acompletioncommand and a hidden__completecommand when the runner has a command of its own.notes completion [bash|zsh|fish]prints the script.completion installandcompletion uninstalladd and remove it, and use$SHELLwhen you name no shell. The script runsnotes __complete <words>on each Tab, with the protocol of Cobra: onevalue<TAB>descriptionline per candidate, then:<directive>. It completes commands and aliases, flags (with--no-forms),allowedvalues withallowedHelpafter--opt=and--opt, andhelp <command>; other options get file completion. The newCliCommand.completeValue(option, partial)adds values only the app knows, with an optional description after a tab. Install writes the bash script tobash-completion/completions/underXDG_DATA_HOME, the fish script tofish/completions/underXDG_CONFIG_HOME, and the zsh script tonotes/zsh/underXDG_DATA_HOME. Only the zsh install edits a file of yours: it adds one marked block to.zshrcafter it asks (--yesskips the question), and never edits it in plain mode. Install twice changes nothing, and uninstall removes what install added.CliRunner(completions: false)turns it off. A command of yours namedcompletionor__completewins. PowerShell is not supported yet. See the new section in the guide "Build a CLI with commands".CLI command runner. The new
CliRunner<T>andCliCommand<T>inpackage:dart_tui/cli.dartextend args'CommandRunnerandCommand, so you rename the two classes and the app runs as before.UsageExceptionis re-exported. Every command has the runner'slogger. Help follows the layout of Cobra and gh: commands grouped bycategory, flags with defaults and allowed values, the newCliCommand.examples, and the footer, wrapped to the terminal width (usageLineLengthoverrides it). It has no colour in pipes, withNO_COLOR,--no-coloror in plain mode, and the same layout. The runner adds-v, --verbose,-q, --quiet,--[no-]colorand--plain, and--versionwhen you passversion:. It skips a flag when the runner's parser or any command's parser already has an option with that name. It drops a taken abbreviation.runAndExitexits with theintthe command returns, or 0. AUsageExceptionexits with 64: one error line, "did you mean" names, and the usage of the command, on stderr. Any other error exits with 70 and one line; the stack trace shows with--verbose. OnlyCliCommandgets the styled help; a plainCommandprints args' help.--plainand--colorapply to the runner'sLogger, not topromptSelectand the other helpers called directly. Text fromArgParser.addSeparatoris not shown. The package now depends onargs: ^2.5.0, the lowest version withArgResults.flagandArgResults.optionthat supports the 3.5 SDK. See the new guide "Build a CLI with commands".example/cli_app/notes.dartshows a full app. Help lists the newcompletioncommand.CLI logger. The new
package:dart_tui/cli.darthasLogger,Level,ProgressandProgressOptions, shaped like mason_logger 0.3.6, so a Dart CLI can switch with an import change. Prompts return aFuture: writeawait logger.prompt(...).info,detail,success,warn,err,alert,delayedandflushwrite to the same streams as in mason_logger.progressdraws a spinner line at once, truncates the message to the width, and never hides the cursor, reads stdin or installs signal handlers. Without a terminal it writes one start line and one end line.ProgressOptions.animationis aSpinner. On a terminal, Esc or Ctrl+C exits with code 130. In plain mode, when input ends, every prompt returns its default, andNoTerminalAttachedErroris never thrown. There is noLogTheme. The constructor takesstdout,stderr,stdin,environmentandexitfor tests. The library is not exported fromdart_tui.dart. See the new guide "Migrating from mason_logger, interact or prompts".example/cli_logger.dartshows a create-project flow.Multi-select prompt and prompt options. The new
promptMultiSelectasks for any number of choices: Space toggles,atoggles all, Enter confirms, and the result is in list order. In plain mode it reads comma-separated numbers.promptSelecttakesinitial,promptConfirmtakesdefaultValue, andpromptInputtakeshidden(shows•while you type) anddefaultValue. All of them are optional, so existing calls do not change.Test harness. The new
package:dart_tui/testing.darttests apps the way teatest and Textual snapshot tests do.TuiTester(model)runs the realProgramheadless at a fixed size (80x24 by default, also sent as the firstWindowSizeMsg), with an empty environment, plain mode off and a pinned colour profile (noColorby default). It savesStyle.defaultProfileandStyle.hasDarkBackgroundand restores them when the run ends, also when the model throws.press('shift+tab')builds itsKeyPressMsgwith the real input decoder;typesends one key per Unicode scalar;pastesends a bracketed paste;resizeandsendsend messages. Each call completes once the program has handled it.screen(plain text),styledScreenandmodelfollow every update.waitForthrows with the last screen on timeout;quitanddonereturn the final model, screen and outcome.TuiTester.run(body)drives programs constructed inside the body, such aspromptSelectorForm.run.expectScreen(screen, path)compares with a golden file and names the first differing line;DART_TUI_UPDATE_GOLDENS=1writes the files.CaptureSinkis a public in-memoryIOSink. The library imports no test framework and nothing is added todart_tui.dart. There is no fake clock: timers run in real time.Spinner presets. The new
Spinner(frames, interval)type has the 12 presets from Bubble Tea'sbubbles/spinner:line,dot,miniDot,jump,pulse,points,globe,moon,monkey,meter,hamburgerandellipsis, with the same frames and speeds. All frames of a preset have one display width, so text after the spinner does not move.SpinnerModeltakes a preset asspinner(theframesargument still works) and a newid. A spinner with anidruns its own tick chain: returntick()frominitand theCmdfrom eachupdate, and it advances at its own speed with nowithTickInterval.TickMsghas a new optionaltag, so a tick from an older chain is dropped and callingtick()twice does not double the speed.spin()takes an optionalspinner; the default is unchanged.example/spinners.dartnow shows all 12 presets at once, each at its own speed.Plain mode. The new
withPlainMode([bool on = true])makespromptSelect,promptConfirm,promptInput,filter,spin,pagerandForm.runask plain line questions and write no escape codes. It is for pipes, CI, screen readers and AI agents. Plain mode is on when you force it, or whenDART_TUI_ACCESSIBLEorACCESSIBLEis set to a true value, or when the helper uses the real stdin and stdout and either is not a terminal orTERM=dumb.withPlainMode(false)wins over all of these. A helper withwithInputorwithOutputkeeps the terminal UI unless you force plain mode, so existing tests do not change. End of input cancels: the helper returnsnull, likeEsc, andForm.runreturnsnull. When input is not a terminal, each answer is echoed to the output. A customProgramin plain mode, or with a real stdout that is not a terminal, writes no cursor, erase or query codes, printsprintlnlines at once, and writes its final frame once as plain text. The feature is additive.Colour profile detection. The new
detectColorProfile()readsFORCE_COLOR,NO_COLOR,CLICOLOR_FORCE,TERM,COLORTERM,TERM_PROGRAMandWT_SESSION, after charmbracelet/colorprofile. AProgramthat writes to the real stdout now uses it when you do not passwithColorProfile, and sends the result inColorProfileMsg.Styles follow the profile. The new
Style.defaultProfileapplies to everyStylewithout its ownprofile. Before, no style read the profile theProgramreported. Outside aProgramit istrueColor, ornoColorwhenNO_COLORis set. Scripts can opt in withStyle.defaultProfile = detectColorProfile();.withColorProfilenow pins it for the run. Border, margin and underline colours,gradientTextandgradientBackgroundfollow the profile too. Before, they always sent true colour, also whenNO_COLORwas set.Light and dark follow the terminal.
AdaptiveColoruses the style's own background, then the newStyle.hasDarkBackground. That value starts fromCOLORFGBGand is otherwise dark. AProgramupdates it from the terminal's OSC 11 reply (BackgroundColorMsg) before the model sees the message, so the next frame uses the correct variant.A
Programrestores both defaults when its run ends, also whenupdatethrows. AProgramwith a custom output sink (withOutput) keepstrueColor, so test output does not change.make testandtool/coverage.shunsetNO_COLOR, because the suite pins true-colour output.example/color_profile.dartshows the detected profile and background. The new website guide "Colour and terminals" describes the rules.
Fixes
Spinners no longer step on other models' ticks. A
SpinnerModelwithout anidadvanced on everyTickMsg, including a timer'stickWithId, so a timer moved every spinner on screen. It now ignores aTickMsgthat has an id. The global tick fromwithTickIntervalstill moves it. No example or test relied on the old behaviour.promptConfirmdefaults to no. Its label said[y/N], but Enter returnedtrue. Enter now returnsfalse, as the label says, and plain mode asks(y/N). Typeyto confirm.AdaptiveColorforegrounds now use aCompleteColorbackground (backgroundComplete) to pick light or dark. Before, they ignored it.Inline programs no longer paint over shell history (#18). Outside the alternate screen, both renderers now draw the view where the cursor is and move only relative to the view's top row. They send no absolute row moves and no cursor-position query. Redraws rewrite only changed lines and erase rows the view no longer uses. A view taller than the terminal shows its last rows, and lines are cut to the terminal width, so redraws do not flood scrollback.
println/printfoutput goes above the view and into scrollback. On exit the last frame stays, with the shell prompt on the next line. Programs run in sequence (prompts, forms) start below each other. Suspend, exec and resize erase only the view, not the screen. Alt-screen output is unchanged.scrollUp/scrollDown(ScrollMsg) now apply only in the alternate screen. Outside it they do nothing, because scrolling the whole terminal moved shell history and the view's anchor.ClearScrollAreaMsgclears once instead of twice. Outside the alternate screen it,ClearScreenMsgand a resize erase only the view.example/prompts_chain.dartnow runs inline. The newexample/tapes/inline.taperecords it below shell history.
Known limit: when the terminal is made narrower, terminals that reflow wrapped lines can leave stale rows above the redrawn view.
This major release makes raw mode behave like Bubble Tea on macOS and Linux, decodes input one Unicode scalar at a time, validates timers and forms in every build mode, and removes two leftover APIs. It also fixes the hang that kept every program reading default stdin alive after it quit (#15). The full macOS validation is in docs/quality/2026-10-17-macos-3.0.0-validation.md.
Breaking changes
View.setContentremoved. Assign the field instead:view.content = 'Hello';.Form.fieldIndexForTestremoved. Test observable state instead, such asform.valuesorform.view().content.Ctrl+C, Ctrl+Z and other control keys are key messages on macOS and Linux. Raw mode now also clears ISIG, IEXTEN and IXON. Ctrl+C no longer raises SIGINT, so
Programno longer turns it intoInterruptMsgand quits for you. Ctrl+Z no longer stops the process, which used to leave the terminal broken. Handle the keys inupdate.kill -INTstill deliversInterruptMsg. Ctrl+\, Ctrl+S, Ctrl+Q, Ctrl+V and Ctrl+Y also arrive as keys.if (msg is KeyMsg) { switch (msg.key) { case 'ctrl+c': return (this, () => quit()); case 'ctrl+z': return (this, suspend); // optional job control } }One key event per Unicode scalar. Adjacent printable bytes are no longer merged into one
KeyPressMsg. An unbracketed paste ofhellois five events. A grapheme cluster such as 👨👩👧 or e + U+0301 arrives as several events. Malformed UTF-8 producesunknownkeys instead of stalling input. Appendmsg.keyEvent.textfor each event, and handlePasteMsgfor pasted text.Timer helpers validate durations when called.
everythrowsArgumentErrorfor a zero or negative interval.tickandtickWithIdthrow for a negative delay. Before,every(Duration.zero, ...)failed later with a division by zero.Forms validate their input at construction in every build mode.
FormthrowsArgumentErrorfor no groups, an empty group, or duplicate field keys across groups.Field.selectOfandField.multiSelectOfthrow when given both or neither ofoptions/optionsFor. Multi-select fields throw on duplicate option values. Before, only debug asserts checked some of these.Default stdin belongs to the main isolate. A
ProgramwithoutwithInputmust run in the main isolate; elsewhererun()throwsStateError. Readers in several isolates used to race for input and could close stdin for the whole process.await Isolate.run(() => Program(options: [withInput(null)]).run(model));SIGTERM quits gracefully. It enqueues
QuitMsg, so the terminal is restored andrun()returns. AwithFilterthat vetoesQuitMsgalso vetoes SIGTERM. Before, the process died with the terminal left in the alternate screen.metais no longer a dependency. If you importedpackage:metathrough dart_tui, add it to your ownpubspec.yaml.
Behavior changes
Programs exit when
run()returns. A helper isolate reads default stdin, so stdin no longer keeps the process alive after the last program. Sequential programs (prompts, gum helpers) still share input, stdin stays open afterwards, andwithInput(stdin)uses the same shared reader.Commands end with the program. Timers that a command starts (
tick,every,Future.delayed, ...) are cancelled when the program ends.execProcessowns the terminal input. While an inherited child runs, no program reads stdin. A child started right after startup no longer receives the terminal's replies to the startup queries; the exec waits up to 500 ms for them, once.sequenceno longer blocks input. Its commands still run in order, but other messages are processed while a step is pending. A sequence stops after a step throws or returnsQuitMsg/InterruptMsg.Text widgets accept bracketed paste. Focused
TextInputModel,TextAreaModelandpromptInputinsertPasteMsgcontent with control characters removed. AFormroutes the paste to the active field. ForwardPasteMsgto your widgets as well asKeyMsg.Multi-select and dynamic selects keep selections by value. Values that disappear from
optionsForare dropped, and reordered options keep the selection. An untouchedoptionsForselect submits its first option, like a static select, instead ofnull.Form focus skips hidden fields, hidden groups and notes, including at the start of the form, and hidden groups never receive input.
More keys are named. ESC + key arrives as
alt+<key>(alt+a,alt+enter,ctrl+alt+a) instead ofunknown. NUL isctrl+space; 0x1C–0x1F arectrl+\,ctrl+],ctrl+^andctrl+_; SS3 arrows areup/down/left/right; SGR wheel-left/right decode aswheelLeft/wheelRight.The final frame is rendered on quit, and leaving the alternate screen no longer prints a blank line.
Mouse wheel events scroll
ListModel,TableModelandTreeModel.ListModelfilter mode: Up/Down and Ctrl+P/Ctrl+N move through the matches while typing, so gumfilter()returns the highlighted match.FilePickerModelshows load errors (error) instead of an empty list, ignores keys while a directory loads, clampscursor,scrollOffsetandheight, and addscopyWith(clearSelected: true).
Fixes
Inline (non-alt-screen) programs leave the shell prompt directly below the view on exit. Before, it landed on the last changed row, inside the view.
Typing a combining mark or a multi-scalar emoji no longer crashes
TextInputModelor misplaces text inTextAreaModel.Backspace in list filters and
promptInputdeletes a whole grapheme, andpromptInputaccepts Space.List mouse clicks select the right item when only some items have descriptions; navigation is safe with an empty list or no filter matches.
Field.input(placeholder:)renders;optionsForselects show their options before the first edit.Table headers align with their rows, and the selected tree branch keeps its highlight.
Canvas layers with equal z-index keep their paint order.
Input stream errors quit cleanly and restore the terminal, and a throttled frame is never written after the terminal is released or the program is killed.
Timer errors show the rejected duration.
Fixed several examples:
shopping_list,showcase,http,package_manager,cursor_model,gmail,canvas,isbn_form,list_mutationandfile_picker.
Performance
TextInputModelre-segments only the end of the value when text is appended: 25,000 single-character inserts take 0.95 s, down from 1.7 s in 2.1.0.
Tooling and docs
A new
sdk-floorCI job runs analysis and tests on Dart 3.5.4, and the dev dependency ranges now resolve there.PTY smoke tests require each example to exit on its own after quit, and cover paste and Space.
tool/compile_examples.shreports failed compiles.Re-recorded all 60 VHS example GIFs.
Known limitations
Inline (non-alt-screen) rendering still starts at row 1 and can overwrite earlier shell output (#18).
On Windows, the first input meant for an
execProcesschild can reach the program instead.
Performance and terminal-lifecycle follow-up to 2.0.0. No breaking API changes.
Performance
Faster input decoding, layout, and rendering on large pastes, viewports, and text widgets.
Cache
TextAreaModellogical lines across cursor-only copies.Fast-path
textWidthfor ASCII-only strings.make bench-hotpathcompares naive Dart with dart_tui;make bench-startup-ptymeasures first-visible startup.
Fixes
Bracketed paste no longer mangles multi-byte UTF-8.
Restore cooked TTY mode before stdin cancel on exit.
Skip
\x1b[?1049lon shutdown when alt screen was never entered.
Docs
Performance guide and README hot-path table.
Re-recorded all 60 VHS example GIFs.
This major release hardens the terminal runtime, ports the selected Bubble Tea capabilities through P9, and removes the temporary compatibility APIs so the package has one clear model, styling, and program-configuration path.
Breaking changes
Models: removed the
TeaModelalias. Extend or implementModeldirectly.Keys: removed the
LegacyKeyMsgalias. UseKeyPressMsgfor press events or the sharedKeyMsgbase type.Styles: removed the raw ANSI
TuiStylehelpers. Use immutableStylevalues such asconst Style(isBold: true).render(text).Program configuration: removed
ProgramOptionsand the parallelprogramOptions/programSettingsparameters.Program, forms, prompts, and gum helpers now accept oneList<ProgramOption>namedoptions. UsewithAltScreen(),withTickInterval(...),withHideCursor(...), andwithLogFile(File(...))for the former struct fields.
Bubble Tea parity
Added declarative terminal colors, native progress reporting, keyboard options, and view-level mouse callbacks.
Added Kitty progressive-keyboard negotiation and modern key press, repeat, and release events.
Added Unicode Core negotiation plus shared grapheme-aware terminal width handling across input, styling, and rendering.
Expanded the viewport with gutters, per-line styles, search highlights, filling, and horizontal navigation.
Added dynamically sized, visually wrapped textarea behavior.
Added multi-stop, scaled, and callback-driven progress colors.
Added rich underline styles, OSC 8 hyperlinks, and ANSI-state-safe layout operations.
Added explicit dark/light component style factories and immutable suggestion, cursor, and viewport introspection APIs.
Runtime correctness and security
Made cell diffs width-aware for CJK, emoji, and other double-width graphemes, while reducing cell parsing from quadratic to linear work.
Made declarative cursor position, shape, blink, and color reach the terminal.
Correctly consume OSC, DCS, APC, PM, and SOS control strings without leaking payload bytes into rendered cells.
Made
Program.kill()wake idle programs and restore terminal state.Corrected Unicode capability-report semantics and sanitized window-title OSC payloads.
Preserved cumulative SGR and OSC 8 hyperlink state in
CellRenderer, made multi-grapheme input edits atomic, and restored viewport line styles around highlighted spans.
Release quality and tooling
Added real-PTY tests for kill, external cancellation, resize, suspend/resume, and terminal restoration.
Centralized alternate-screen, cursor, focus, paste, and mouse transitions in one terminal-mode state machine shared by both renderers.
Aligned local and CI analysis on one clean repository-wide boundary.
Made plain Dart the default across Make targets, examples, VHS tapes, and website source mirrors; FVM remains an optional override.
Refreshed
meta,lints, andtestconstraints to their current resolvable releases.Moved README previews to the hosted documentation assets and excluded local GIF binaries from the pub archive.
Documentation and examples
Upgraded the documentation site to patched Next.js 16.3.0 with dedicated audit, typecheck, and production-build CI.
Refreshed the component gallery, guides, API snippets, and all 60 tape-backed example previews for the 2.0 API.
Forms (huh-style)
A composable, immutable, key-based forms subsystem — the equivalent of Charm's huh.
Form(forms/form.dart) — an immutableTeaModelyou can embed (exposessubmitted/cancelled/values), or run one-shot withawait form.run()(returnsFormValues?,nullif cancelled). Groups of fields render one page at a time as a wizard, with aGroup N/Mindicator.Field types via the
Fieldfactory:input,password,text(multiline),file,select/selectOf<T>,multiSelect/multiSelectOf<T>,confirm,note. Text-ish fields reuseTextInputModel/TextAreaModel/FilePickerModel.Key-based values —
FormValues.get<T>(key); hidden fields are excluded from the result.Validation — per-field
validatewith inline errors; blocks advancing and submit.Dynamic / conditional fields — any field or group takes
hidden: (FormValues) => bool; titles and select options can be computed from other fields' values (titleFor,optionsFor), recomputed on every change with selection clamping.Navigation —
Tab/Enteradvance (Enter inserts a newline in multilinetext;Tab/Ctrl+Dadvance there),Shift+Tabback,Esc/Ctrl+Ccancel.FormStyles— Catppuccin Mocha defaults.New
form.dartexample + VHS tape.
Fixes
TextInputModel/TextAreaModel: typing a space inserted the literal string"space"(and F-keys inserted"f1", etc.) because the default branch inserted the keystroke name rather than the character. Now only unmodified printable runes are inserted, using the actual rune text — so text fields (and form inputs) accept spaces correctly.
Docs
New documentation website — a searchable gallery of every component, block and guide with live GIF previews and copyable source. Lives in
website/(excluded from the published package via.pubignore).
New components & helpers
Spring(bubbles/spring.dart) — harmonica-style damped-harmonic-oscillator for smooth eased motion of any scalar (progress, scroll, cursor). Pure math, no terminal I/O:Spring(fps:, frequency:, damping:).update(pos, vel, target)plusfpsToDelta().FileLog(log.dart) — append timestamped diagnostics to a file. Because a runningProgramowns stdout,print()corrupts the UI; write here andtail -finstead.FileLog.none()discards.gum-style one-shot helpers (
gum.dart) —filter()(interactive fuzzy picker),spin()(run a spinner while awaiting aFuture, returns its result), andpager()(scrollable viewer). Each takes aprogramOptionslist for headless testing.ListModelruntime mutation API —withItems,appendItem,insertItem,removeItemAt,setItemAt,select, andselectedIndex; all clamp the cursor.Readline / emacs editing keys for
TextInputModelandTextAreaModel—ctrl+a/ctrl+e(home/end),ctrl+b/ctrl+f(char left/right),alt+←/alt+→(word motion), andctrl+w/alt+backspace(delete previous word).
Examples
Five new runnable examples (each with a VHS tape): spring, gum (filter/spin/pager), list_mutation, readline, and file_log.
Performance
Hot-path allocation and CPU reductions on the per-frame render and per-keystroke paths (all behaviour-preserving, covered by regression tests):
stripAnsifast-path (skip the regex when there is no escape) plus a single-grapheme width helper — the width/wrap/truncate/pad path no longer runs a regex per grapheme.ViewportModelreuses its wrapped lines across scrolling instead of re-wrapping every frame.AnsiRendererandCellRendererskip the grid rebuild / diff walk on identical frames; the redundant per-frame list copy is gone.ListModel.filteredItemsis memoised;TreeModelreuses its flattened node list on cursor-only changes.The render throttle uses a precomputed frame budget and a monotonic
Stopwatch.
Fixes
Prompts no longer hang on cancel.
promptSelect/promptConfirm/promptInputsetfinishedon Esc/Ctrl+C but never quit, and raw mode delivers Ctrl+C as a byte (not SIGINT) — so cancelling hung forever. They now quit cleanly and returnnull. The three prompt helpers also gained aprogramOptionsparameter for headless/scripted use.
Quality
Test suite grown from 423 to 560+ cases; measured
lib/line coverage raised from ~67% to 92%.New
make coverage [FLOOR=90]target and a CI coverage gate (Linux/macOS) that fails below the floor, honouring// coverage:ignore-*markers for genuinely-untestable code (Win32 FFI, raw-mode TTY, OS signals).
New components
CursorModel(bubbles/cursor.dart): in-line blinking cursor widget with three display modes —CursorMode.block(█),CursorMode.underline(_), andCursorMode.bar(|). Toggles visibility on everyTickMsgwhenblink: true. Useful for building custom text editors, prompts, or any UI that needs a visible insertion point independent of the real terminal cursor. Supportsfocus()/blur()to pause blinking, andwithMode()/withBlink()builders.MultiSelectModel(bubbles/multi_select.dart): scrollable checkbox list supporting multiple concurrent selections. Navigate with↑↓ / jk, toggle withSpaceorx, select/deselect all witha, confirm withEnter. Features:wrap: bool— cursor wraps at list boundariesheight— viewport limitingshowStatusBar—"N/Total selected"footerselectedValuesgetter — returns customvalueor falls back tolabelMultiSelectStylesfor full per-element theming (Catppuccin Mocha defaults)
New ProgramOption functions
Seven new fluent option functions complement the existing ProgramOptions struct:
withAltScreen() // enter alt-screen buffer at startup
withHideCursor([bool hide = true]) // hide/show terminal cursor at startup
withTickInterval(Duration interval) // emit TickMsg at a fixed interval
withMouseCellMotion() // enable button-event mouse tracking
withMouseAllMotion() // enable all-motion mouse tracking
withReportFocus() // emit FocusMsg / BlurMsg on window focus
withWindowSize(int width, int height) // inject fixed dimensions (useful in tests)These compose with ProgramOptions and take precedence over it; defaultMouseMode and defaultReportFocus act as floor values so per-View overrides still work.
Style additions
Border.normal— ASCII-art border (+,-,|) for environments without Unicode box-drawing support.Per-side border flags —
Bordernow hasshowTop,showRight,showBottom,showLeft(all defaulttrue). UseStyle.withBorderSides({top, right, bottom, left})or the pre-built helpersBorder.topOnly,Border.bottomOnly,Border.sidesOnlyto draw partial borders.Border.copyWith()— produce modifiedBorderinstances without recreating all fields.tabWidth: intfield onStyle(default4) —\tcharacters are expanded to spaces before rendering. UseStyle.withTabWidth(n)fluent builder.marginBackground: RgbColor?field onStyle— fills the margin area with a solid ANSI background colour. UseStyle.withMarginBackground(color)fluent builder.getWidth(String)(public) — visible terminal column width after stripping ANSI and counting double-wide characters.getHeight(String)(public) — number of newline-delimited lines.truncate(String, int)(public) — drop trailing visible columns to fitmaxWidth; ANSI-safe.truncateLeft(String, int)(public) — drop leading visible columns; ANSI codes in the kept portion are preserved.
Component navigation & mouse improvements
ListModel— addedpgup/ctrl+b,pgdown/ctrl+f,home/g,end/Gkey bindings;viewOffsetYfield for click-to-select mouse handling; mouse wheel scrolling.SelectListModel— addedwrap: bool(cursor wraps at list boundaries).TableModel— addedviewOffsetYand mouse handling (wheel up/down, left-click to select with header offset).TreeModel— addedviewOffsetYand mouse handling (wheel scroll, left-click to move cursor); fixed' 'space key mapping to'space'keystroke.
New examples
| Example | What it shows |
|---|---|
cursor_model.dart | CursorModel — all three blink modes side-by-side, toggle blink with b |
multi_select.dart | MultiSelectModel — toggle, select-all, confirm, display result |
Tests
10 new test files, 160+ new test cases:
| File | Coverage |
|---|---|
spinner_test.dart | SpinnerModel state transitions |
select_list_test.dart | SelectListModel navigation, wrap, view |
progress_test.dart | ProgressModel rendering and clamping |
help_test.dart | HelpModel expand/collapse, KeyMap |
paginator_test.dart | PaginatorModel navigation, bounds, view |
cursor_model_test.dart | CursorModel blink, focus, modes, view |
multi_select_test.dart | MultiSelectModel toggle, select-all, wrap, view |
program_options_test.dart | Integration: each ProgramOption emits correct ANSI sequences |
input_decoder_test.dart | TerminalInputDecoder — 48 edge-case / fuzz-style tests |
style_properties_test.dart | Property-based invariants for getWidth, getHeight, truncate, Style.render, joinH/V, stripAnsi |
Other
All 54 VHS GIFs regenerated from current kernel snapshots.
New features
ListModel(bubbles/list.dart): full-featured scrollable list with fuzzy/subsequence filtering, keyboard navigation (↑↓ / jk), filter mode (/to enter,Esc/Backspaceto exit), viewport scrolling, optional descriptions, status bar (x/y items), andFullListStylesfor per-element theming.TabsModel(bubbles/tabs.dart): tabbed-interface component with(label, content)pairs,←/→ / h/l / Tab / Shift+Tabnavigation, andTabsStylesfor active/inactive/divider/content theming.SGR attributes — three new text decorations on
Style:isReverse(SGR 7) — swap foreground and backgroundisBlink(SGR 5) — blinking textisOverline(SGR 53) — overline decoration
Style.inherit(parent)— fills everynullfield from a parentStyle, enabling clean style composition without property repetition. All boolean SGR fields (isBold,isDim,isItalic,isUnderline,isStrikethrough,isReverse,isBlink,isOverline) changed frombool→bool?to support three-valued inheritance semantics.underlineSpaces/strikethroughSpaces— control whether underline / strikethrough decorations extend over padding spaces (defaulttrue, matching Lipgloss).borderForeground/borderBackground— independentRgbColortinting for border characters, separate from text content color.borderTitle/borderTitleAlignment— embed a title string in the top border edge withAlign.left/.center/.rightpositioning.wordWrap—Style(wordWrap: true)wraps at word boundaries before padding/border/constraint are applied; respects thewidthconstraint.transform—Style(transform: fn)applies an arbitraryString Function(String)to the rendered content (useful for upper-casing, truncation, etc.).CompleteColor— per-profile color specification:CompleteColor(trueColor: …, ansi256: …, ansi: …); used viaforegroundComplete/backgroundCompleteonStylefor correct downgrade at each profile level.Border.hidden— a visible-but-blank border (spaces) that preserves box geometry without drawing any characters.EdgeInsets.symmetric({vertical, horizontal})andEdgeInsets.only({top, right, bottom, left})— additional named constructors matching Flutter conventions.Layout helpers now accept enums instead of raw
doublefractions:joinHorizontal(AlignVertical, List<String>)— wasdoublejoinVertical(Align, List<String>)— wasdoubleplace(width, height, Align, AlignVertical, content)— was twodoubleargsplaceHorizontal(width, Align, content)— new helperplaceVertical(height, AlignVertical, content)— new helper
Terminal control Cmd helpers (
cmd.dart):enterAltScreen()/exitAltScreen()— emitEnterAltScreenMsg/ExitAltScreenMsghideCursor()/showCursor()— emitHideCursorMsg/ShowCursorMsgsetWindowTitle(title)—Cmdthat emitsSetWindowTitleMsgclearScrollArea()— emitsClearScrollAreaMsgscrollUp([n = 1])/scrollDown([n = 1])—Cmdthat emitsScrollMsg
Renderer interface extended:
setAltScreen(bool),setCursorVisibility(bool),scroll(int, {bool up})added toTeaRendererand implemented byAnsiRenderer,CellRenderer, andNilRenderer.stripAnsi(String)— public utility that strips all ANSI escape sequences from a string; previously internal-only.
New examples
| Example | What it shows |
|---|---|
word_wrap.dart | Style.wordWrap at multiple widths with box, rounded, and thick borders + border title |
border_style.dart | All 6 Border variants, borderForeground / borderBackground, and all three borderTitle alignments |
sgr_attrs.dart | All 8 SGR text attributes; Style.inherit() composition |
list_filter.dart | ListModel with fuzzy filtering, descriptions, status bar, and selection |
tabs.dart updated to use the exported TabsModel bubble instead of an inline reimplementation.
Tests
9 new test files, 90+ new test cases: style_sgr_test.dart, style_border_test.dart, style_wordwrap_test.dart, canvas_test.dart, gradient_test.dart, adaptive_color_test.dart, cmd_terminal_test.dart, list_model_test.dart, tabs_model_test.dart.
Breaking changes
joinHorizontal,joinVertical, andplacenow accept enum arguments (AlignVertical,Align) instead of rawdoublefractions. Migrate:0.0 → AlignVertical.top,0.5 → AlignVertical.middle,1.0 → AlignVertical.bottom;0.0 → Align.left,0.5 → Align.center,1.0 → Align.right.All boolean SGR fields on
Style(isBold,isDim,isItalic,isUnderline,isStrikethrough) changed frombool(defaultfalse) tobool?(defaultnull). Existing code that reads these fields may need a null-aware comparison (style.isBold == trueorstyle.isBold ?? false).
Bug fixes
Terminal hang on exit: awaiting the stdin subscription cancel in the shutdown path so the Dart event loop is fully released before the process exits. Previously the
unawaitedcancel could leave stdin holding the event loop open, requiring a manual Ctrl-C to regain the shell prompt.Terminal not restored on quit: flushing ANSI reset sequences (show cursor, exit alt-screen) before the process exits so the shell prompt appears on a clean line.
Other changes
Enter / LF key fix:
0x0a(LF /\n) now correctly maps toKeyCode.enter, fixing silent key drops on Linux/WSL terminals that send LF instead of CR for Enter.Batch render loop: all pending messages are drained before each render; a single render fires per batch, eliminating up to 16 ms of FPS-throttle lag per key press.
Deferred capability queries:
CSI ?2026$yandOSC 11are sent after the first rendered frame so startup is not delayed.Makefile:
make format(dart format check),make test,make analyze,make run/run-fast/kernels/bench/gifs/new-example.Analyzer clean: resolved all
strict_raw_type,unused_local_variable,prefer_const_constructors,library_private_types_in_public_api, andavoid_relative_lib_importswarnings.
New features
CellRenderer: cell-level diff renderer using grapheme clusters (
characterspackage) — only changed cells emit ANSI sequences, eliminating flicker.Synchronized updates: CSI
?2026h/lwrapping for flicker-free frames on terminals that support it.ExecMsg / execProcess(): run external processes (e.g.
$EDITOR) with full terminal hand-off and optional exit-code callback.TextAreaModel: multi-line editor with
charLimit, ctrl+k/ctrl+u line-kill, cursor navigation.ViewportModel: scrollable content pane with soft-wrap,
atBottom/scrollPercent, keyboard navigation.TableModel + TableColumn: tabular data viewer with header, separator, scrolling cursor, and optional row styles.
TimerModel: countdown timer,
start()/stop()/reset()builders,TickMsgrouting byid.StopwatchModel: elapsed-time stopwatch with millisecond display.
KeyMap + KeyBinding + HelpModel: declarative keybinding registry; help UI with compact/full toggle.
FilePickerModel: async directory browser with extension filtering.
Style system: Lipgloss-inspired
Stylewithwidth/heightconstraints,Align/AlignVertical,inlinemode,AdaptiveColor,Bordervariants;joinHorizontal(),joinVertical(),place()layout helpers.EchoMode (normal / password / none) and
suggestions(tab-completion) onTextInputModel.ValidationFailedMsg + validate callback on
TextInputModel.tickWithId(Duration, Object): tick Cmd with routing ID for composable timers.batch()/sequence(): concurrent vs. ordered command scheduling.Mouse support:
MouseMode.cellMotion/allMotion;MouseClickMsg,MouseMotionMsg,MouseWheelMsg.Cursor control:
View.cursorwithCursorShape(block / underline / bar) and blink flag.Focus reporting:
View.reportFocus,FocusMsg,BlurMsg.Window title:
View.windowTitleOSC sequence.41 examples: complete port of the Bubbletea example gallery.
Performance improvements
Enter / LF key fix:
0x0a(LF /\n) was silently decoded asctrl+jand dropped by all components. It is now correctly mapped toKeyCode.enter, matching Linux/WSL terminal behaviour.Batch render loop: messages are now drained without re-rendering between each one; a single render fires per batch. Eliminates up to 16 ms of FPS-throttle lag per key press.
Unawaited commands:
runCmdis now fire-and-forget so command results arrive as the next queued message without blocking key event processing.Deferred capability queries:
CSI ?2026$y(synchronized-updates query) andOSC 11(background-color query) are sent after the first rendered frame, so the initial visible output is not delayed.Kernel snapshot build:
tool/build.sh --kernelcompiles examples to.dillkernel snapshots (~550 ms startup vs ~1 050 ms JIT source on WSL2).Makefile: added targets for
test,analyze,run,run-fast,kernels,bench,gifs,new-example, and more.48 GIFs re-recorded from kernel snapshots for faster, cleaner recordings.
Bug fixes
Terminal not restored on quit: added
_output.writeln()+await _output.flush()in thefinallyblock so ANSI reset sequences (show cursor, exit alt-screen) are flushed to the terminal before the shell regains control.Terminal hang on exit: awaiting the stdin subscription cancel in the shutdown path so the Dart event loop is fully released before the process exits. Previously the
unawaitedcancel could leave stdin holding the event loop open, requiring a manual Ctrl-C to regain the shell prompt.
Breaking changes from 0.1.0
Legacy Go-style uppercase API aliases removed (
Batch,Sequence,Quit,Println,WithInput, etc.) — use canonical lowercase equivalents.request*commands now emit real terminal protocol queries; decoder responses feed back as typedMsgvalues.ListModelrenamed toSelectListModel.
Initial release:
Programruntime (Elm-styleModel,Msg,Cmd,Batch).Terminal integration via
dart_console(raw keys, window size, resize).Components:
ListModel,TextInputModel,SpinnerModel,ProgressModel.Optional
promptshelpers:select,confirm,input.Example: shopping list (Bubble Tea tutorial port).