>_ENGINEERING REPORT
arb is an original language for visualizing and modifying Unix pipelines — pipe a stream in and it spawns a dynamic TUI (ratatui) or, later, a served web page (zgui) from a declarative spec. It targets the fusevm bytecode VM and its three-tier Cranelift JIT. This report describes the positioning, the target architecture, and the current state of the tree. The statements below are facts about the design and the manifest, not aspirational metrics.
Summary
A pipeline dumps text at you; arb turns it into an interface. Drop arb into a pipe and a small declarative spec — Tcl/Tk-flavored, but not Tcl — describes widgets, layout, a uniform query over any format, and interactive controls. Those controls feed back into the passthrough, so arb can sit mid-pipe and shape what the downstream consumer receives, not just display it. It joins fusevm alongside zshrs, stryke, rubyrs, and elisp, reusing that shared bytecode VM and JIT rather than shipping its own.
arb is an original language in stryke's class — not a port, and deliberately lean (rubyrs-scale, not stryke-scale). It is early. M0 ships the zero-config live-tail — find / | arb renders the stream in a full-screen ratatui TUI with a live count and rate, degrading to a headless summary with no controlling terminal on stdout. M1 adds the Tcl-flavored reader and the declarative widget/source interpreter with multi-widget render; M2 (in progress) builds out the source query pipeline — in, match/grep, reject/grepv, field N/field NAME, count, rate, tally over line and JSON streams (in.json, nested key paths) — with per-widget derived data rendering into gauge/bars/histo. The expression layer, fusevm lowering, the full query surface, the web target, actors, and the package manager arrive across the later milestones specified in SPEC.md. Nothing is faked — unrecognized widget verbs are ignored for forward compatibility, and unbuilt features are absent, not stubbed.
World-first positioning
The novelty is the synthesis and the ecosystem, not any single leg. Every capability has prior art on its own:
Prior art per leg
Tcl / Tk (1988), Expect (1990, spawn/react), dasel (unified query), ratatui (TUI), Streamlit / textual serve (served web UI), filt (interactive pipe grep — single filter box, filter-only, TUI-only).
The combination is new
No tool is a pipe-native, dual-target (terminal + web), component-generating UI language with a shareable dashboard registry. arb is that combination.
Ecosystem leg
cmd | arb sniffs the upstream command or data shape → resolves the matching arb-<tool> package → renders. No registry of installable pipeline TUIs exists today.
Not a server
Terminal-invoked and pipe-driven. The web target spawns a local UI host on demand (like textual serve), not a daemon you run.
Target architecture on fusevm
arb is designed as a fusevm frontend: the spec is meant to lower to fusevm::Chunk bytecode and run on the shared VM + three-tier Cranelift JIT, while ratatui / zgui / query / actor behaviour is served by an extension-op host over a Value::Obj heap. The M1/M2 tree is still a direct interpreter — the reader builds a Spec that the ratatui backend renders and the query pipeline evaluates over the live stream; the fusevm lowering is a later milestone. The target execution path is:
arb spec → lexer → parser → AST → lower to fusevm bytecode → fusevm VM + Cranelift JIT
│
host: ratatui / zgui / query / actors
stream: stdin(.json/.xml/.html/.yaml/.toml/.csv)
Shared engine
Planned deps pull fusevm from crates.io with the jit, jit-disk-cache, and aot features. JIT and VM improvements land once and benefit zshrs, stryke, rubyrs, elisp, and arb together.
Mechanics reused, semantics original
Transfers from siblings are mechanics only — fusevm embedding, the rkyv cache, the LSP/DAP stdio shape, the package-manager ABI. The lexer, parser, AST, lowering, and semantics are arb-original.
One query engine
A single vocabulary (a jq/xpath/css/yq superset) works uniformly over JSON, XML, HTML, YAML, TOML, and CSV — field, each, find, attr, sel, where, and aggregates.
Megafilter/map passthrough
Interactive controls (filter, facet, slider) render AND feed out, so a control's path used as a value is its current state — arb filters and maps the downstream output live.
Milestones
arb lands in stages. M0–M2 are in the tree (M2 still expanding); everything past them is specified in SPEC.md and not yet built.
| Milestone | State | Scope |
|---|---|---|
| M0 · walking skeleton | Implemented | Zero-config live-tail TUI + headless summary; count/rate header, ring buffer, q/Esc/Ctrl-C (src/main.rs). |
| M1 · spec interpreter + widgets | Implemented | Tcl-flavored reader, declarative widget/source interp, .x <- in binds, multi-widget render (src/lexer.rs, src/parser.rs, src/ast.rs, src/spec.rs, src/tui.rs). |
| M2 · query pipeline + widgets (expanding) | Implemented | in, match/grep, reject/grepv, field N/field NAME, count, rate, tally over line and JSON streams (in.json, nested key paths); per-widget derived data into gauge/bars/histo (src/query.rs). |
| M2+ · presets / richer query | Planned | Modules, imports, preset dashboards; CSV/XML/HTML/YAML/TOML extraction, where(pred), sort / group / uniq. |
M3 · controls + out | Planned | Interactive controls that megafilter/map the passthrough. |
| M4 · Expect + events | Planned | Stream reactions (expect) and Tk-style bind events. |
| M5 · web target | Planned | Served zgui page + WebSocket live update (-t web). |
| M6 · actors | Planned | Akka-style actors, pools, ask/tell, stream fan-out. |
| M7 · package manager | Planned | Script + native packages, arb install/add/publish, the shared-dashboard registry. |
| M8 · LSP / DAP | Planned | Editor tooling over stdio JSON-RPC. |
Module layout
The present rows are in the tree today (a lib + bin: the front-end is unit-testable without a terminal); the planned rows are the target layout the later milestones fill in.
| File | State | Role |
|---|---|---|
| src/main.rs | present | Entry point. Loads a spec (or synthesizes a tail), wires stdin → ratatui or headless output. |
| src/lexer.rs | present | Tcl-flavored reader (original). |
| src/parser.rs | present | Widget commands + block grammar (original). |
| src/ast.rs | present | Command syntax tree. |
| src/spec.rs | present | Command tree → Spec (widgets, source pipelines, binds). |
| src/query.rs | present | Source query pipeline (M2 verbs; jq/xpath/css/yq surface grows here). |
| src/stream.rs | present | Live stream state feeding the widgets. |
| src/tui.rs | present | ratatui backend. |
| src/compiler.rs | planned | AST → fusevm::Chunk (original lowering). |
| src/host.rs | planned | Extension ops over a Value::Obj heap. |
| src/web.rs | planned | zgui codegen + WS server (feature: web). |
| src/actor.rs | planned | Akka-style runtime (feature: actors). |
| src/module.rs | planned | import / resolution. |
| src/pkg.rs | planned | Package manager (arb.toml, install/publish). |
| src/cache.rs | planned | rkyv bytecode cache under ~/.arb/. |
| src/lsp.rs / src/dap.rs | planned | stdio JSON-RPC (shape reused from siblings). |
Dependency posture
arb is a standalone crate (MIT). The current manifest is deliberately minimal — ratatui 0.29 (with its crossterm backend), clap 4.5, and regex 1 for the match/reject verbs. Later milestones add fusevm{jit,jit-disk-cache,aot}, rkyv/bincode/memmap2 for the cache, the format parsers (serde_json / quick-xml / serde_yaml / toml / csv + html), and feature-gated async http + ws for the web target. Release builds use lto = true and strip = true.
License
arb is MIT licensed — free and open source. See LICENSE.