Headless flex layout engine for terminal UIs. Pure TypeScript, zero runtime dependencies.

📖 API reference

Pilates is a flex layout engine designed for the terminal: integer cell coordinates, CJK / emoji / wide-char awareness, ANSI escape passthrough, and unbundled from any UI framework. Use it directly to compute layouts, or wrap the included renderer to produce styled strings.

import { render } from '@pilates/render';

process.stdout.write(
  render({
    width: 80,
    height: 6,
    flexDirection: 'row',
    children: [
      { flex: 1, border: 'rounded', title: 'Logs',   children: [{ text: 'user logged in' }] },
      { width: 20, border: 'single', title: 'Status', children: [{ text: 'ok', color: 'green', bold: true }] },
    ],
  }),
);
// ╭─ Logs ───────────────────────────────────────────────────╮┌─ Status ─────────┐
// │user logged in                                            ││ok                │
// │                                                          ││                  │
// │                                                          ││                  │
// ╰──────────────────────────────────────────────────────────╯└──────────────────┘

Why

Terminal UIs in JavaScript are dominated by Ink, which couples two distinct concerns into one package: a WASM flex layout engine and a React reconciler. If you want the layout half, you have to take all of React. Pilates separates them:

• @pilates/core — the engine. Imperative Node API, returns integer cell coordinates. Pure TypeScript, zero runtime dependencies. Handles CJK / emoji / wide-char widths, integer-cell rounding, the CSS Flexbox freeze loop, and absolute positioning. Validated cell-for-cell against a reference WASM flexbox implementation across 33 oracle fixtures.
• @pilates/render — the out-of-box renderer. Declarative POJO tree → painted ANSI string with borders, titles, colors, and text wrap. Uses core internally; depends only on it.
• @pilates/diff — cell-level frame diffing + minimal ANSI redraw sequences for live TUIs. Pairs with @pilates/render.
• @pilates/react — optional React reconciler on top of the same engine, for consumers who want JSX and hooks. Independent of the core / render / diff stack — you don't pay for it if you don't import it.
• @pilates/widgets — interactive widgets (TextInput, Select, Spinner) built on @pilates/react. For wizard-style CLI flows.

Packages

Examples

Eleven runnable examples live under examples/ — six built on the imperative @pilates/render API, five built on @pilates/react.

Imperative (@pilates/render):

React (@pilates/react + @pilates/widgets):

pnpm install
# imperative
pnpm --filter @pilates-examples/chat-log dev
pnpm --filter @pilates-examples/progress-table dev
# react
pnpm --filter @pilates-examples/react-counter dev
pnpm --filter @pilates-examples/react-wizard dev
# flagship
pnpm --filter @pilates-examples/react-build-dashboard dev

Quick start (using just the engine)

import { Node, Edge } from '@pilates/core';

const root = Node.create();
root.setFlexDirection('row');
root.setWidth(80);
root.setHeight(24);
root.setPadding(Edge.All, 1);

const main = Node.create();
main.setFlex(1);
const sidebar = Node.create();
sidebar.setWidth(20);

root.insertChild(main, 0);
root.insertChild(sidebar, 1);
root.calculateLayout();

main.getComputedLayout();    // { left:1, top:1, width:58, height:22 }
sidebar.getComputedLayout(); // { left:59, top:1, width:20, height:22 }

You'd then paint to the terminal yourself — or pass the same shape via the declarative API to @pilates/render to skip the painting:

import { render } from '@pilates/render';

process.stdout.write(
  render({
    width: 80,
    height: 24,
    flexDirection: 'row',
    padding: 1,
    children: [{ flex: 1 }, { width: 20 }],
  }),
);

What's supported

Out of v1: aspectRatio, RTL/LTR direction inheritance, baseline alignment, input handling, animations, scroll containers, style inheritance.

Performance

Pure-TypeScript layout, validated cell-for-cell against WASM Yoga. Across the 9 scenarios in our bench suite, the pure-TS engine is faster than WASM Yoga on each — including the structural-mutation workload (append + remove a row per frame) Yoga led on through mid-2026. Numbers are median latency from pnpm bench (Node 22, win32-x64, ~5s tinybench window with bootstrap CI95; a hand-picked suite, not a universal claim — real workloads will differ):

The hot-relayout and hot-structural patterns — building a tree once and mutating-and-relaying out per frame — are the workloads Yoga's WASM compute advantage traditionally won on. The Spineless incremental layout engine (an attribute-grammar dependency graph + priority-queue recomputation; refined through phases 8–17 with a typed-array runtime, linear-recurrence main-axis positions, and fold-default input elimination) flips that: a single leaf mutation re-evaluates only the fields actually downstream of the change, and structural mutations patch only the affected subtree.

For trees of pure fixed-size cells (e.g. a data table with one cell's text length changing per frame), the direct @pilates/core (spineless) runtime mutation goes through in ~0.2µs — 380× faster than the Yoga round-trip. That path is @internal for now; the public calculateLayout ships the engine and is what every other Pilates consumer uses.

WASM Yoga's compute kernel is genuinely fast in isolation, but every setProperty / Node.create crosses the JS↔WASM boundary; that marshalling cost dominates at TUI tree sizes (10–10k nodes), and the Spineless engine's incremental recompute then beats WASM's per-frame full layout. Pure-TS Pilates pays no marshalling cost.

Reproduce with pnpm bench. Full numbers + scenario shapes in bench/RESULTS.md.

Validation

Every flex feature is verified cell-for-cell against a reference WASM flexbox implementation:

• 33 oracle fixtures (fixed widths, flex distributions, padding, margin, gap, min/max, all justifyContent / alignItems / alignSelf / alignContent values, flexWrap, flexWrap: wrap-reverse, every absolute positioning anchor)
• 200+ unit + algorithm + render tests
• Unicode width fuzzer running through 200 randomized strings against @xterm/headless per CI run, plus a fixture set of pinned agreement cases and documented divergences (where modern terminals render wider than xterm.js's Unicode-11 tables)
• Property-based fuzz with fast-check over layout invariants — non-overflow, sibling non-overlap, reproducibility — across randomly generated trees

Notable design choices

• Default flexShrink: 0 in core (React Native convention, not CSS's 1) — declared widths stay declared. The render layer flips this to 1 for text leaves so wrapped text fits its container.
• Absolute offsets are relative to the parent's outer box, not its content (post-padding) box — React Native semantics, not CSS. Keeps consumers porting from Ink / RN consistent.
• Integer cell rounding rounds absolute corners and derives size from rounded edges — sibling boxes butt cleanly across uneven splits ([100, flex:1, flex:1, flex:1] → [34, 33, 33]).

Status

@pilates/core@2.0.1 is on npm. Core algorithm + flex pipeline are feature-complete, validated cell-for-cell against WASM Yoga, and faster than Yoga on each of the 9 scenarios in the bench suite (see Performance above) — powered by the Spineless incremental engine. The React layer ships mouse, scroll, focus management, typed errors, and layout devtools.

Contributing

Issues, discussions, and PRs welcome. Start with CONTRIBUTING.md for setup, the test loop, and what the maintainer expects from layout-algorithm changes (oracle-fixture coverage). By participating you agree to follow the Code of Conduct. Security issues: see SECURITY.md for the private disclosure channel.

License

MIT © Zhijie Wang.