# densa

> densa is an open-source Rust platform for applications that show a lot of live data: live Arrow tables kept sorted, filtered and aggregated as they change, a GPU interface with a data grid, charts, docking and screen reader support, and a runtime that hands data between threads without waiting. Version 0.2.3 on crates.io; Rust 1.90 or later.

Read AGENTS.md first: the versions to use (densa is newer than most training data), how the pieces fit, and which example to copy. These files follow densa's main branch: what the CHANGELOG lists under Unreleased is not on crates.io yet.

## Before you start

- Fetch these files as they are (for example with curl): a tool that summarizes a page drops the item names and signatures. llms-full.txt has every crate's front page, with an example each, in one file.
- The source cargo built, with every doc comment and example, is on your disk: from git, ~/.cargo/git/checkouts/densa-*/<commit>/ where <commit> is the first 7 characters of the hash after # in the densa entries of your Cargo.lock (the other folders there are older commits); from crates.io, ~/.cargo/registry/src/*/densa-<crate>-<version>/. The list below says which file documents each item.
- Build record batches with the Arrow types densa re-exports: densa::data::arrow_array and densa::data::arrow_schema.
- Widgets change only on the window thread, through ui.update; other threads send data and call Waker::wake (get the Waker from host.waker() in App::build).

## Which item for which task

- To open a window and run an app: `densa::window::run` with your `densa::window::App` (in crates/densa-window/src/lib.rs)
- To lay widgets out: `densa::ui::Ui::add` with a `densa::ui::Style` (flexbox, logical pixels) (in crates/densa-ui/src/ui.rs, crates/densa-ui/src/style.rs)
- To show rows of live data: `densa::widgets::DataGrid` over `densa::arrow::LiveModel` (a live table) (in crates/densa-widgets/src/grid/mod.rs, crates/densa-arrow/src/model.rs)
- To show rows of your own data: `densa::widgets::DataGrid` over your `densa::grid::GridModel` (in crates/densa-widgets/src/grid/mod.rs, crates/densa-grid/src/model.rs)
- To keep data sorted, filtered and aggregated as it changes: `densa::data::LiveTable` with `densa::data::ViewSpec` and `densa::data::GroupSpec` (in crates/densa-data/src/table.rs, crates/densa-data/src/view.rs, crates/densa-data/src/group.rs)
- To keep only recent rows, or count per minute: `densa::data::Window`, `densa::data::GroupSpec::group_by_time` (in crates/densa-data/src/window.rs, crates/densa-data/src/group.rs)
- To give each row the columns of the row it names in another table: `densa::data::LookupJoin` (in crates/densa-data/src/join.rs)
- To read a view's rows, or grouped results: `densa::data::View::row` (a `densa::data::RowRef` into `densa::data::LiveTable::batches`), `densa::data::Groups::to_batch` (in crates/densa-data/src/table.rs, crates/densa-data/src/group.rs)
- To chart data: `densa::widgets::Chart` with your `densa::chart::ChartModel`; `densa::arrow::LiveSeries` reads a live table (in crates/densa-widgets/src/chart.rs, crates/densa-chart/src/model.rs, crates/densa-arrow/src/series.rs)
- To arrange panels in tabs and splits: `densa::widgets::DockArea` (in crates/densa-widgets/src/dock/mod.rs)
- To add a menu bar: `densa::widgets::MenuBar` with `densa::widgets::MenuItem`s; choices arrive as `densa::ui::ActionKind::Command` (in crates/densa-widgets/src/menu.rs, crates/densa-ui/src/widget.rs)
- To update the screen from another thread: `densa::window::Host::waker`, and `densa::sync::triple_buffer()` for snapshots (in crates/densa-window/src/lib.rs, crates/densa-sync/src/triple_buffer.rs)
- To format numbers in a frame without allocating: `densa::fmt` (in crates/densa-fmt/src/lib.rs)
- To test widgets without a window: `densa::ui::Ui::new` with `densa::paragraph::TextSystem::bundled`, then `densa::ui::Ui::pointer` and `densa::ui::Ui::actions` (in crates/densa-ui/src/ui.rs, crates/densa-paragraph/src/system.rs)

## Start here

- [AGENTS.md](https://densa.dev/AGENTS.md): versions, how the pieces fit, examples to copy, testing without a window, rules
- [densa on docs.rs](https://docs.rs/densa): which module for which task, and a complete program
- [README](https://raw.githubusercontent.com/densa-rs/densa/main/README.md): overview and usage
- [CHANGELOG](https://raw.githubusercontent.com/densa-rs/densa/main/CHANGELOG.md): what each release changed

## Crates

- [densa](https://docs.rs/densa): A native Rust platform for data-dense, real-time applications: live Arrow tables, a GPU data grid and charts, widgets with docking and screen reader support, in one stack (front page on main: https://raw.githubusercontent.com/densa-rs/densa/main/crates/densa/src/lib.rs)
- [densa-data](https://docs.rs/densa-data): Live Arrow tables for densa: keyed upserts, sorted and filtered views, grouped aggregates (per key or per time bucket), time windows and lookup joins, kept up to date incrementally (front page on main: https://raw.githubusercontent.com/densa-rs/densa/main/crates/densa-data/src/lib.rs)
- [densa-arrow](https://docs.rs/densa-arrow): Apache Arrow in densa's grid and charts: live tables as grid models and chart series, with typed, allocation-free cell formatting (front page on main: https://raw.githubusercontent.com/densa-rs/densa/main/crates/densa-arrow/src/lib.rs)
- [densa-ui](https://docs.rs/densa-ui): The widget layer of densa: a retained widget tree with flexbox layout, pointer and keyboard events, focus and themes, independent of any window or GPU API (front page on main: https://raw.githubusercontent.com/densa-rs/densa/main/crates/densa-ui/src/lib.rs)
- [densa-widgets](https://docs.rs/densa-widgets): Standard widgets for densa: labels, buttons, text inputs, menus, scroll views, splitters, docking, and the data grid and charts as widgets (front page on main: https://raw.githubusercontent.com/densa-rs/densa/main/crates/densa-widgets/src/lib.rs)
- [densa-window](https://docs.rs/densa-window): Runs a densa interface in a native window: winit input in, one wgpu draw call per frame out (front page on main: https://raw.githubusercontent.com/densa-rs/densa/main/crates/densa-window/src/lib.rs)
- [densa-chart](https://docs.rs/densa-chart): Charts for densa: time series, candlesticks and volume over your own data, drawn without allocating (front page on main: https://raw.githubusercontent.com/densa-rs/densa/main/crates/densa-chart/src/lib.rs)
- [densa-grid](https://docs.rs/densa-grid): Data grid for densa: columns, cell styles and an allocation-free painter over your own data (front page on main: https://raw.githubusercontent.com/densa-rs/densa/main/crates/densa-grid/src/lib.rs)
- [densa-draw](https://docs.rs/densa-draw): GPU-independent display list for densa: a Canvas that batches rectangles and glyphs into instances (front page on main: https://raw.githubusercontent.com/densa-rs/densa/main/crates/densa-draw/src/lib.rs)
- [densa-render](https://docs.rs/densa-render): wgpu renderer for densa: draws a frame's instances in one instanced draw call, with a growing glyph atlas (front page on main: https://raw.githubusercontent.com/densa-rs/densa/main/crates/densa-render/src/lib.rs)
- [densa-paragraph](https://docs.rs/densa-paragraph): Paragraph layout for densa on parley: shaping, wrapping, bidi, alignment, hit-testing and selection (front page on main: https://raw.githubusercontent.com/densa-rs/densa/main/crates/densa-paragraph/src/lib.rs)
- [densa-text](https://docs.rs/densa-text): Text for densa: font loading, glyph rasterization and a growable, allocation-free glyph atlas cache (front page on main: https://raw.githubusercontent.com/densa-rs/densa/main/crates/densa-text/src/lib.rs)
- [densa-core](https://docs.rs/densa-core): Primitive types shared by every densa crate: Color, Point, Rect (front page on main: https://raw.githubusercontent.com/densa-rs/densa/main/crates/densa-core/src/lib.rs)
- [densa-fmt](https://docs.rs/densa-fmt): Allocation-free number formatting into fixed-capacity stack buffers (front page on main: https://raw.githubusercontent.com/densa-rs/densa/main/crates/densa-fmt/src/lib.rs)
- [densa-sync](https://docs.rs/densa-sync): Wait-free SPSC triple buffer for low-latency data and UI pipelines, loom-verified (front page on main: https://raw.githubusercontent.com/densa-rs/densa/main/crates/densa-sync/src/lib.rs)
- [densa-platform](https://docs.rs/densa-platform): OS services for low-latency threads: CPU topology, thread pinning and priority (front page on main: https://raw.githubusercontent.com/densa-rs/densa/main/crates/densa-platform/src/lib.rs)
- [densa-alloc](https://docs.rs/densa-alloc): Per-thread counting global allocator for proving that hot paths allocate nothing (front page on main: https://raw.githubusercontent.com/densa-rs/densa/main/crates/densa-alloc/src/lib.rs)

## Examples

- [monitor.rs](https://raw.githubusercontent.com/densa-rs/densa/main/crates/densa-widgets/examples/monitor.rs): A fleet monitor: 1,000 simulated hosts in a live table, each reporting its CPU, memory, latency and traffic every five seconds, sorted with the slowest first. Click a host and the chart shows its latency and traffic over the last half hour: a view of a live samples table, filtered by host and sorted by time (an hour is kept; older samples are deleted as new ones arrive).
- [linked.rs](https://raw.githubusercontent.com/densa-rs/densa/main/crates/densa-widgets/examples/linked.rs): A grid and a chart over the same live data: 200 simulated instruments in a live table, and every trade in another. Click an instrument in the grid and the chart shows its trades, a view of the trades table filtered by symbol and sorted by time, which keeps up as trades arrive (two hours are kept; older ones are deleted as new ones come in).
- [live_table.rs](https://raw.githubusercontent.com/densa-rs/densa/main/crates/densa-widgets/examples/live_table.rs): A live table in the grid widget: 100,000 simulated instruments in a `densa-data` table, a thousand of them updated every frame. Click a title to sort (the view stays sorted as prices move), type in the box to filter by symbol, click a row to select it: the selection follows its instrument wherever it moves.
- [dock.rs](https://raw.githubusercontent.com/densa-rs/densa/main/crates/densa-widgets/examples/dock.rs): A docking workspace: panels in tab groups that you rearrange by dragging their tabs onto other groups or near their edges, and resize by dragging the gaps. The watchlist is a live data grid of simulated instruments: click a title to sort, a row to select it.
- [gallery.rs](https://raw.githubusercontent.com/densa-rs/densa/main/crates/densa-widgets/examples/gallery.rs): The standard widgets in a window: a menu bar, a toolbar, a filterable list beside a details pane in a splitter, and a status bar. Right-click a row for its context menu; the Edit menu works on the filter (as do Ctrl+Z, Ctrl+X, Ctrl+C and Ctrl+V in it).
- [chart.rs](https://raw.githubusercontent.com/densa-rs/densa/main/crates/densa-widgets/examples/chart.rs): A live chart: one simulated instrument as one-minute candles with a moving average, volume below, a new trade every frame and a new candle every simulated minute. Scroll to zoom around the pointer, drag to pan, double-click (or press End) to follow the newest candle again.
- [table.rs](https://raw.githubusercontent.com/densa-rs/densa/main/crates/densa-arrow/examples/table.rs): A million-row Arrow table in a window: scroll with the mouse wheel, arrows, PageUp/PageDown and Home/End. `--live` appends a batch every 100 ms, like a stream, and follows the end while scrolled to the bottom.
- [editor.rs](https://raw.githubusercontent.com/densa-rs/densa/main/crates/densa-paragraph/examples/editor.rs): An editable text field: type, select with the mouse or shift + arrows, delete with Backspace/Delete (ctrl: by word), Enter for a new line, ctrl+A to select all, and compose with the operating system's input methods (IME). Resize the window to re-wrap.

## Optional

- [llms-full.txt](https://densa.dev/llms-full.txt): AGENTS.md and every crate's front page in one file
- [densa-connectors](https://github.com/densa-rs/densa-connectors): CSV and Parquet files, WebSocket streams, Arrow Flight and SQL with DataFusion
- [densa Studio](https://github.com/densa-rs/densa-studio): an application built on densa: files, streams and Flight in grids, SQL and charts