PHPackages milpa/live-tui - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. milpa/live-tui ActiveLibrary milpa/live-tui ============== Terminal transport layer for Milpa Live: a retained-mode TUI runtime with virtual-buffer diffing, its own ANSI painter, focus and shortcut management, and the node renderers that paint Milpa Live components in the terminal for the Milpa PHP framework. v0.2.3(yesterday)011↑2900%Apache-2.0PHPPHP >=8.3CI passing Since Jul 27Pushed todayCompare [ Source](https://github.com/getmilpa/live-tui)[ Packagist](https://packagist.org/packages/milpa/live-tui)[ RSS](/packages/milpa-live-tui/feed)WikiDiscussions main Synced today READMEChangelog (6)Dependencies (6)Versions (6)Used By (0) [ ![Milpa](https://raw.githubusercontent.com/getmilpa/core/main/art/lockup/milpa-lockup-v-color-light.svg) ](https://github.com/getmilpa) Milpa Live TUI ============== [](#milpa-live-tui) > The **terminal surface** for `milpa/live` — a retained-mode runtime that diffs a virtual terminal buffer and repaints only what changed, its own ANSI painter, focus and shortcut management, and 23 node renderers. [![CI](https://github.com/getmilpa/live-tui/actions/workflows/ci.yml/badge.svg)](https://github.com/getmilpa/live-tui/actions/workflows/ci.yml)[![Packagist](https://camo.githubusercontent.com/7799bd89fdabaae38cab679bb9aeee3e7282b58161d3fdee668f926aae4f9351/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6d696c70612f6c6976652d7475692e737667)](https://packagist.org/packages/milpa/live-tui)[![PHP](https://camo.githubusercontent.com/ca03f11ea27dac4dedc8ad56a7bdfc4a9ff5feb825055f9d2983616115076607/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d254532253839254135253230382e332d3737376262342e737667)](https://www.php.net/)[![License](https://camo.githubusercontent.com/798509b4df525f56802b56f8096862487f08023e3d7561c68656f8dab10d0d6e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4170616368652d2d322e302d626c75652e737667)](LICENSE)[![Docs](https://camo.githubusercontent.com/c6dc6a3411e15b0ac7cc4583e8e6a8144181caedb82f5d98753353decda06d77/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f646f63732d4150492532307265666572656e63652d626c75652e737667)](https://getmilpa.github.io/live-tui/) `milpa/live` defines the render-target-agnostic component lifecycle (mount / handle / render, contracts, data sources). `milpa/live-tui` is what makes that lifecycle reachable from a terminal: a node tree, a layout engine that resolves it into bounds, 23 renderers that paint those bounds, and a loop that writes only the rows that actually changed. It is the **sibling** of [`milpa/live-web`](https://github.com/getmilpa/live-web), not its dependent. Both are transports of the same engine; neither requires the other. Install ------- [](#install) ``` composer require milpa/live-tui ``` What it is ---------- [](#what-it-is) - **`RetainedTuiLoop`** — the retained-mode loop. Renders the tree into a `VirtualTerminalBuffer`, diffs it against the previous frame, and writes only the changed rows. An identical frame costs zero writes. It owns focus, key dispatch, session values, and the input buffer for the run. - **`VirtualTerminalBuffer`** — a fixed grid of cells that frames composite into. Its `diff()` is the whole reason this is a retained runtime rather than a redrawn one. - **`SimpleTuiLayoutEngine`** — resolves a `TuiNode` tree into absolute bounds plus a paint order, clipped to the viewport, so a renderer is handed the rectangle it may paint and never computes geometry itself. - **23 node renderers** — `data-table`, `select-list`, `settings-list`, `editor`, `text-input`, `markdown`, `log-view`, `job-monitor`, `command-palette`, `progress-bar`, `loader`, `cancellable-loader`, `box`, `badge`, `divider`, `spacer`, `text`, `image`, `status-bar`, `milpa-logo`, plus the structural and fallback ones. Each is pure: node plus bounds in, lines out. - **Editor-grade input** — `InputBuffer` (partial escape sequences held across reads), `Key`(modifier naming), `KeyMatcher`, `BracketedPaste`, `WordNavigation`, `KillRing`, `UndoStack`, and `Grapheme`/`TuiString` for cell-accurate width. - **`TuiComponentRenderer`** — renders a Live component to the terminal, the counterpart of the HTML renderers in `milpa/live-web`. Same component definition, same state snapshot, different target: this is the seam that lets one component description serve both surfaces. Two rules the renderers keep ---------------------------- [](#two-rules-the-renderers-keep) **Width is measured in cells, never bytes.** Everything goes through `TuiString`, which ignores ANSI sequences and counts wide graphemes as the columns they really take. The buffer composites at bounds *without clamping*, so a renderer that mismeasured would not produce a wrong string — it would corrupt neighbouring cells. **Dispatch is on shape, never on identity.** A renderer decides by the node's declared `type`; the registry asks each renderer in turn and the first match wins. An unknown type resolves to `null`rather than being guessed at. Nothing in this package knows which section of which application it is drawing. Quick example ------------- [](#quick-example) ``` use Milpa\Live\Tui\NodeRenderers\DataTableRenderer; use Milpa\Live\ValueObjects\Tui\{TuiBounds, TuiNode, TuiRenderContext}; $frame = (new DataTableRenderer())->render( new TuiNode('routes', 'data-table', props: [ // `columns` are declarations, not labels: a list of plain strings // renders nothing. 'columns' => [ ['key' => 'method', 'label' => 'method'], ['key' => 'path', 'label' => 'path'], ], 'rows' => [ ['method' => 'GET', 'path' => '/'], ['method' => 'PUT', 'path' => '/agency/api/account'], ], ]), new TuiRenderContext(new TuiBounds(0, 0, 48, 6)), ); echo implode(PHP_EOL, $frame->lines); ``` And the retained core, which is what the loop is built on: ``` use Milpa\Live\Tui\VirtualTerminalBuffer; $previous = new VirtualTerminalBuffer(80, 24); $current = new VirtualTerminalBuffer(80, 24); $current->writeFrame($bounds, $frame); foreach ($current->diff($previous)->changes as $change) { // Only these rows ever reach the terminal. printf("\033[%d;1H%s", $change['row'] + 1, $change['line']); } ``` What's inside ------------- [](#whats-inside) NamespaceWhat it provides`Milpa\Live\Tui``RetainedTuiLoop`, `InteractiveTuiLoop`, `RetainedTuiRenderer`, `VirtualTerminalBuffer`, `SimpleTuiLayoutEngine`, `TuiNodeRendererRegistry`, `TuiAnsiPainter`, `StreamTerminal`, `FocusManager`, `TerminalTheme`, `TuiString`, `Grapheme`, `InputBuffer`, `Key`, `KeyMatcher``Milpa\Live\Tui\NodeRenderers`The 23 renderers, plus `AbstractTuiNodeRenderer` with the shared box/fit/pad helpers`Milpa\Live\Rendering``TuiComponentRenderer` — the Live-component-to-terminal renderer`Milpa\Live\Contracts\Tui``TerminalInterface`, `VirtualTerminalBufferInterface`, `TuiLayoutEngineInterface`, `TuiNodeRendererInterface`, `TuiNodeRendererRegistryInterface`, `FocusManagerInterface`, `FocusableInterface`, `ShortcutRegistryInterface`, `TuiEventBusInterface`, `TuiStateManagerInterface`, `BackgroundJobManagerInterface`, `AutocompleteProviderInterface`, `TerminalThemeInterface``Milpa\Live\ValueObjects\Tui``TuiNode`, `TuiBounds`, `TuiFrame`, `TuiLayoutFrame`, `TuiBufferDiff`, `TuiRenderContext`, `TuiEvent`, `ShortcutBinding`, `BackgroundJob`Every public symbol carries a DocBlock — 79 types, 240 public methods, enforced by CI. Requirements ------------ [](#requirements) - PHP **≥ 8.3** - [`milpa/core`](https://packagist.org/packages/milpa/core) **^0.6** - [`milpa/live`](https://packagist.org/packages/milpa/live) **^0.1** No terminal extension is required. `ext-pcntl` is used opportunistically for `SIGWINCH` resize handling and its absence only costs you live resize. What this package does not claim yet ------------------------------------ [](#what-this-package-does-not-claim-yet) Stated plainly, because the package is `0.x` and the evidence behind it is specific: - The **interactive loop has not been exercised against a real terminal** in CI. What the test suite covers is the buffer diff, the layout engine, the renderers, the registry, and the value objects' invariants — 27 tests. Keyboard handling, resize, and the run loop are verified by use, not by tests. - `milpa/live` is pinned at **`^0.1`**, which is pre-1.0 on both sides. Documentation ------------- [](#documentation) **Full API reference: [getmilpa.github.io/live-tui](https://getmilpa.github.io/live-tui/)** — generated straight from the source DocBlocks and dressed with the Milpa design system. Contributing ------------ [](#contributing) Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). Please report security issues via [SECURITY.md](SECURITY.md), and note that this project follows a [Code of Conduct](CODE_OF_CONDUCT.md). License ------- [](#license) [Apache-2.0](LICENSE) © Rodrigo Vicente - TeamX Agency. --- Milpa is designed, built, and maintained by **[Rodrigo Vicente - TeamX Agency](https://teamx.agency/?utm_source=github&utm_medium=readme&utm_campaign=milpa&utm_content=live-tui)**. ### Health Score 41 — FairBetter than 87% of packages Maintenance100 Actively maintained with recent releases Popularity7 Limited adoption so far Community8 Small or concentrated contributor base Maturity42 Maturing project, gaining track record Bus Factor1 Top contributor holds 75% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~0 days Total 5 Last Release 1d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/1993784?v=4)[rodrigomx](/maintainers/rodrigomx)[@rodrigomx](https://github.com/rodrigomx) --- Top Contributors [![rodrigoteamx](https://avatars.githubusercontent.com/u/269849276?v=4)](https://github.com/rodrigoteamx "rodrigoteamx (18 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (6 commits)") ### Code Quality TestsPHPUnit Static AnalysisPHPStan Code StylePHP CS Fixer Type Coverage Yes ### Embed Badge ![Health badge](/badges/milpa-live-tui/health.svg) ``` [![Health](https://phpackages.com/badges/milpa-live-tui/health.svg)](https://phpackages.com/packages/milpa-live-tui) ``` PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)